| Message ID | 1477962314-26763-3-git-send-email-tomas.winkler@intel.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
On Tue, Nov 01, 2016 at 03:05:14AM +0200, Tomas Winkler wrote: > Use correct kdoc format, describe correct parameters and return values. > > Signed-off-by: Tomas Winkler <tomas.winkler@intel.com> > --- > drivers/char/tpm/tpm2-cmd.c | 107 +++++++++++++++++++++++++++----------------- > 1 file changed, 66 insertions(+), 41 deletions(-) > > diff --git a/drivers/char/tpm/tpm2-cmd.c b/drivers/char/tpm/tpm2-cmd.c > index 7df55d58c939..a7a519c87bee 100644 > --- a/drivers/char/tpm/tpm2-cmd.c > +++ b/drivers/char/tpm/tpm2-cmd.c > @@ -258,11 +258,13 @@ static const struct tpm_input_header tpm2_pcrread_header = { > * tpm2_pcr_read() - read a PCR value > * @chip: TPM chip to use. > * @pcr_idx: index of the PCR to read. > - * @ref_buf: buffer to store the resulting hash, > + * @res_buf: buffer to store the resulting hash, > * > - * 0 is returned when the operation is successful. If a negative number is > - * returned it remarks a POSIX error code. If a positive number is returned > - * it remarks a TPM error. > + * > + * Return: > + * 0 when the operation is successful > + * A negative number for system errors (errno) > + * A positive number for a TPM error. > */ > int tpm2_pcr_read(struct tpm_chip *chip, int pcr_idx, u8 *res_buf) > { > @@ -304,13 +306,15 @@ static const struct tpm_input_header tpm2_pcrextend_header = { > > /** > * tpm2_pcr_extend() - extend a PCR value > + * > * @chip: TPM chip to use. > * @pcr_idx: index of the PCR. > * @hash: hash value to use for the extend operation. > * > - * 0 is returned when the operation is successful. If a negative number is > - * returned it remarks a POSIX error code. If a positive number is returned > - * it remarks a TPM error. > + * Return: > + * 0 when the operation is successful > + * A negative number for system errors (errno) > + * A positive number for a TPM error. Put this to tpm_transmit_cmd only and refer to that from other functions with "same as with tpm_transmit_cmd()" with parenthesis because that marks in rst a link to that function. /Jarkko ------------------------------------------------------------------------------ Developer Access Program for Intel Xeon Phi Processors Access to Intel Xeon Phi processor-based developer platforms. With one year of Intel Parallel Studio XE. Training and support from Colfax. Order your platform today. http://sdm.link/xeonphi
.org > Subject: Re: [PATCH 2/2] tpm/tpm2-chip: fix kdoc errors > > On Tue, Nov 01, 2016 at 03:05:14AM +0200, Tomas Winkler wrote: > > Use correct kdoc format, describe correct parameters and return values. > > > > Signed-off-by: Tomas Winkler <tomas.winkler@intel.com> > > --- > > drivers/char/tpm/tpm2-cmd.c | 107 > > +++++++++++++++++++++++++++----------------- > > 1 file changed, 66 insertions(+), 41 deletions(-) > > > > diff --git a/drivers/char/tpm/tpm2-cmd.c b/drivers/char/tpm/tpm2-cmd.c > > index 7df55d58c939..a7a519c87bee 100644 > > --- a/drivers/char/tpm/tpm2-cmd.c > > +++ b/drivers/char/tpm/tpm2-cmd.c > > @@ -258,11 +258,13 @@ static const struct tpm_input_header > tpm2_pcrread_header = { > > * tpm2_pcr_read() - read a PCR value > > * @chip: TPM chip to use. > > * @pcr_idx: index of the PCR to read. > > - * @ref_buf: buffer to store the resulting hash, > > + * @res_buf: buffer to store the resulting hash, > > * > > - * 0 is returned when the operation is successful. If a negative > > number is > > - * returned it remarks a POSIX error code. If a positive number is > > returned > > - * it remarks a TPM error. > > + * > > + * Return: > > + * 0 when the operation is successful > > + * A negative number for system errors (errno) > > + * A positive number for a TPM error. > > */ > > int tpm2_pcr_read(struct tpm_chip *chip, int pcr_idx, u8 *res_buf) { > > @@ -304,13 +306,15 @@ static const struct tpm_input_header > > tpm2_pcrextend_header = { > > > > /** > > * tpm2_pcr_extend() - extend a PCR value > > + * > > * @chip: TPM chip to use. > > * @pcr_idx: index of the PCR. > > * @hash: hash value to use for the extend operation. > > * > > - * 0 is returned when the operation is successful. If a negative > > number is > > - * returned it remarks a POSIX error code. If a positive number is > > returned > > - * it remarks a TPM error. > > + * Return: > > + * 0 when the operation is successful > > + * A negative number for system errors (errno) > > + * A positive number for a TPM error. > > Put this to tpm_transmit_cmd only and refer to that from other functions with > "same as with tpm_transmit_cmd()" with parenthesis because that marks in rst > a link to that function. And then tpm_transmit_cmd() will point to tpm_transmit() ? I'm not sure I'm happy about those links, rst is okay but after all mostly we're just looking directly to the sources with a simple editor. Anyhow this patch is to resolve the kdoc syntax bug, the overhaul of the documentation can be built on top of it. Thanks Tomas ------------------------------------------------------------------------------ Developer Access Program for Intel Xeon Phi Processors Access to Intel Xeon Phi processor-based developer platforms. With one year of Intel Parallel Studio XE. Training and support from Colfax. Order your platform today. http://sdm.link/xeonphi
On Mon, Nov 14, 2016 at 01:05:41PM +0000, Winkler, Tomas wrote: > .org > > Subject: Re: [PATCH 2/2] tpm/tpm2-chip: fix kdoc errors > > > > On Tue, Nov 01, 2016 at 03:05:14AM +0200, Tomas Winkler wrote: > > > Use correct kdoc format, describe correct parameters and return values. > > > > > > Signed-off-by: Tomas Winkler <tomas.winkler@intel.com> > > > --- > > > drivers/char/tpm/tpm2-cmd.c | 107 > > > +++++++++++++++++++++++++++----------------- > > > 1 file changed, 66 insertions(+), 41 deletions(-) > > > > > > diff --git a/drivers/char/tpm/tpm2-cmd.c b/drivers/char/tpm/tpm2-cmd.c > > > index 7df55d58c939..a7a519c87bee 100644 > > > --- a/drivers/char/tpm/tpm2-cmd.c > > > +++ b/drivers/char/tpm/tpm2-cmd.c > > > @@ -258,11 +258,13 @@ static const struct tpm_input_header > > tpm2_pcrread_header = { > > > * tpm2_pcr_read() - read a PCR value > > > * @chip: TPM chip to use. > > > * @pcr_idx: index of the PCR to read. > > > - * @ref_buf: buffer to store the resulting hash, > > > + * @res_buf: buffer to store the resulting hash, > > > * > > > - * 0 is returned when the operation is successful. If a negative > > > number is > > > - * returned it remarks a POSIX error code. If a positive number is > > > returned > > > - * it remarks a TPM error. > > > + * > > > + * Return: > > > + * 0 when the operation is successful > > > + * A negative number for system errors (errno) > > > + * A positive number for a TPM error. > > > */ > > > int tpm2_pcr_read(struct tpm_chip *chip, int pcr_idx, u8 *res_buf) { > > > @@ -304,13 +306,15 @@ static const struct tpm_input_header > > > tpm2_pcrextend_header = { > > > > > > /** > > > * tpm2_pcr_extend() - extend a PCR value > > > + * > > > * @chip: TPM chip to use. > > > * @pcr_idx: index of the PCR. > > > * @hash: hash value to use for the extend operation. > > > * > > > - * 0 is returned when the operation is successful. If a negative > > > number is > > > - * returned it remarks a POSIX error code. If a positive number is > > > returned > > > - * it remarks a TPM error. > > > + * Return: > > > + * 0 when the operation is successful > > > + * A negative number for system errors (errno) > > > + * A positive number for a TPM error. > > > > Put this to tpm_transmit_cmd only and refer to that from other functions with > > "same as with tpm_transmit_cmd()" with parenthesis because that marks in rst > > a link to that function. > > And then tpm_transmit_cmd() will point to tpm_transmit() ? For tpm_transmit() those error codes don't apply. It never returns TPM error codes. > I'm not sure I'm happy about those links, rst is okay but after all mostly we're just looking directly to the sources with a simple editor. > Anyhow this patch is to resolve the kdoc syntax bug, the overhaul of the documentation can be built on top of it. Do you know how could I easily get the rendered output for this? If I do make htmldocs. At least when I tried it, it generates only those kdoc comments that are imported to the rst files (like I do with tpm_vtmp_proxy). > Thanks > Tomas /Jarkko ------------------------------------------------------------------------------
diff --git a/drivers/char/tpm/tpm2-cmd.c b/drivers/char/tpm/tpm2-cmd.c index 7df55d58c939..a7a519c87bee 100644 --- a/drivers/char/tpm/tpm2-cmd.c +++ b/drivers/char/tpm/tpm2-cmd.c @@ -258,11 +258,13 @@ static const struct tpm_input_header tpm2_pcrread_header = { * tpm2_pcr_read() - read a PCR value * @chip: TPM chip to use. * @pcr_idx: index of the PCR to read. - * @ref_buf: buffer to store the resulting hash, + * @res_buf: buffer to store the resulting hash, * - * 0 is returned when the operation is successful. If a negative number is - * returned it remarks a POSIX error code. If a positive number is returned - * it remarks a TPM error. + * + * Return: + * 0 when the operation is successful + * A negative number for system errors (errno) + * A positive number for a TPM error. */ int tpm2_pcr_read(struct tpm_chip *chip, int pcr_idx, u8 *res_buf) { @@ -304,13 +306,15 @@ static const struct tpm_input_header tpm2_pcrextend_header = { /** * tpm2_pcr_extend() - extend a PCR value + * * @chip: TPM chip to use. * @pcr_idx: index of the PCR. * @hash: hash value to use for the extend operation. * - * 0 is returned when the operation is successful. If a negative number is - * returned it remarks a POSIX error code. If a positive number is returned - * it remarks a TPM error. + * Return: + * 0 when the operation is successful + * A negative number for system errors (errno) + * A positive number for a TPM error. */ int tpm2_pcr_extend(struct tpm_chip *chip, int pcr_idx, const u8 *hash) { @@ -348,13 +352,15 @@ static const struct tpm_input_header tpm2_getrandom_header = { /** * tpm2_get_random() - get random bytes from the TPM RNG + * * @chip: TPM chip to use * @out: destination buffer for the random bytes * @max: the max number of bytes to write to @out * - * 0 is returned when the operation is successful. If a negative number is - * returned it remarks a POSIX error code. If a positive number is returned - * it remarks a TPM error. + * Return: + * 0 when the operation is successful + * A negative number for system errors (errno) + * A positive number for a TPM error. */ int tpm2_get_random(struct tpm_chip *chip, u8 *out, size_t max) { @@ -404,15 +410,16 @@ static const struct tpm_input_header tpm2_get_tpm_pt_header = { }; /** - * Append TPMS_AUTH_COMMAND to the buffer. The buffer must be allocated with - * tpm_buf_alloc(). - * - * @param buf: an allocated tpm_buf instance - * @param nonce: the session nonce, may be NULL if not used - * @param nonce_len: the session nonce length, may be 0 if not used - * @param attributes: the session attributes - * @param hmac: the session HMAC or password, may be NULL if not used - * @param hmac_len: the session HMAC or password length, maybe 0 if not used + * tpm_buf_alloc() - Append TPMS_AUTH_COMMAND to the buffer. + * The buffer must be allocated with + * + * @buf: an allocated tpm_buf instance + * @session_handle: session handle + * @nonce: the session nonce, may be NULL if not used + * @nonce_len: the session nonce length, may be 0 if not used + * @attributes: the session attributes + * @hmac: the session HMAC or password, may be NULL if not used + * @hmac_len: the session HMAC or password length, maybe 0 if not used */ static void tpm2_buf_append_auth(struct tpm_buf *buf, u32 session_handle, const u8 *nonce, u16 nonce_len, @@ -435,7 +442,8 @@ static void tpm2_buf_append_auth(struct tpm_buf *buf, u32 session_handle, /** * tpm2_seal_trusted() - seal the payload of a trusted key - * @chip_num: TPM chip to use + * + * @chip: TPM chip to use * @payload: the key data in clear and encrypted form * @options: authentication values and other options * @@ -540,9 +548,12 @@ out: /** * tpm2_load_cmd() - execute a TPM2_Load command - * @chip_num: TPM chip to use + * + * @chip: TPM chip to use * @payload: the key data in clear and encrypted form * @options: authentication values and other options + * @blob_handle: returned blob handle + * @flags: tpm transmit flags * * Return: same as with tpm_transmit_cmd */ @@ -600,9 +611,10 @@ out: /** * tpm2_flush_context_cmd() - execute a TPM2_FlushContext command - * @chip_num: TPM chip to use - * @payload: the key data in clear and encrypted form - * @options: authentication values and other options + * + * @chip: TPM chip to use + * @handle: the key data in clear and encrypted form + * @flags: tpm transmit flags * * Return: same as with tpm_transmit_cmd */ @@ -632,9 +644,12 @@ static void tpm2_flush_context_cmd(struct tpm_chip *chip, u32 handle, /** * tpm2_unseal_cmd() - execute a TPM2_Unload command - * @chip_num: TPM chip to use + * + * @chip: TPM chip to use * @payload: the key data in clear and encrypted form * @options: authentication values and other options + * @blob_handle: blob handle + * @flags: tpm_transmit_cmd flags * * Return: same as with tpm_transmit_cmd */ @@ -681,7 +696,7 @@ static int tpm2_unseal_cmd(struct tpm_chip *chip, /** * tpm_unseal_trusted() - unseal the payload of a trusted key - * @chip_num: TPM chip to use + * @chip: TPM chip to use * @payload: the key data in clear and encrypted form * @options: authentication values and other options * @@ -750,13 +765,15 @@ static const struct tpm_input_header tpm2_startup_header = { /** * tpm2_startup() - send startup command to the TPM chip + * * @chip: TPM chip to use. - * @startup_type startup type. The value is either + * @startup_type: startup type. The value is either * TPM_SU_CLEAR or TPM_SU_STATE. * - * 0 is returned when the operation is successful. If a negative number is - * returned it remarks a POSIX error code. If a positive number is returned - * it remarks a TPM error. + * Return: + * 0 when the operation is successful + * A negative number for system errors (errno) + * A positive number for a TPM error. */ static int tpm2_startup(struct tpm_chip *chip, u16 startup_type) { @@ -782,7 +799,7 @@ static const struct tpm_input_header tpm2_shutdown_header = { /** * tpm2_shutdown() - send shutdown command to the TPM chip * @chip: TPM chip to use. - * @shutdown_type shutdown type. The value is either + * @shutdown_type: shutdown type. The value is either * TPM_SU_CLEAR or TPM_SU_STATE. */ void tpm2_shutdown(struct tpm_chip *chip, u16 shutdown_type) @@ -805,12 +822,14 @@ void tpm2_shutdown(struct tpm_chip *chip, u16 shutdown_type) /* * tpm2_calc_ordinal_duration() - maximum duration for a command + * * @chip: TPM chip to use. * @ordinal: command code number. * - * 0 is returned when the operation is successful. If a negative number is - * returned it remarks a POSIX error code. If a positive number is returned - * it remarks a TPM error. + * Return: + * 0 when the operation is successful + * A negative number for system errors (errno) + * A positive number for a TPM error. */ unsigned long tpm2_calc_ordinal_duration(struct tpm_chip *chip, u32 ordinal) { @@ -842,13 +861,15 @@ static const struct tpm_input_header tpm2_selftest_header = { /** * tpm2_continue_selftest() - start a self test + * * @chip: TPM chip to use * @full: test all commands instead of testing only those that were not * previously tested. * - * 0 is returned when the operation is successful. If a negative number is - * returned it remarks a POSIX error code. If a positive number is returned - * it remarks a TPM error. + * Return: + * 0 when the operation is successful + * A negative number for system errors (errno) + * A positive number for a TPM error. */ static int tpm2_start_selftest(struct tpm_chip *chip, bool full) { @@ -874,14 +895,16 @@ static int tpm2_start_selftest(struct tpm_chip *chip, bool full) /** * tpm2_do_selftest() - run a full self test + * * @chip: TPM chip to use * + * Return: + * 0 when the operation is successful + * A negative number for system errors (errno) + * A positive number for a TPM error. + * * During the self test TPM2 commands return with the error code RC_TESTING. * Waiting is done by issuing PCR read until it executes successfully. - * - * 0 is returned when the operation is successful. If a negative number is - * returned it remarks a POSIX error code. If a positive number is returned - * it remarks a TPM error. */ static int tpm2_do_selftest(struct tpm_chip *chip) { @@ -928,6 +951,8 @@ static int tpm2_do_selftest(struct tpm_chip *chip) * tpm2_probe() - probe TPM 2.0 * @chip: TPM chip to use * + * Return: same as with tpm_transmit_cmd + * * Send idempotent TPM 2.0 command and see whether TPM 2.0 chip replied based on * the reply tag. */
Use correct kdoc format, describe correct parameters and return values. Signed-off-by: Tomas Winkler <tomas.winkler@intel.com> --- drivers/char/tpm/tpm2-cmd.c | 107 +++++++++++++++++++++++++++----------------- 1 file changed, 66 insertions(+), 41 deletions(-)