Re: [PATCH 2/2] tpm/tpm2-chip: fix kdoc errors

[Jarkko Sakkinen]

On Mon, Nov 14, 2016 at 01:05:41PM +, 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.wink...@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

Re: [PATCH 2/2] tpm/tpm2-chip: fix kdoc errors

[Jarkko Sakkinen]

On Mon, Nov 14, 2016 at 01:05:41PM +, 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 
> > > ---
> > >  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

RE: [PATCH 2/2] tpm/tpm2-chip: fix kdoc errors

[Winkler, Tomas]

.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.wink...@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

RE: [PATCH 2/2] tpm/tpm2-chip: fix kdoc errors

[Winkler, Tomas]

.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 
> > ---
> >  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

Re: [PATCH 2/2] tpm/tpm2-chip: fix kdoc errors

[Jarkko Sakkinen]

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 
> ---
>  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

Re: [PATCH 2/2] tpm/tpm2-chip: fix kdoc errors

[Jarkko Sakkinen]

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 
> ---
>  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

[PATCH 2/2] tpm/tpm2-chip: fix kdoc errors

[Tomas Winkler]

Use correct kdoc format, describe correct parameters and return values.

Signed-off-by: Tomas Winkler 
---
 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.
  */
 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 

[PATCH 2/2] tpm/tpm2-chip: fix kdoc errors

[Tomas Winkler]

Use correct kdoc format, describe correct parameters and return values.

Signed-off-by: Tomas Winkler 
---
 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.
  */
 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