[PATCH v2 0/4] tpm: kdoc cleanup

[PATCH v2 0/4] tpm: kdoc cleanup

[Tomas Winkler]

Cleanup tpm in-code documentation.

Tomas Winkler (4):
  tpm: add kdoc for tpm_transmit and tpm_transmit_cmd
  tpm/tpm2-chip: fix kdoc errors
  tmp: use pdev for parent device in tpm_chip_alloc
  tpm/vtpm: fix kdoc warnings

 drivers/char/tpm/tpm-chip.c       |   8 +--
 drivers/char/tpm/tpm-interface.c  |  33 ++++++++++--
 drivers/char/tpm/tpm2-cmd.c       | 105 +++++++++++++++++++++-----------------
 drivers/char/tpm/tpm_ibmvtpm.c    |  51 +++++++++---------
 drivers/char/tpm/tpm_vtpm_proxy.c |  48 ++++++++++++-----
 5 files changed, 150 insertions(+), 95 deletions(-)

-- 
2.7.4

[PATCH v2 1/4] tpm: add kdoc for tpm_transmit and tpm_transmit_cmd

[Tomas Winkler]

Functions tpm_transmit and transmit_cmd are referenced
from other functions kdoc hence deserve documentation.

Signed-off-by: Tomas Winkler <tomas.winkler-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>
---
V2: Add some missing '.'
 drivers/char/tpm/tpm-interface.c | 33 ++++++++++++++++++++++++++++-----
 1 file changed, 28 insertions(+), 5 deletions(-)

diff --git a/drivers/char/tpm/tpm-interface.c b/drivers/char/tpm/tpm-interface.c
index a2688ac2b48f..769d8b0d31a3 100644
--- a/drivers/char/tpm/tpm-interface.c
+++ b/drivers/char/tpm/tpm-interface.c
@@ -328,8 +328,17 @@ unsigned long tpm_calc_ordinal_duration(struct tpm_chip *chip,
 }
 EXPORT_SYMBOL_GPL(tpm_calc_ordinal_duration);
 
-/*
- * Internal kernel interface to transmit TPM commands
+/**
+ * tmp_transmit - Internal kernel interface to transmit TPM commands.
+ *
+ * @chip: TPM chip to use
+ * @buf: TPM command buffer
+ * @bufsiz: length of the TPM command buffer
+ * @flags: tpm transmit flags - bitmap
+ *
+ * Return:
+ *     0 when the operation is successful.
+ *     A negative number for system errors (errno).
  */
 ssize_t tpm_transmit(struct tpm_chip *chip, const u8 *buf, size_t bufsiz,
 		     unsigned int flags)
@@ -409,9 +418,21 @@ ssize_t tpm_transmit(struct tpm_chip *chip, const u8 *buf, size_t bufsiz,
 	return rc;
 }
 
-#define TPM_DIGEST_SIZE 20
-#define TPM_RET_CODE_IDX 6
-
+/**
+ * tmp_transmit_cmd - send a tpm command to the device
+ *    The function extracts tpm out header return code
+ *
+ * @chip: TPM chip to use
+ * @cmd: TPM command buffer
+ * @len: length of the TPM command
+ * @flags: tpm transmit flags - bitmap
+ * @desc: command description used in the error message
+ *
+ * Return:
+ *     0 when the operation is successful.
+ *     A negative number for system errors (errno).
+ *     A positive number for a TPM error.
+ */
 ssize_t tpm_transmit_cmd(struct tpm_chip *chip, const void *cmd,
 			 int len, unsigned int flags, const char *desc)
 {
@@ -434,6 +455,8 @@ ssize_t tpm_transmit_cmd(struct tpm_chip *chip, const void *cmd,
 	return err;
 }
 
+#define TPM_DIGEST_SIZE 20
+#define TPM_RET_CODE_IDX 6
 #define TPM_INTERNAL_RESULT_SIZE 200
 #define TPM_ORD_GET_CAP cpu_to_be32(101)
 #define TPM_ORD_GET_RANDOM cpu_to_be32(70)
-- 
2.7.4


------------------------------------------------------------------------------

[PATCH v2 1/4] tpm: add kdoc for tpm_transmit and tpm_transmit_cmd

[Tomas Winkler]

Functions tpm_transmit and transmit_cmd are referenced
from other functions kdoc hence deserve documentation.

Signed-off-by: Tomas Winkler <tomas.winkler@intel.com>
---
V2: Add some missing '.'
 drivers/char/tpm/tpm-interface.c | 33 ++++++++++++++++++++++++++++-----
 1 file changed, 28 insertions(+), 5 deletions(-)

diff --git a/drivers/char/tpm/tpm-interface.c b/drivers/char/tpm/tpm-interface.c
index a2688ac2b48f..769d8b0d31a3 100644
--- a/drivers/char/tpm/tpm-interface.c
+++ b/drivers/char/tpm/tpm-interface.c
@@ -328,8 +328,17 @@ unsigned long tpm_calc_ordinal_duration(struct tpm_chip *chip,
 }
 EXPORT_SYMBOL_GPL(tpm_calc_ordinal_duration);
 
-/*
- * Internal kernel interface to transmit TPM commands
+/**
+ * tmp_transmit - Internal kernel interface to transmit TPM commands.
+ *
+ * @chip: TPM chip to use
+ * @buf: TPM command buffer
+ * @bufsiz: length of the TPM command buffer
+ * @flags: tpm transmit flags - bitmap
+ *
+ * Return:
+ *     0 when the operation is successful.
+ *     A negative number for system errors (errno).
  */
 ssize_t tpm_transmit(struct tpm_chip *chip, const u8 *buf, size_t bufsiz,
 		     unsigned int flags)
@@ -409,9 +418,21 @@ ssize_t tpm_transmit(struct tpm_chip *chip, const u8 *buf, size_t bufsiz,
 	return rc;
 }
 
-#define TPM_DIGEST_SIZE 20
-#define TPM_RET_CODE_IDX 6
-
+/**
+ * tmp_transmit_cmd - send a tpm command to the device
+ *    The function extracts tpm out header return code
+ *
+ * @chip: TPM chip to use
+ * @cmd: TPM command buffer
+ * @len: length of the TPM command
+ * @flags: tpm transmit flags - bitmap
+ * @desc: command description used in the error message
+ *
+ * Return:
+ *     0 when the operation is successful.
+ *     A negative number for system errors (errno).
+ *     A positive number for a TPM error.
+ */
 ssize_t tpm_transmit_cmd(struct tpm_chip *chip, const void *cmd,
 			 int len, unsigned int flags, const char *desc)
 {
@@ -434,6 +455,8 @@ ssize_t tpm_transmit_cmd(struct tpm_chip *chip, const void *cmd,
 	return err;
 }
 
+#define TPM_DIGEST_SIZE 20
+#define TPM_RET_CODE_IDX 6
 #define TPM_INTERNAL_RESULT_SIZE 200
 #define TPM_ORD_GET_CAP cpu_to_be32(101)
 #define TPM_ORD_GET_RANDOM cpu_to_be32(70)
-- 
2.7.4

Re: [PATCH v2 1/4] tpm: add kdoc for tpm_transmit and tpm_transmit_cmd

[Jarkko Sakkinen]

On Wed, Nov 23, 2016 at 12:04:11PM +0200, Tomas Winkler wrote:
> Functions tpm_transmit and transmit_cmd are referenced
> from other functions kdoc hence deserve documentation.
> 
> Signed-off-by: Tomas Winkler <tomas.winkler-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>

Do you mind if I change TPM_DIGEST_SIZE to SHA1_DIGEST_SIZE?

I'm looking to drop TPM_DIGEST_SIZE eventually.

Reviewed-by: Jarkko Sakkinen <jarkko.sakkinen-VuQAYsv1563Yd54FQh9/CA@public.gmane.org>

/Jarkko

> ---
> V2: Add some missing '.'
>  drivers/char/tpm/tpm-interface.c | 33 ++++++++++++++++++++++++++++-----
>  1 file changed, 28 insertions(+), 5 deletions(-)
> 
> diff --git a/drivers/char/tpm/tpm-interface.c b/drivers/char/tpm/tpm-interface.c
> index a2688ac2b48f..769d8b0d31a3 100644
> --- a/drivers/char/tpm/tpm-interface.c
> +++ b/drivers/char/tpm/tpm-interface.c
> @@ -328,8 +328,17 @@ unsigned long tpm_calc_ordinal_duration(struct tpm_chip *chip,
>  }
>  EXPORT_SYMBOL_GPL(tpm_calc_ordinal_duration);
>  
> -/*
> - * Internal kernel interface to transmit TPM commands
> +/**
> + * tmp_transmit - Internal kernel interface to transmit TPM commands.
> + *
> + * @chip: TPM chip to use
> + * @buf: TPM command buffer
> + * @bufsiz: length of the TPM command buffer
> + * @flags: tpm transmit flags - bitmap
> + *
> + * Return:
> + *     0 when the operation is successful.
> + *     A negative number for system errors (errno).
>   */
>  ssize_t tpm_transmit(struct tpm_chip *chip, const u8 *buf, size_t bufsiz,
>  		     unsigned int flags)
> @@ -409,9 +418,21 @@ ssize_t tpm_transmit(struct tpm_chip *chip, const u8 *buf, size_t bufsiz,
>  	return rc;
>  }
>  
> -#define TPM_DIGEST_SIZE 20
> -#define TPM_RET_CODE_IDX 6
> -
> +/**
> + * tmp_transmit_cmd - send a tpm command to the device
> + *    The function extracts tpm out header return code
> + *
> + * @chip: TPM chip to use
> + * @cmd: TPM command buffer
> + * @len: length of the TPM command
> + * @flags: tpm transmit flags - bitmap
> + * @desc: command description used in the error message
> + *
> + * Return:
> + *     0 when the operation is successful.
> + *     A negative number for system errors (errno).
> + *     A positive number for a TPM error.
> + */
>  ssize_t tpm_transmit_cmd(struct tpm_chip *chip, const void *cmd,
>  			 int len, unsigned int flags, const char *desc)
>  {
> @@ -434,6 +455,8 @@ ssize_t tpm_transmit_cmd(struct tpm_chip *chip, const void *cmd,
>  	return err;
>  }
>  
> +#define TPM_DIGEST_SIZE 20
> +#define TPM_RET_CODE_IDX 6
>  #define TPM_INTERNAL_RESULT_SIZE 200
>  #define TPM_ORD_GET_CAP cpu_to_be32(101)
>  #define TPM_ORD_GET_RANDOM cpu_to_be32(70)
> -- 
> 2.7.4
> 

------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most 
engaging tech sites, SlashDot.org! http://sdm.link/slashdot

Re: [PATCH v2 1/4] tpm: add kdoc for tpm_transmit and tpm_transmit_cmd

[Jarkko Sakkinen]

On Wed, Nov 23, 2016 at 12:04:11PM +0200, Tomas Winkler wrote:
> Functions tpm_transmit and transmit_cmd are referenced
> from other functions kdoc hence deserve documentation.
> 
> Signed-off-by: Tomas Winkler <tomas.winkler@intel.com>

Do you mind if I change TPM_DIGEST_SIZE to SHA1_DIGEST_SIZE?

I'm looking to drop TPM_DIGEST_SIZE eventually.

Reviewed-by: Jarkko Sakkinen <jarkko.sakkinen@linux.intel.com>

/Jarkko

> ---
> V2: Add some missing '.'
>  drivers/char/tpm/tpm-interface.c | 33 ++++++++++++++++++++++++++++-----
>  1 file changed, 28 insertions(+), 5 deletions(-)
> 
> diff --git a/drivers/char/tpm/tpm-interface.c b/drivers/char/tpm/tpm-interface.c
> index a2688ac2b48f..769d8b0d31a3 100644
> --- a/drivers/char/tpm/tpm-interface.c
> +++ b/drivers/char/tpm/tpm-interface.c
> @@ -328,8 +328,17 @@ unsigned long tpm_calc_ordinal_duration(struct tpm_chip *chip,
>  }
>  EXPORT_SYMBOL_GPL(tpm_calc_ordinal_duration);
>  
> -/*
> - * Internal kernel interface to transmit TPM commands
> +/**
> + * tmp_transmit - Internal kernel interface to transmit TPM commands.
> + *
> + * @chip: TPM chip to use
> + * @buf: TPM command buffer
> + * @bufsiz: length of the TPM command buffer
> + * @flags: tpm transmit flags - bitmap
> + *
> + * Return:
> + *     0 when the operation is successful.
> + *     A negative number for system errors (errno).
>   */
>  ssize_t tpm_transmit(struct tpm_chip *chip, const u8 *buf, size_t bufsiz,
>  		     unsigned int flags)
> @@ -409,9 +418,21 @@ ssize_t tpm_transmit(struct tpm_chip *chip, const u8 *buf, size_t bufsiz,
>  	return rc;
>  }
>  
> -#define TPM_DIGEST_SIZE 20
> -#define TPM_RET_CODE_IDX 6
> -
> +/**
> + * tmp_transmit_cmd - send a tpm command to the device
> + *    The function extracts tpm out header return code
> + *
> + * @chip: TPM chip to use
> + * @cmd: TPM command buffer
> + * @len: length of the TPM command
> + * @flags: tpm transmit flags - bitmap
> + * @desc: command description used in the error message
> + *
> + * Return:
> + *     0 when the operation is successful.
> + *     A negative number for system errors (errno).
> + *     A positive number for a TPM error.
> + */
>  ssize_t tpm_transmit_cmd(struct tpm_chip *chip, const void *cmd,
>  			 int len, unsigned int flags, const char *desc)
>  {
> @@ -434,6 +455,8 @@ ssize_t tpm_transmit_cmd(struct tpm_chip *chip, const void *cmd,
>  	return err;
>  }
>  
> +#define TPM_DIGEST_SIZE 20
> +#define TPM_RET_CODE_IDX 6
>  #define TPM_INTERNAL_RESULT_SIZE 200
>  #define TPM_ORD_GET_CAP cpu_to_be32(101)
>  #define TPM_ORD_GET_RANDOM cpu_to_be32(70)
> -- 
> 2.7.4
> 

Re: [PATCH v2 1/4] tpm: add kdoc for tpm_transmit and tpm_transmit_cmd

[Jarkko Sakkinen]

On Sat, Dec 03, 2016 at 05:32:36PM +0200, Jarkko Sakkinen wrote:
> On Wed, Nov 23, 2016 at 12:04:11PM +0200, Tomas Winkler wrote:
> > Functions tpm_transmit and transmit_cmd are referenced
> > from other functions kdoc hence deserve documentation.
> > 
> > Signed-off-by: Tomas Winkler <tomas.winkler-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>
> 
> Do you mind if I change TPM_DIGEST_SIZE to SHA1_DIGEST_SIZE?
> 
> I'm looking to drop TPM_DIGEST_SIZE eventually.
> 
> Reviewed-by: Jarkko Sakkinen <jarkko.sakkinen-VuQAYsv1563Yd54FQh9/CA@public.gmane.org>

Tested-by: Jarkko Sakkinen <jarkko.sakkinen-VuQAYsv1563Yd54FQh9/CA@public.gmane.org>

... in the sense that the changes do not break the compilation and do
not produce sparse or cocciheck errors. I guess that should be enough
for documentation changes.

/Jarkko

------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most 
engaging tech sites, SlashDot.org! http://sdm.link/slashdot

Re: [PATCH v2 1/4] tpm: add kdoc for tpm_transmit and tpm_transmit_cmd

[Jarkko Sakkinen]

On Sat, Dec 03, 2016 at 05:32:36PM +0200, Jarkko Sakkinen wrote:
> On Wed, Nov 23, 2016 at 12:04:11PM +0200, Tomas Winkler wrote:
> > Functions tpm_transmit and transmit_cmd are referenced
> > from other functions kdoc hence deserve documentation.
> > 
> > Signed-off-by: Tomas Winkler <tomas.winkler@intel.com>
> 
> Do you mind if I change TPM_DIGEST_SIZE to SHA1_DIGEST_SIZE?
> 
> I'm looking to drop TPM_DIGEST_SIZE eventually.
> 
> Reviewed-by: Jarkko Sakkinen <jarkko.sakkinen@linux.intel.com>

Tested-by: Jarkko Sakkinen <jarkko.sakkinen@linux.intel.com>

... in the sense that the changes do not break the compilation and do
not produce sparse or cocciheck errors. I guess that should be enough
for documentation changes.

/Jarkko

Re: [PATCH v2 1/4] tpm: add kdoc for tpm_transmit and tpm_transmit_cmd

[Nayna]

On 12/03/2016 09:02 PM, Jarkko Sakkinen wrote:
> On Wed, Nov 23, 2016 at 12:04:11PM +0200, Tomas Winkler wrote:
>> Functions tpm_transmit and transmit_cmd are referenced
>> from other functions kdoc hence deserve documentation.
>>
>> Signed-off-by: Tomas Winkler <tomas.winkler-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>
>
> Do you mind if I change TPM_DIGEST_SIZE to SHA1_DIGEST_SIZE?
>
> I'm looking to drop TPM_DIGEST_SIZE eventually.

I was thinking if we should use SHA1_DIGEST_SIZE directly from
<crypto/sha.h>, or probably <crypto/hash_info.h>

Thanks & Regards,
     - Nayna


>
> Reviewed-by: Jarkko Sakkinen <jarkko.sakkinen-VuQAYsv1563Yd54FQh9/CA@public.gmane.org>
>
> /Jarkko
>
>> ---
>> V2: Add some missing '.'
>>   drivers/char/tpm/tpm-interface.c | 33 ++++++++++++++++++++++++++++-----
>>   1 file changed, 28 insertions(+), 5 deletions(-)
>>
>> diff --git a/drivers/char/tpm/tpm-interface.c b/drivers/char/tpm/tpm-interface.c
>> index a2688ac2b48f..769d8b0d31a3 100644
>> --- a/drivers/char/tpm/tpm-interface.c
>> +++ b/drivers/char/tpm/tpm-interface.c
>> @@ -328,8 +328,17 @@ unsigned long tpm_calc_ordinal_duration(struct tpm_chip *chip,
>>   }
>>   EXPORT_SYMBOL_GPL(tpm_calc_ordinal_duration);
>>
>> -/*
>> - * Internal kernel interface to transmit TPM commands
>> +/**
>> + * tmp_transmit - Internal kernel interface to transmit TPM commands.
>> + *
>> + * @chip: TPM chip to use
>> + * @buf: TPM command buffer
>> + * @bufsiz: length of the TPM command buffer
>> + * @flags: tpm transmit flags - bitmap
>> + *
>> + * Return:
>> + *     0 when the operation is successful.
>> + *     A negative number for system errors (errno).
>>    */
>>   ssize_t tpm_transmit(struct tpm_chip *chip, const u8 *buf, size_t bufsiz,
>>   		     unsigned int flags)
>> @@ -409,9 +418,21 @@ ssize_t tpm_transmit(struct tpm_chip *chip, const u8 *buf, size_t bufsiz,
>>   	return rc;
>>   }
>>
>> -#define TPM_DIGEST_SIZE 20
>> -#define TPM_RET_CODE_IDX 6
>> -
>> +/**
>> + * tmp_transmit_cmd - send a tpm command to the device
>> + *    The function extracts tpm out header return code
>> + *
>> + * @chip: TPM chip to use
>> + * @cmd: TPM command buffer
>> + * @len: length of the TPM command
>> + * @flags: tpm transmit flags - bitmap
>> + * @desc: command description used in the error message
>> + *
>> + * Return:
>> + *     0 when the operation is successful.
>> + *     A negative number for system errors (errno).
>> + *     A positive number for a TPM error.
>> + */
>>   ssize_t tpm_transmit_cmd(struct tpm_chip *chip, const void *cmd,
>>   			 int len, unsigned int flags, const char *desc)
>>   {
>> @@ -434,6 +455,8 @@ ssize_t tpm_transmit_cmd(struct tpm_chip *chip, const void *cmd,
>>   	return err;
>>   }
>>
>> +#define TPM_DIGEST_SIZE 20
>> +#define TPM_RET_CODE_IDX 6
>>   #define TPM_INTERNAL_RESULT_SIZE 200
>>   #define TPM_ORD_GET_CAP cpu_to_be32(101)
>>   #define TPM_ORD_GET_RANDOM cpu_to_be32(70)
>> --
>> 2.7.4
>>
>
> ------------------------------------------------------------------------------
> Check out the vibrant tech community on one of the world's most
> engaging tech sites, SlashDot.org! http://sdm.link/slashdot
> _______________________________________________
> tpmdd-devel mailing list
> tpmdd-devel-5NWGOfrQmneRv+LV9MX5uipxlwaOVQ5f@public.gmane.org
> https://lists.sourceforge.net/lists/listinfo/tpmdd-devel
>


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

Re: [tpmdd-devel] [PATCH v2 1/4] tpm: add kdoc for tpm_transmit and tpm_transmit_cmd

[Nayna]

On 12/03/2016 09:02 PM, Jarkko Sakkinen wrote:
> On Wed, Nov 23, 2016 at 12:04:11PM +0200, Tomas Winkler wrote:
>> Functions tpm_transmit and transmit_cmd are referenced
>> from other functions kdoc hence deserve documentation.
>>
>> Signed-off-by: Tomas Winkler <tomas.winkler@intel.com>
>
> Do you mind if I change TPM_DIGEST_SIZE to SHA1_DIGEST_SIZE?
>
> I'm looking to drop TPM_DIGEST_SIZE eventually.

I was thinking if we should use SHA1_DIGEST_SIZE directly from
<crypto/sha.h>, or probably <crypto/hash_info.h>

Thanks & Regards,
     - Nayna


>
> Reviewed-by: Jarkko Sakkinen <jarkko.sakkinen@linux.intel.com>
>
> /Jarkko
>
>> ---
>> V2: Add some missing '.'
>>   drivers/char/tpm/tpm-interface.c | 33 ++++++++++++++++++++++++++++-----
>>   1 file changed, 28 insertions(+), 5 deletions(-)
>>
>> diff --git a/drivers/char/tpm/tpm-interface.c b/drivers/char/tpm/tpm-interface.c
>> index a2688ac2b48f..769d8b0d31a3 100644
>> --- a/drivers/char/tpm/tpm-interface.c
>> +++ b/drivers/char/tpm/tpm-interface.c
>> @@ -328,8 +328,17 @@ unsigned long tpm_calc_ordinal_duration(struct tpm_chip *chip,
>>   }
>>   EXPORT_SYMBOL_GPL(tpm_calc_ordinal_duration);
>>
>> -/*
>> - * Internal kernel interface to transmit TPM commands
>> +/**
>> + * tmp_transmit - Internal kernel interface to transmit TPM commands.
>> + *
>> + * @chip: TPM chip to use
>> + * @buf: TPM command buffer
>> + * @bufsiz: length of the TPM command buffer
>> + * @flags: tpm transmit flags - bitmap
>> + *
>> + * Return:
>> + *     0 when the operation is successful.
>> + *     A negative number for system errors (errno).
>>    */
>>   ssize_t tpm_transmit(struct tpm_chip *chip, const u8 *buf, size_t bufsiz,
>>   		     unsigned int flags)
>> @@ -409,9 +418,21 @@ ssize_t tpm_transmit(struct tpm_chip *chip, const u8 *buf, size_t bufsiz,
>>   	return rc;
>>   }
>>
>> -#define TPM_DIGEST_SIZE 20
>> -#define TPM_RET_CODE_IDX 6
>> -
>> +/**
>> + * tmp_transmit_cmd - send a tpm command to the device
>> + *    The function extracts tpm out header return code
>> + *
>> + * @chip: TPM chip to use
>> + * @cmd: TPM command buffer
>> + * @len: length of the TPM command
>> + * @flags: tpm transmit flags - bitmap
>> + * @desc: command description used in the error message
>> + *
>> + * Return:
>> + *     0 when the operation is successful.
>> + *     A negative number for system errors (errno).
>> + *     A positive number for a TPM error.
>> + */
>>   ssize_t tpm_transmit_cmd(struct tpm_chip *chip, const void *cmd,
>>   			 int len, unsigned int flags, const char *desc)
>>   {
>> @@ -434,6 +455,8 @@ ssize_t tpm_transmit_cmd(struct tpm_chip *chip, const void *cmd,
>>   	return err;
>>   }
>>
>> +#define TPM_DIGEST_SIZE 20
>> +#define TPM_RET_CODE_IDX 6
>>   #define TPM_INTERNAL_RESULT_SIZE 200
>>   #define TPM_ORD_GET_CAP cpu_to_be32(101)
>>   #define TPM_ORD_GET_RANDOM cpu_to_be32(70)
>> --
>> 2.7.4
>>
>
> ------------------------------------------------------------------------------
> Check out the vibrant tech community on one of the world's most
> engaging tech sites, SlashDot.org! http://sdm.link/slashdot
> _______________________________________________
> tpmdd-devel mailing list
> tpmdd-devel@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/tpmdd-devel
>

Re: [PATCH v2 1/4] tpm: add kdoc for tpm_transmit and tpm_transmit_cmd

[Winkler, Tomas]

> -----Original Message-----
> From: Nayna [mailto:nayna-23VcF4HTsmIX0ybBhKVfKdBPR1lH4CV8@public.gmane.org]
> Sent: Tuesday, December 06, 2016 11:17
> To: Jarkko Sakkinen <jarkko.sakkinen-VuQAYsv1563Yd54FQh9/CA@public.gmane.org>; Winkler, Tomas
> <tomas.winkler-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>
> Cc: tpmdd-devel-5NWGOfrQmneRv+LV9MX5uipxlwaOVQ5f@public.gmane.org; linux-kernel-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
> Subject: Re: [tpmdd-devel] [PATCH v2 1/4] tpm: add kdoc for tpm_transmit and
> tpm_transmit_cmd
> 
> 
> 
> On 12/03/2016 09:02 PM, Jarkko Sakkinen wrote:
> > On Wed, Nov 23, 2016 at 12:04:11PM +0200, Tomas Winkler wrote:
> >> Functions tpm_transmit and transmit_cmd are referenced from other
> >> functions kdoc hence deserve documentation.
> >>
> >> Signed-off-by: Tomas Winkler <tomas.winkler-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>
> >
> > Do you mind if I change TPM_DIGEST_SIZE to SHA1_DIGEST_SIZE?
> >
> > I'm looking to drop TPM_DIGEST_SIZE eventually.
> 
> I was thinking if we should use SHA1_DIGEST_SIZE directly from <crypto/sha.h>,
> or probably <crypto/hash_info.h>

Probably the best approach 
Tomas
> 
> >
> > Reviewed-by: Jarkko Sakkinen <jarkko.sakkinen-VuQAYsv1563Yd54FQh9/CA@public.gmane.org>
> >
> > /Jarkko
> >
> >> ---
> >> V2: Add some missing '.'
> >>   drivers/char/tpm/tpm-interface.c | 33 ++++++++++++++++++++++++++++--
> ---
> >>   1 file changed, 28 insertions(+), 5 deletions(-)
> >>
> >> diff --git a/drivers/char/tpm/tpm-interface.c
> >> b/drivers/char/tpm/tpm-interface.c
> >> index a2688ac2b48f..769d8b0d31a3 100644
> >> --- a/drivers/char/tpm/tpm-interface.c
> >> +++ b/drivers/char/tpm/tpm-interface.c
> >> @@ -328,8 +328,17 @@ unsigned long tpm_calc_ordinal_duration(struct
> tpm_chip *chip,
> >>   }
> >>   EXPORT_SYMBOL_GPL(tpm_calc_ordinal_duration);
> >>
> >> -/*
> >> - * Internal kernel interface to transmit TPM commands
> >> +/**
> >> + * tmp_transmit - Internal kernel interface to transmit TPM commands.
> >> + *
> >> + * @chip: TPM chip to use
> >> + * @buf: TPM command buffer
> >> + * @bufsiz: length of the TPM command buffer
> >> + * @flags: tpm transmit flags - bitmap
> >> + *
> >> + * Return:
> >> + *     0 when the operation is successful.
> >> + *     A negative number for system errors (errno).
> >>    */
> >>   ssize_t tpm_transmit(struct tpm_chip *chip, const u8 *buf, size_t bufsiz,
> >>   		     unsigned int flags)
> >> @@ -409,9 +418,21 @@ ssize_t tpm_transmit(struct tpm_chip *chip, const
> u8 *buf, size_t bufsiz,
> >>   	return rc;
> >>   }
> >>
> >> -#define TPM_DIGEST_SIZE 20
> >> -#define TPM_RET_CODE_IDX 6
> >> -
> >> +/**
> >> + * tmp_transmit_cmd - send a tpm command to the device
> >> + *    The function extracts tpm out header return code
> >> + *
> >> + * @chip: TPM chip to use
> >> + * @cmd: TPM command buffer
> >> + * @len: length of the TPM command
> >> + * @flags: tpm transmit flags - bitmap
> >> + * @desc: command description used in the error message
> >> + *
> >> + * Return:
> >> + *     0 when the operation is successful.
> >> + *     A negative number for system errors (errno).
> >> + *     A positive number for a TPM error.
> >> + */
> >>   ssize_t tpm_transmit_cmd(struct tpm_chip *chip, const void *cmd,
> >>   			 int len, unsigned int flags, const char *desc)
> >>   {
> >> @@ -434,6 +455,8 @@ ssize_t tpm_transmit_cmd(struct tpm_chip *chip,
> const void *cmd,
> >>   	return err;
> >>   }
> >>
> >> +#define TPM_DIGEST_SIZE 20
> >> +#define TPM_RET_CODE_IDX 6
> >>   #define TPM_INTERNAL_RESULT_SIZE 200
> >>   #define TPM_ORD_GET_CAP cpu_to_be32(101)
> >>   #define TPM_ORD_GET_RANDOM cpu_to_be32(70)
> >> --
> >> 2.7.4
> >>
> >
> > ----------------------------------------------------------------------
> > -------- Check out the vibrant tech community on one of the world's
> > most engaging tech sites, SlashDot.org! http://sdm.link/slashdot
> > _______________________________________________
> > tpmdd-devel mailing list
> > tpmdd-devel-5NWGOfrQmneRv+LV9MX5uipxlwaOVQ5f@public.gmane.org
> > https://lists.sourceforge.net/lists/listinfo/tpmdd-devel
> >


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

RE: [tpmdd-devel] [PATCH v2 1/4] tpm: add kdoc for tpm_transmit and tpm_transmit_cmd

[Winkler, Tomas]

> -----Original Message-----
> From: Nayna [mailto:nayna@linux.vnet.ibm.com]
> Sent: Tuesday, December 06, 2016 11:17
> To: Jarkko Sakkinen <jarkko.sakkinen@linux.intel.com>; Winkler, Tomas
> <tomas.winkler@intel.com>
> Cc: tpmdd-devel@lists.sourceforge.net; linux-kernel@vger.kernel.org
> Subject: Re: [tpmdd-devel] [PATCH v2 1/4] tpm: add kdoc for tpm_transmit and
> tpm_transmit_cmd
> 
> 
> 
> On 12/03/2016 09:02 PM, Jarkko Sakkinen wrote:
> > On Wed, Nov 23, 2016 at 12:04:11PM +0200, Tomas Winkler wrote:
> >> Functions tpm_transmit and transmit_cmd are referenced from other
> >> functions kdoc hence deserve documentation.
> >>
> >> Signed-off-by: Tomas Winkler <tomas.winkler@intel.com>
> >
> > Do you mind if I change TPM_DIGEST_SIZE to SHA1_DIGEST_SIZE?
> >
> > I'm looking to drop TPM_DIGEST_SIZE eventually.
> 
> I was thinking if we should use SHA1_DIGEST_SIZE directly from <crypto/sha.h>,
> or probably <crypto/hash_info.h>

Probably the best approach 
Tomas
> 
> >
> > Reviewed-by: Jarkko Sakkinen <jarkko.sakkinen@linux.intel.com>
> >
> > /Jarkko
> >
> >> ---
> >> V2: Add some missing '.'
> >>   drivers/char/tpm/tpm-interface.c | 33 ++++++++++++++++++++++++++++--
> ---
> >>   1 file changed, 28 insertions(+), 5 deletions(-)
> >>
> >> diff --git a/drivers/char/tpm/tpm-interface.c
> >> b/drivers/char/tpm/tpm-interface.c
> >> index a2688ac2b48f..769d8b0d31a3 100644
> >> --- a/drivers/char/tpm/tpm-interface.c
> >> +++ b/drivers/char/tpm/tpm-interface.c
> >> @@ -328,8 +328,17 @@ unsigned long tpm_calc_ordinal_duration(struct
> tpm_chip *chip,
> >>   }
> >>   EXPORT_SYMBOL_GPL(tpm_calc_ordinal_duration);
> >>
> >> -/*
> >> - * Internal kernel interface to transmit TPM commands
> >> +/**
> >> + * tmp_transmit - Internal kernel interface to transmit TPM commands.
> >> + *
> >> + * @chip: TPM chip to use
> >> + * @buf: TPM command buffer
> >> + * @bufsiz: length of the TPM command buffer
> >> + * @flags: tpm transmit flags - bitmap
> >> + *
> >> + * Return:
> >> + *     0 when the operation is successful.
> >> + *     A negative number for system errors (errno).
> >>    */
> >>   ssize_t tpm_transmit(struct tpm_chip *chip, const u8 *buf, size_t bufsiz,
> >>   		     unsigned int flags)
> >> @@ -409,9 +418,21 @@ ssize_t tpm_transmit(struct tpm_chip *chip, const
> u8 *buf, size_t bufsiz,
> >>   	return rc;
> >>   }
> >>
> >> -#define TPM_DIGEST_SIZE 20
> >> -#define TPM_RET_CODE_IDX 6
> >> -
> >> +/**
> >> + * tmp_transmit_cmd - send a tpm command to the device
> >> + *    The function extracts tpm out header return code
> >> + *
> >> + * @chip: TPM chip to use
> >> + * @cmd: TPM command buffer
> >> + * @len: length of the TPM command
> >> + * @flags: tpm transmit flags - bitmap
> >> + * @desc: command description used in the error message
> >> + *
> >> + * Return:
> >> + *     0 when the operation is successful.
> >> + *     A negative number for system errors (errno).
> >> + *     A positive number for a TPM error.
> >> + */
> >>   ssize_t tpm_transmit_cmd(struct tpm_chip *chip, const void *cmd,
> >>   			 int len, unsigned int flags, const char *desc)
> >>   {
> >> @@ -434,6 +455,8 @@ ssize_t tpm_transmit_cmd(struct tpm_chip *chip,
> const void *cmd,
> >>   	return err;
> >>   }
> >>
> >> +#define TPM_DIGEST_SIZE 20
> >> +#define TPM_RET_CODE_IDX 6
> >>   #define TPM_INTERNAL_RESULT_SIZE 200
> >>   #define TPM_ORD_GET_CAP cpu_to_be32(101)
> >>   #define TPM_ORD_GET_RANDOM cpu_to_be32(70)
> >> --
> >> 2.7.4
> >>
> >
> > ----------------------------------------------------------------------
> > -------- Check out the vibrant tech community on one of the world's
> > most engaging tech sites, SlashDot.org! http://sdm.link/slashdot
> > _______________________________________________
> > tpmdd-devel mailing list
> > tpmdd-devel@lists.sourceforge.net
> > https://lists.sourceforge.net/lists/listinfo/tpmdd-devel
> >

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

[Tomas Winkler]

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

Signed-off-by: Tomas Winkler <tomas.winkler-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>
---
V2: Add missing '.'

 drivers/char/tpm/tpm2-cmd.c | 105 ++++++++++++++++++++++++--------------------
 1 file changed, 57 insertions(+), 48 deletions(-)

diff --git a/drivers/char/tpm/tpm2-cmd.c b/drivers/char/tpm/tpm2-cmd.c
index da5b782a9731..cc624e1e052d 100644
--- a/drivers/char/tpm/tpm2-cmd.c
+++ b/drivers/char/tpm/tpm2-cmd.c
@@ -258,11 +258,9 @@ 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: Same as with tpm_transmit_cmd.
  */
 int tpm2_pcr_read(struct tpm_chip *chip, int pcr_idx, u8 *res_buf)
 {
@@ -304,13 +302,12 @@ 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: Same as with tpm_transmit_cmd.
  */
 int tpm2_pcr_extend(struct tpm_chip *chip, int pcr_idx, const u8 *hash)
 {
@@ -348,13 +345,13 @@ 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:
+ *    Size of the output buffer, or -EIO on error.
  */
 int tpm2_get_random(struct tpm_chip *chip, u8 *out, size_t max)
 {
@@ -404,15 +401,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 +433,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,11 +539,17 @@ int tpm2_seal_trusted(struct tpm_chip *chip,
 
 /**
  * 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
+ * Return: 0 on success.
+ *        -E2BIG on wrong payload size.
+ *        -EPERM on tpm error status.
+ *        < 0 error from tpm_transmit_cmd.
  */
 static int tpm2_load_cmd(struct tpm_chip *chip,
 			 struct trusted_key_payload *payload,
@@ -600,11 +605,12 @@ static int tpm2_load_cmd(struct tpm_chip *chip,
 
 /**
  * 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
  *
- * Return: same as with tpm_transmit_cmd
+ * @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.
  */
 static void tpm2_flush_context_cmd(struct tpm_chip *chip, u32 handle,
 				   unsigned int flags)
@@ -632,11 +638,16 @@ 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
+ * Return: 0 on success
+ *         -EPERM on tpm error status
+ *         < 0 error from tpm_transmit_cmd
  */
 static int tpm2_unseal_cmd(struct tpm_chip *chip,
 			   struct trusted_key_payload *payload,
@@ -681,11 +692,12 @@ static int tpm2_unseal_cmd(struct tpm_chip *chip,
 
 /**
  * tpm2_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
  *
- * Return: < 0 on error and 0 on success.
+ * Return: Same as with tpm_transmit_cmd.
  */
 int tpm2_unseal_trusted(struct tpm_chip *chip,
 			struct trusted_key_payload *payload,
@@ -715,9 +727,7 @@ int tpm2_unseal_trusted(struct tpm_chip *chip,
  * @value:		output variable.
  * @desc:		passed to tpm_transmit_cmd()
  *
- * 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: Same as with tpm_transmit_cmd.
  */
 ssize_t tpm2_get_tpm_pt(struct tpm_chip *chip, u32 property_id,  u32 *value,
 			const char *desc)
@@ -750,13 +760,12 @@ 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: Same as with tpm_transmit_cmd.
  */
 static int tpm2_startup(struct tpm_chip *chip, u16 startup_type)
 {
@@ -781,8 +790,9 @@ 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 +815,11 @@ 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: maximum duration for a command
  */
 unsigned long tpm2_calc_ordinal_duration(struct tpm_chip *chip, u32 ordinal)
 {
@@ -842,13 +851,12 @@ 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: Same as with tpm_transmit_cmd with exception of RC_TESTING.
  */
 static int tpm2_start_selftest(struct tpm_chip *chip, bool full)
 {
@@ -874,14 +882,13 @@ 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: Same as with tpm_transmit_cmd.
+ *
  * 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 +935,8 @@ static int tpm2_do_selftest(struct tpm_chip *chip)
  * tpm2_probe() - probe TPM 2.0
  * @chip: TPM chip to use
  *
+ * Return: < 0 error and 0 on success.
+ *
  * Send idempotent TPM 2.0 command and see whether TPM 2.0 chip replied based on
  * the reply tag.
  */
-- 
2.7.4


------------------------------------------------------------------------------

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

[Tomas Winkler]

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

Signed-off-by: Tomas Winkler <tomas.winkler@intel.com>
---
V2: Add missing '.'

 drivers/char/tpm/tpm2-cmd.c | 105 ++++++++++++++++++++++++--------------------
 1 file changed, 57 insertions(+), 48 deletions(-)

diff --git a/drivers/char/tpm/tpm2-cmd.c b/drivers/char/tpm/tpm2-cmd.c
index da5b782a9731..cc624e1e052d 100644
--- a/drivers/char/tpm/tpm2-cmd.c
+++ b/drivers/char/tpm/tpm2-cmd.c
@@ -258,11 +258,9 @@ 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: Same as with tpm_transmit_cmd.
  */
 int tpm2_pcr_read(struct tpm_chip *chip, int pcr_idx, u8 *res_buf)
 {
@@ -304,13 +302,12 @@ 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: Same as with tpm_transmit_cmd.
  */
 int tpm2_pcr_extend(struct tpm_chip *chip, int pcr_idx, const u8 *hash)
 {
@@ -348,13 +345,13 @@ 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:
+ *    Size of the output buffer, or -EIO on error.
  */
 int tpm2_get_random(struct tpm_chip *chip, u8 *out, size_t max)
 {
@@ -404,15 +401,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 +433,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,11 +539,17 @@ int tpm2_seal_trusted(struct tpm_chip *chip,
 
 /**
  * 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
+ * Return: 0 on success.
+ *        -E2BIG on wrong payload size.
+ *        -EPERM on tpm error status.
+ *        < 0 error from tpm_transmit_cmd.
  */
 static int tpm2_load_cmd(struct tpm_chip *chip,
 			 struct trusted_key_payload *payload,
@@ -600,11 +605,12 @@ static int tpm2_load_cmd(struct tpm_chip *chip,
 
 /**
  * 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
  *
- * Return: same as with tpm_transmit_cmd
+ * @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.
  */
 static void tpm2_flush_context_cmd(struct tpm_chip *chip, u32 handle,
 				   unsigned int flags)
@@ -632,11 +638,16 @@ 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
+ * Return: 0 on success
+ *         -EPERM on tpm error status
+ *         < 0 error from tpm_transmit_cmd
  */
 static int tpm2_unseal_cmd(struct tpm_chip *chip,
 			   struct trusted_key_payload *payload,
@@ -681,11 +692,12 @@ static int tpm2_unseal_cmd(struct tpm_chip *chip,
 
 /**
  * tpm2_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
  *
- * Return: < 0 on error and 0 on success.
+ * Return: Same as with tpm_transmit_cmd.
  */
 int tpm2_unseal_trusted(struct tpm_chip *chip,
 			struct trusted_key_payload *payload,
@@ -715,9 +727,7 @@ int tpm2_unseal_trusted(struct tpm_chip *chip,
  * @value:		output variable.
  * @desc:		passed to tpm_transmit_cmd()
  *
- * 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: Same as with tpm_transmit_cmd.
  */
 ssize_t tpm2_get_tpm_pt(struct tpm_chip *chip, u32 property_id,  u32 *value,
 			const char *desc)
@@ -750,13 +760,12 @@ 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: Same as with tpm_transmit_cmd.
  */
 static int tpm2_startup(struct tpm_chip *chip, u16 startup_type)
 {
@@ -781,8 +790,9 @@ 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 +815,11 @@ 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: maximum duration for a command
  */
 unsigned long tpm2_calc_ordinal_duration(struct tpm_chip *chip, u32 ordinal)
 {
@@ -842,13 +851,12 @@ 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: Same as with tpm_transmit_cmd with exception of RC_TESTING.
  */
 static int tpm2_start_selftest(struct tpm_chip *chip, bool full)
 {
@@ -874,14 +882,13 @@ 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: Same as with tpm_transmit_cmd.
+ *
  * 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 +935,8 @@ static int tpm2_do_selftest(struct tpm_chip *chip)
  * tpm2_probe() - probe TPM 2.0
  * @chip: TPM chip to use
  *
+ * Return: < 0 error and 0 on success.
+ *
  * Send idempotent TPM 2.0 command and see whether TPM 2.0 chip replied based on
  * the reply tag.
  */
-- 
2.7.4

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

[Jarkko Sakkinen]

On Wed, Nov 23, 2016 at 12:04:12PM +0200, Tomas Winkler wrote:
> Use correct kdoc format, describe correct parameters and return values.
> 
> Signed-off-by: Tomas Winkler <tomas.winkler-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>

Reviewed-by: Jarkko Sakkinen <jarkko.sakkinen-VuQAYsv1563Yd54FQh9/CA@public.gmane.org>

/Jarkko

> ---
> V2: Add missing '.'
> 
>  drivers/char/tpm/tpm2-cmd.c | 105 ++++++++++++++++++++++++--------------------
>  1 file changed, 57 insertions(+), 48 deletions(-)
> 
> diff --git a/drivers/char/tpm/tpm2-cmd.c b/drivers/char/tpm/tpm2-cmd.c
> index da5b782a9731..cc624e1e052d 100644
> --- a/drivers/char/tpm/tpm2-cmd.c
> +++ b/drivers/char/tpm/tpm2-cmd.c
> @@ -258,11 +258,9 @@ 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: Same as with tpm_transmit_cmd.
>   */
>  int tpm2_pcr_read(struct tpm_chip *chip, int pcr_idx, u8 *res_buf)
>  {
> @@ -304,13 +302,12 @@ 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: Same as with tpm_transmit_cmd.
>   */
>  int tpm2_pcr_extend(struct tpm_chip *chip, int pcr_idx, const u8 *hash)
>  {
> @@ -348,13 +345,13 @@ 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:
> + *    Size of the output buffer, or -EIO on error.
>   */
>  int tpm2_get_random(struct tpm_chip *chip, u8 *out, size_t max)
>  {
> @@ -404,15 +401,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 +433,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,11 +539,17 @@ int tpm2_seal_trusted(struct tpm_chip *chip,
>  
>  /**
>   * 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
> + * Return: 0 on success.
> + *        -E2BIG on wrong payload size.
> + *        -EPERM on tpm error status.
> + *        < 0 error from tpm_transmit_cmd.
>   */
>  static int tpm2_load_cmd(struct tpm_chip *chip,
>  			 struct trusted_key_payload *payload,
> @@ -600,11 +605,12 @@ static int tpm2_load_cmd(struct tpm_chip *chip,
>  
>  /**
>   * 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
>   *
> - * Return: same as with tpm_transmit_cmd
> + * @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.
>   */
>  static void tpm2_flush_context_cmd(struct tpm_chip *chip, u32 handle,
>  				   unsigned int flags)
> @@ -632,11 +638,16 @@ 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
> + * Return: 0 on success
> + *         -EPERM on tpm error status
> + *         < 0 error from tpm_transmit_cmd
>   */
>  static int tpm2_unseal_cmd(struct tpm_chip *chip,
>  			   struct trusted_key_payload *payload,
> @@ -681,11 +692,12 @@ static int tpm2_unseal_cmd(struct tpm_chip *chip,
>  
>  /**
>   * tpm2_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
>   *
> - * Return: < 0 on error and 0 on success.
> + * Return: Same as with tpm_transmit_cmd.
>   */
>  int tpm2_unseal_trusted(struct tpm_chip *chip,
>  			struct trusted_key_payload *payload,
> @@ -715,9 +727,7 @@ int tpm2_unseal_trusted(struct tpm_chip *chip,
>   * @value:		output variable.
>   * @desc:		passed to tpm_transmit_cmd()
>   *
> - * 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: Same as with tpm_transmit_cmd.
>   */
>  ssize_t tpm2_get_tpm_pt(struct tpm_chip *chip, u32 property_id,  u32 *value,
>  			const char *desc)
> @@ -750,13 +760,12 @@ 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: Same as with tpm_transmit_cmd.
>   */
>  static int tpm2_startup(struct tpm_chip *chip, u16 startup_type)
>  {
> @@ -781,8 +790,9 @@ 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 +815,11 @@ 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: maximum duration for a command
>   */
>  unsigned long tpm2_calc_ordinal_duration(struct tpm_chip *chip, u32 ordinal)
>  {
> @@ -842,13 +851,12 @@ 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: Same as with tpm_transmit_cmd with exception of RC_TESTING.
>   */
>  static int tpm2_start_selftest(struct tpm_chip *chip, bool full)
>  {
> @@ -874,14 +882,13 @@ 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: Same as with tpm_transmit_cmd.
> + *
>   * 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 +935,8 @@ static int tpm2_do_selftest(struct tpm_chip *chip)
>   * tpm2_probe() - probe TPM 2.0
>   * @chip: TPM chip to use
>   *
> + * Return: < 0 error and 0 on success.
> + *
>   * Send idempotent TPM 2.0 command and see whether TPM 2.0 chip replied based on
>   * the reply tag.
>   */
> -- 
> 2.7.4
> 

------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most 
engaging tech sites, SlashDot.org! http://sdm.link/slashdot

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

[Jarkko Sakkinen]

On Wed, Nov 23, 2016 at 12:04:12PM +0200, Tomas Winkler wrote:
> Use correct kdoc format, describe correct parameters and return values.
> 
> Signed-off-by: Tomas Winkler <tomas.winkler@intel.com>

Reviewed-by: Jarkko Sakkinen <jarkko.sakkinen@linux.intel.com>

/Jarkko

> ---
> V2: Add missing '.'
> 
>  drivers/char/tpm/tpm2-cmd.c | 105 ++++++++++++++++++++++++--------------------
>  1 file changed, 57 insertions(+), 48 deletions(-)
> 
> diff --git a/drivers/char/tpm/tpm2-cmd.c b/drivers/char/tpm/tpm2-cmd.c
> index da5b782a9731..cc624e1e052d 100644
> --- a/drivers/char/tpm/tpm2-cmd.c
> +++ b/drivers/char/tpm/tpm2-cmd.c
> @@ -258,11 +258,9 @@ 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: Same as with tpm_transmit_cmd.
>   */
>  int tpm2_pcr_read(struct tpm_chip *chip, int pcr_idx, u8 *res_buf)
>  {
> @@ -304,13 +302,12 @@ 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: Same as with tpm_transmit_cmd.
>   */
>  int tpm2_pcr_extend(struct tpm_chip *chip, int pcr_idx, const u8 *hash)
>  {
> @@ -348,13 +345,13 @@ 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:
> + *    Size of the output buffer, or -EIO on error.
>   */
>  int tpm2_get_random(struct tpm_chip *chip, u8 *out, size_t max)
>  {
> @@ -404,15 +401,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 +433,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,11 +539,17 @@ int tpm2_seal_trusted(struct tpm_chip *chip,
>  
>  /**
>   * 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
> + * Return: 0 on success.
> + *        -E2BIG on wrong payload size.
> + *        -EPERM on tpm error status.
> + *        < 0 error from tpm_transmit_cmd.
>   */
>  static int tpm2_load_cmd(struct tpm_chip *chip,
>  			 struct trusted_key_payload *payload,
> @@ -600,11 +605,12 @@ static int tpm2_load_cmd(struct tpm_chip *chip,
>  
>  /**
>   * 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
>   *
> - * Return: same as with tpm_transmit_cmd
> + * @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.
>   */
>  static void tpm2_flush_context_cmd(struct tpm_chip *chip, u32 handle,
>  				   unsigned int flags)
> @@ -632,11 +638,16 @@ 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
> + * Return: 0 on success
> + *         -EPERM on tpm error status
> + *         < 0 error from tpm_transmit_cmd
>   */
>  static int tpm2_unseal_cmd(struct tpm_chip *chip,
>  			   struct trusted_key_payload *payload,
> @@ -681,11 +692,12 @@ static int tpm2_unseal_cmd(struct tpm_chip *chip,
>  
>  /**
>   * tpm2_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
>   *
> - * Return: < 0 on error and 0 on success.
> + * Return: Same as with tpm_transmit_cmd.
>   */
>  int tpm2_unseal_trusted(struct tpm_chip *chip,
>  			struct trusted_key_payload *payload,
> @@ -715,9 +727,7 @@ int tpm2_unseal_trusted(struct tpm_chip *chip,
>   * @value:		output variable.
>   * @desc:		passed to tpm_transmit_cmd()
>   *
> - * 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: Same as with tpm_transmit_cmd.
>   */
>  ssize_t tpm2_get_tpm_pt(struct tpm_chip *chip, u32 property_id,  u32 *value,
>  			const char *desc)
> @@ -750,13 +760,12 @@ 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: Same as with tpm_transmit_cmd.
>   */
>  static int tpm2_startup(struct tpm_chip *chip, u16 startup_type)
>  {
> @@ -781,8 +790,9 @@ 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 +815,11 @@ 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: maximum duration for a command
>   */
>  unsigned long tpm2_calc_ordinal_duration(struct tpm_chip *chip, u32 ordinal)
>  {
> @@ -842,13 +851,12 @@ 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: Same as with tpm_transmit_cmd with exception of RC_TESTING.
>   */
>  static int tpm2_start_selftest(struct tpm_chip *chip, bool full)
>  {
> @@ -874,14 +882,13 @@ 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: Same as with tpm_transmit_cmd.
> + *
>   * 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 +935,8 @@ static int tpm2_do_selftest(struct tpm_chip *chip)
>   * tpm2_probe() - probe TPM 2.0
>   * @chip: TPM chip to use
>   *
> + * Return: < 0 error and 0 on success.
> + *
>   * Send idempotent TPM 2.0 command and see whether TPM 2.0 chip replied based on
>   * the reply tag.
>   */
> -- 
> 2.7.4
> 

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

[Jarkko Sakkinen]

On Sat, Dec 03, 2016 at 05:34:17PM +0200, Jarkko Sakkinen wrote:
> On Wed, Nov 23, 2016 at 12:04:12PM +0200, Tomas Winkler wrote:
> > Use correct kdoc format, describe correct parameters and return values.
> > 
> > Signed-off-by: Tomas Winkler <tomas.winkler-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>
> 
> Reviewed-by: Jarkko Sakkinen <jarkko.sakkinen-VuQAYsv1563Yd54FQh9/CA@public.gmane.org>

Tested-by: Jarkko Sakkinen <jarkko.sakkinen-VuQAYsv1563Yd54FQh9/CA@public.gmane.org>

... in the sense that the changes do not break the compilation and do
not produce sparse or cocciheck errors. I guess that should be enough
for these documentation changes.

/Jarkko

------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most 
engaging tech sites, SlashDot.org! http://sdm.link/slashdot

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

[Jarkko Sakkinen]

On Sat, Dec 03, 2016 at 05:34:17PM +0200, Jarkko Sakkinen wrote:
> On Wed, Nov 23, 2016 at 12:04:12PM +0200, Tomas Winkler wrote:
> > Use correct kdoc format, describe correct parameters and return values.
> > 
> > Signed-off-by: Tomas Winkler <tomas.winkler@intel.com>
> 
> Reviewed-by: Jarkko Sakkinen <jarkko.sakkinen@linux.intel.com>

Tested-by: Jarkko Sakkinen <jarkko.sakkinen@linux.intel.com>

... in the sense that the changes do not break the compilation and do
not produce sparse or cocciheck errors. I guess that should be enough
for these documentation changes.

/Jarkko

[PATCH v2 3/4] tmp: use pdev for parent device in tpm_chip_alloc

[Tomas Winkler]

The tpm stack uses pdev name convention for the parent device.
Fix that also in tpm_chip_alloc().

Fixes: 3897cd9c8d1d ("tpm: Split out the devm stuff from tpmm_chip_alloc")'
Signed-off-by: Tomas Winkler <tomas.winkler-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>
---
V2: resend
 drivers/char/tpm/tpm-chip.c | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/drivers/char/tpm/tpm-chip.c b/drivers/char/tpm/tpm-chip.c
index 7a4869151d3b..eefdc809faf0 100644
--- a/drivers/char/tpm/tpm-chip.c
+++ b/drivers/char/tpm/tpm-chip.c
@@ -141,7 +141,7 @@ static void tpm_dev_release(struct device *dev)
  * Allocates a new struct tpm_chip instance and assigns a free
  * device number for it. Must be paired with put_device(&chip->dev).
  */
-struct tpm_chip *tpm_chip_alloc(struct device *dev,
+struct tpm_chip *tpm_chip_alloc(struct device *pdev,
 				const struct tpm_class_ops *ops)
 {
 	struct tpm_chip *chip;
@@ -160,7 +160,7 @@ struct tpm_chip *tpm_chip_alloc(struct device *dev,
 	rc = idr_alloc(&dev_nums_idr, NULL, 0, TPM_NUM_DEVICES, GFP_KERNEL);
 	mutex_unlock(&idr_lock);
 	if (rc < 0) {
-		dev_err(dev, "No available tpm device numbers\n");
+		dev_err(pdev, "No available tpm device numbers\n");
 		kfree(chip);
 		return ERR_PTR(rc);
 	}
@@ -170,7 +170,7 @@ struct tpm_chip *tpm_chip_alloc(struct device *dev,
 
 	chip->dev.class = tpm_class;
 	chip->dev.release = tpm_dev_release;
-	chip->dev.parent = dev;
+	chip->dev.parent = pdev;
 	chip->dev.groups = chip->groups;
 
 	if (chip->dev_num == 0)
@@ -182,7 +182,7 @@ struct tpm_chip *tpm_chip_alloc(struct device *dev,
 	if (rc)
 		goto out;
 
-	if (!dev)
+	if (!pdev)
 		chip->flags |= TPM_CHIP_FLAG_VIRTUAL;
 
 	cdev_init(&chip->cdev, &tpm_fops);
-- 
2.7.4


------------------------------------------------------------------------------

[PATCH v2 3/4] tmp: use pdev for parent device in tpm_chip_alloc

[Tomas Winkler]

The tpm stack uses pdev name convention for the parent device.
Fix that also in tpm_chip_alloc().

Fixes: 3897cd9c8d1d ("tpm: Split out the devm stuff from tpmm_chip_alloc")'
Signed-off-by: Tomas Winkler <tomas.winkler@intel.com>
---
V2: resend
 drivers/char/tpm/tpm-chip.c | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/drivers/char/tpm/tpm-chip.c b/drivers/char/tpm/tpm-chip.c
index 7a4869151d3b..eefdc809faf0 100644
--- a/drivers/char/tpm/tpm-chip.c
+++ b/drivers/char/tpm/tpm-chip.c
@@ -141,7 +141,7 @@ static void tpm_dev_release(struct device *dev)
  * Allocates a new struct tpm_chip instance and assigns a free
  * device number for it. Must be paired with put_device(&chip->dev).
  */
-struct tpm_chip *tpm_chip_alloc(struct device *dev,
+struct tpm_chip *tpm_chip_alloc(struct device *pdev,
 				const struct tpm_class_ops *ops)
 {
 	struct tpm_chip *chip;
@@ -160,7 +160,7 @@ struct tpm_chip *tpm_chip_alloc(struct device *dev,
 	rc = idr_alloc(&dev_nums_idr, NULL, 0, TPM_NUM_DEVICES, GFP_KERNEL);
 	mutex_unlock(&idr_lock);
 	if (rc < 0) {
-		dev_err(dev, "No available tpm device numbers\n");
+		dev_err(pdev, "No available tpm device numbers\n");
 		kfree(chip);
 		return ERR_PTR(rc);
 	}
@@ -170,7 +170,7 @@ struct tpm_chip *tpm_chip_alloc(struct device *dev,
 
 	chip->dev.class = tpm_class;
 	chip->dev.release = tpm_dev_release;
-	chip->dev.parent = dev;
+	chip->dev.parent = pdev;
 	chip->dev.groups = chip->groups;
 
 	if (chip->dev_num == 0)
@@ -182,7 +182,7 @@ struct tpm_chip *tpm_chip_alloc(struct device *dev,
 	if (rc)
 		goto out;
 
-	if (!dev)
+	if (!pdev)
 		chip->flags |= TPM_CHIP_FLAG_VIRTUAL;
 
 	cdev_init(&chip->cdev, &tpm_fops);
-- 
2.7.4

Re: [PATCH v2 3/4] tmp: use pdev for parent device in tpm_chip_alloc

[Jarkko Sakkinen]

On Wed, Nov 23, 2016 at 12:04:13PM +0200, Tomas Winkler wrote:
> The tpm stack uses pdev name convention for the parent device.
> Fix that also in tpm_chip_alloc().

Usually I'm not too fond for minor style fixes but in this case it
improves the clarity.

Reviewed-by: Jarkko Sakkinen <jarkko.sakkinen@linux.intel.com>

/Jarkko

> 
> Fixes: 3897cd9c8d1d ("tpm: Split out the devm stuff from tpmm_chip_alloc")'
> Signed-off-by: Tomas Winkler <tomas.winkler@intel.com>
> ---
> V2: resend
>  drivers/char/tpm/tpm-chip.c | 8 ++++----
>  1 file changed, 4 insertions(+), 4 deletions(-)
> 
> diff --git a/drivers/char/tpm/tpm-chip.c b/drivers/char/tpm/tpm-chip.c
> index 7a4869151d3b..eefdc809faf0 100644
> --- a/drivers/char/tpm/tpm-chip.c
> +++ b/drivers/char/tpm/tpm-chip.c
> @@ -141,7 +141,7 @@ static void tpm_dev_release(struct device *dev)
>   * Allocates a new struct tpm_chip instance and assigns a free
>   * device number for it. Must be paired with put_device(&chip->dev).
>   */
> -struct tpm_chip *tpm_chip_alloc(struct device *dev,
> +struct tpm_chip *tpm_chip_alloc(struct device *pdev,
>  				const struct tpm_class_ops *ops)
>  {
>  	struct tpm_chip *chip;
> @@ -160,7 +160,7 @@ struct tpm_chip *tpm_chip_alloc(struct device *dev,
>  	rc = idr_alloc(&dev_nums_idr, NULL, 0, TPM_NUM_DEVICES, GFP_KERNEL);
>  	mutex_unlock(&idr_lock);
>  	if (rc < 0) {
> -		dev_err(dev, "No available tpm device numbers\n");
> +		dev_err(pdev, "No available tpm device numbers\n");
>  		kfree(chip);
>  		return ERR_PTR(rc);
>  	}
> @@ -170,7 +170,7 @@ struct tpm_chip *tpm_chip_alloc(struct device *dev,
>  
>  	chip->dev.class = tpm_class;
>  	chip->dev.release = tpm_dev_release;
> -	chip->dev.parent = dev;
> +	chip->dev.parent = pdev;
>  	chip->dev.groups = chip->groups;
>  
>  	if (chip->dev_num == 0)
> @@ -182,7 +182,7 @@ struct tpm_chip *tpm_chip_alloc(struct device *dev,
>  	if (rc)
>  		goto out;
>  
> -	if (!dev)
> +	if (!pdev)
>  		chip->flags |= TPM_CHIP_FLAG_VIRTUAL;
>  
>  	cdev_init(&chip->cdev, &tpm_fops);
> -- 
> 2.7.4
> 

Re: [PATCH v2 3/4] tmp: use pdev for parent device in tpm_chip_alloc

[Jarkko Sakkinen]

On Sat, Dec 03, 2016 at 05:35:30PM +0200, Jarkko Sakkinen wrote:
> On Wed, Nov 23, 2016 at 12:04:13PM +0200, Tomas Winkler wrote:
> > The tpm stack uses pdev name convention for the parent device.
> > Fix that also in tpm_chip_alloc().
> 
> Usually I'm not too fond for minor style fixes but in this case it
> improves the clarity.
> 
> Reviewed-by: Jarkko Sakkinen <jarkko.sakkinen-VuQAYsv1563Yd54FQh9/CA@public.gmane.org>

Tested-by: Jarkko Sakkinen <jarkko.sakkinen-VuQAYsv1563Yd54FQh9/CA@public.gmane.org>

... in the sense that the changes do not break the compilation and do
not produce sparse or cocciheck errors. I guess that should be enough
for these documentation changes.

/Jarkko

------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most 
engaging tech sites, SlashDot.org! http://sdm.link/slashdot

Re: [PATCH v2 3/4] tmp: use pdev for parent device in tpm_chip_alloc

[Jarkko Sakkinen]

On Sat, Dec 03, 2016 at 05:35:30PM +0200, Jarkko Sakkinen wrote:
> On Wed, Nov 23, 2016 at 12:04:13PM +0200, Tomas Winkler wrote:
> > The tpm stack uses pdev name convention for the parent device.
> > Fix that also in tpm_chip_alloc().
> 
> Usually I'm not too fond for minor style fixes but in this case it
> improves the clarity.
> 
> Reviewed-by: Jarkko Sakkinen <jarkko.sakkinen@linux.intel.com>

Tested-by: Jarkko Sakkinen <jarkko.sakkinen@linux.intel.com>

... in the sense that the changes do not break the compilation and do
not produce sparse or cocciheck errors. I guess that should be enough
for these documentation changes.

/Jarkko

[PATCH v2 4/4] tpm/vtpm: fix kdoc warnings

[Tomas Winkler]

Use corret kdoc format for function description and eliminate warning
of type:

tpm_ibmvtpm.c:66: warning: No description found for parameter 'count'

Signed-off-by: Tomas Winkler <tomas.winkler-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>
---
V2: more fixes
 drivers/char/tpm/tpm_ibmvtpm.c    | 106 ++++++++++++++++++++------------------
 drivers/char/tpm/tpm_vtpm_proxy.c |  48 ++++++++++++-----
 2 files changed, 91 insertions(+), 63 deletions(-)

diff --git a/drivers/char/tpm/tpm_ibmvtpm.c b/drivers/char/tpm/tpm_ibmvtpm.c
index 946025a7413b..1b9d61ffe991 100644
--- a/drivers/char/tpm/tpm_ibmvtpm.c
+++ b/drivers/char/tpm/tpm_ibmvtpm.c
@@ -40,11 +40,12 @@ MODULE_DEVICE_TABLE(vio, tpm_ibmvtpm_device_table);
 
 /**
  * ibmvtpm_send_crq - Send a CRQ request
+ *
  * @vdev:	vio device struct
  * @w1:		first word
  * @w2:		second word
  *
- * Return value:
+ * Return:
  *	0 -Sucess
  *	Non-zero - Failure
  */
@@ -55,11 +56,12 @@ static int ibmvtpm_send_crq(struct vio_dev *vdev, u64 w1, u64 w2)
 
 /**
  * tpm_ibmvtpm_recv - Receive data after send
+ *
  * @chip:	tpm chip struct
  * @buf:	buffer to read
- * count:	size of buffer
+ * @count:	size of buffer
  *
- * Return value:
+ * Return:
  *	Number of bytes read
  */
 static int tpm_ibmvtpm_recv(struct tpm_chip *chip, u8 *buf, size_t count)
@@ -96,12 +98,13 @@ static int tpm_ibmvtpm_recv(struct tpm_chip *chip, u8 *buf, size_t count)
 
 /**
  * tpm_ibmvtpm_send - Send tpm request
+ *
  * @chip:	tpm chip struct
  * @buf:	buffer contains data to send
- * count:	size of buffer
+ * @count:	size of buffer
  *
- * Return value:
- *	Number of bytes sent
+ * Return:
+ *	Number of bytes sent or < 0 on error.
  */
 static int tpm_ibmvtpm_send(struct tpm_chip *chip, u8 *buf, size_t count)
 {
@@ -170,11 +173,12 @@ static u8 tpm_ibmvtpm_status(struct tpm_chip *chip)
 
 /**
  * ibmvtpm_crq_get_rtce_size - Send a CRQ request to get rtce size
+ *
  * @ibmvtpm:	vtpm device struct
  *
- * Return value:
- *	0 - Success
- *	Non-zero - Failure
+ * Return:
+ *	0 on success.
+ *	Non-zero on failure.
  */
 static int ibmvtpm_crq_get_rtce_size(struct ibmvtpm_dev *ibmvtpm)
 {
@@ -197,11 +201,12 @@ static int ibmvtpm_crq_get_rtce_size(struct ibmvtpm_dev *ibmvtpm)
 /**
  * ibmvtpm_crq_get_version - Send a CRQ request to get vtpm version
  *			   - Note that this is vtpm version and not tpm version
+ *
  * @ibmvtpm:	vtpm device struct
  *
- * Return value:
- *	0 - Success
- *	Non-zero - Failure
+ * Return:
+ *	0 on success.
+ *	Non-zero on failure.
  */
 static int ibmvtpm_crq_get_version(struct ibmvtpm_dev *ibmvtpm)
 {
@@ -225,9 +230,9 @@ static int ibmvtpm_crq_get_version(struct ibmvtpm_dev *ibmvtpm)
  * ibmvtpm_crq_send_init_complete - Send a CRQ initialize complete message
  * @ibmvtpm:	vtpm device struct
  *
- * Return value:
- *	0 - Success
- *	Non-zero - Failure
+ * Return:
+ *	0 on success.
+ *	Non-zero on failure.
  */
 static int ibmvtpm_crq_send_init_complete(struct ibmvtpm_dev *ibmvtpm)
 {
@@ -245,9 +250,9 @@ static int ibmvtpm_crq_send_init_complete(struct ibmvtpm_dev *ibmvtpm)
  * ibmvtpm_crq_send_init - Send a CRQ initialize message
  * @ibmvtpm:	vtpm device struct
  *
- * Return value:
- *	0 - Success
- *	Non-zero - Failure
+ * Return:
+ *	0 on success.
+ *	Non-zero on failure.
  */
 static int ibmvtpm_crq_send_init(struct ibmvtpm_dev *ibmvtpm)
 {
@@ -265,8 +270,7 @@ static int ibmvtpm_crq_send_init(struct ibmvtpm_dev *ibmvtpm)
  * tpm_ibmvtpm_remove - ibm vtpm remove entry point
  * @vdev:	vio device struct
  *
- * Return value:
- *	0
+ * Return: Always 0.
  */
 static int tpm_ibmvtpm_remove(struct vio_dev *vdev)
 {
@@ -303,18 +307,19 @@ static int tpm_ibmvtpm_remove(struct vio_dev *vdev)
  * tpm_ibmvtpm_get_desired_dma - Get DMA size needed by this driver
  * @vdev:	vio device struct
  *
- * Return value:
- *	Number of bytes the driver needs to DMA map
+ * Return:
+ *	Number of bytes the driver needs to DMA map.
  */
 static unsigned long tpm_ibmvtpm_get_desired_dma(struct vio_dev *vdev)
 {
 	struct tpm_chip *chip = dev_get_drvdata(&vdev->dev);
 	struct ibmvtpm_dev *ibmvtpm = dev_get_drvdata(&chip->dev);
 
-	/* ibmvtpm initializes at probe time, so the data we are
-	* asking for may not be set yet. Estimate that 4K required
-	* for TCE-mapped buffer in addition to CRQ.
-	*/
+	/*
+	 * ibmvtpm initializes at probe time, so the data we are
+	 * asking for may not be set yet. Estimate that 4K required
+	 * for TCE-mapped buffer in addition to CRQ.
+	 */
 	if (!ibmvtpm)
 		return CRQ_RES_BUF_SIZE + PAGE_SIZE;
 
@@ -325,8 +330,7 @@ static unsigned long tpm_ibmvtpm_get_desired_dma(struct vio_dev *vdev)
  * tpm_ibmvtpm_suspend - Suspend
  * @dev:	device struct
  *
- * Return value:
- *	0
+ * Return: Always 0.
  */
 static int tpm_ibmvtpm_suspend(struct device *dev)
 {
@@ -350,11 +354,12 @@ static int tpm_ibmvtpm_suspend(struct device *dev)
 
 /**
  * ibmvtpm_reset_crq - Reset CRQ
+ *
  * @ibmvtpm:	ibm vtpm struct
  *
- * Return value:
- *	0 - Success
- *	Non-zero - Failure
+ * Return:
+ *	0 on success.
+ *	Non-zero on failure.
  */
 static int ibmvtpm_reset_crq(struct ibmvtpm_dev *ibmvtpm)
 {
@@ -376,10 +381,10 @@ static int ibmvtpm_reset_crq(struct ibmvtpm_dev *ibmvtpm)
 
 /**
  * tpm_ibmvtpm_resume - Resume from suspend
+ *
  * @dev:	device struct
  *
- * Return value:
- *	0
+ * Return: Always 0.
  */
 static int tpm_ibmvtpm_resume(struct device *dev)
 {
@@ -434,10 +439,10 @@ static const struct dev_pm_ops tpm_ibmvtpm_pm_ops = {
 
 /**
  * ibmvtpm_crq_get_next - Get next responded crq
- * @ibmvtpm	vtpm device struct
  *
- * Return value:
- *	vtpm crq pointer
+ * @ibmvtpm:	vtpm device struct
+ *
+ * Return: vtpm crq pointer or NULL.
  */
 static struct ibmvtpm_crq *ibmvtpm_crq_get_next(struct ibmvtpm_dev *ibmvtpm)
 {
@@ -455,11 +460,10 @@ static struct ibmvtpm_crq *ibmvtpm_crq_get_next(struct ibmvtpm_dev *ibmvtpm)
 
 /**
  * ibmvtpm_crq_process - Process responded crq
- * @crq		crq to be processed
- * @ibmvtpm	vtpm device struct
  *
- * Return value:
- *	Nothing
+ * @crq:	crq to be processed
+ * @ibmvtpm:	vtpm device struct
+ *
  */
 static void ibmvtpm_crq_process(struct ibmvtpm_crq *crq,
 				struct ibmvtpm_dev *ibmvtpm)
@@ -528,6 +532,7 @@ static void ibmvtpm_crq_process(struct ibmvtpm_crq *crq,
 
 /**
  * ibmvtpm_interrupt -	Interrupt handler
+ *
  * @irq:		irq number to handle
  * @vtpm_instance:	vtpm that received interrupt
  *
@@ -554,12 +559,13 @@ static irqreturn_t ibmvtpm_interrupt(int irq, void *vtpm_instance)
 
 /**
  * tpm_ibmvtpm_probe - ibm vtpm initialize entry point
+ *
  * @vio_dev:	vio device struct
  * @id:		vio device id struct
  *
- * Return value:
- *	0 - Success
- *	Non-zero - Failure
+ * Return:
+ *	0 on success.
+ *	Non-zero on failure.
  */
 static int tpm_ibmvtpm_probe(struct vio_dev *vio_dev,
 				   const struct vio_device_id *id)
@@ -671,11 +677,12 @@ static struct vio_driver ibmvtpm_driver = {
 };
 
 /**
- * ibmvtpm_module_init - Initialize ibm vtpm module
+ * ibmvtpm_module_init - Initialize ibm vtpm module.
  *
- * Return value:
- *	0 -Success
- *	Non-zero - Failure
+ *
+ * Return:
+ *	0 on success.
+ *	Non-zero on failure.
  */
 static int __init ibmvtpm_module_init(void)
 {
@@ -683,10 +690,7 @@ static int __init ibmvtpm_module_init(void)
 }
 
 /**
- * ibmvtpm_module_exit - Teardown ibm vtpm module
- *
- * Return value:
- *	Nothing
+ * ibmvtpm_module_exit - Tear down ibm vtpm module.
  */
 static void __exit ibmvtpm_module_exit(void)
 {
diff --git a/drivers/char/tpm/tpm_vtpm_proxy.c b/drivers/char/tpm/tpm_vtpm_proxy.c
index 5463b58af26e..751059d2140a 100644
--- a/drivers/char/tpm/tpm_vtpm_proxy.c
+++ b/drivers/char/tpm/tpm_vtpm_proxy.c
@@ -65,7 +65,12 @@ static void vtpm_proxy_delete_device(struct proxy_dev *proxy_dev);
 /**
  * vtpm_proxy_fops_read - Read TPM commands on 'server side'
  *
- * Return value:
+ * @filp: file pointer
+ * @buf: read buffer
+ * @count: number of bytes to read
+ * @off: offset
+ *
+ * Return:
  *	Number of bytes read or negative error code
  */
 static ssize_t vtpm_proxy_fops_read(struct file *filp, char __user *buf,
@@ -115,7 +120,12 @@ static ssize_t vtpm_proxy_fops_read(struct file *filp, char __user *buf,
 /**
  * vtpm_proxy_fops_write - Write TPM responses on 'server side'
  *
- * Return value:
+ * @filp: file pointer
+ * @buf: write buffer
+ * @count: number of bytes to write
+ * @off: offset
+ *
+ * Return:
  *	Number of bytes read or negative error value
  */
 static ssize_t vtpm_proxy_fops_write(struct file *filp, const char __user *buf,
@@ -155,10 +165,12 @@ static ssize_t vtpm_proxy_fops_write(struct file *filp, const char __user *buf,
 }
 
 /*
- * vtpm_proxy_fops_poll: Poll status on 'server side'
+ * vtpm_proxy_fops_poll - Poll status on 'server side'
+ *
+ * @filp: file pointer
+ * @wait: poll table
  *
- * Return value:
- *      Poll flags
+ * Return: Poll flags
  */
 static unsigned int vtpm_proxy_fops_poll(struct file *filp, poll_table *wait)
 {
@@ -185,6 +197,8 @@ static unsigned int vtpm_proxy_fops_poll(struct file *filp, poll_table *wait)
 /*
  * vtpm_proxy_fops_open - Open vTPM device on 'server side'
  *
+ * @filp: file pointer
+ *
  * Called when setting up the anonymous file descriptor
  */
 static void vtpm_proxy_fops_open(struct file *filp)
@@ -196,8 +210,9 @@ static void vtpm_proxy_fops_open(struct file *filp)
 
 /**
  * vtpm_proxy_fops_undo_open - counter-part to vtpm_fops_open
+ *       Call to undo vtpm_proxy_fops_open
  *
- * Call to undo vtpm_proxy_fops_open
+ *@proxy_dev: tpm proxy device
  */
 static void vtpm_proxy_fops_undo_open(struct proxy_dev *proxy_dev)
 {
@@ -212,9 +227,11 @@ static void vtpm_proxy_fops_undo_open(struct proxy_dev *proxy_dev)
 }
 
 /*
- * vtpm_proxy_fops_release: Close 'server side'
+ * vtpm_proxy_fops_release - Close 'server side'
  *
- * Return value:
+ * @inode: inode
+ * @filp: file pointer
+ * Return:
  *      Always returns 0.
  */
 static int vtpm_proxy_fops_release(struct inode *inode, struct file *filp)
@@ -245,7 +262,10 @@ static const struct file_operations vtpm_proxy_fops = {
 /*
  * Called when core TPM driver reads TPM responses from 'server side'
  *
- * Return value:
+ * @chip: tpm chip to use
+ * @buf: receive buffer
+ * @count: bytes to read
+ * Return:
  *      Number of TPM response bytes read, negative error value otherwise
  */
 static int vtpm_proxy_tpm_op_recv(struct tpm_chip *chip, u8 *buf, size_t count)
@@ -282,7 +302,11 @@ static int vtpm_proxy_tpm_op_recv(struct tpm_chip *chip, u8 *buf, size_t count)
 /*
  * Called when core TPM driver forwards TPM requests to 'server side'.
  *
- * Return value:
+ * @chip: tpm chip to use
+ * @buf: send buffer
+ * @count: bytes to send
+ *
+ * Return:
  *      0 in case of success, negative error value otherwise.
  */
 static int vtpm_proxy_tpm_op_send(struct tpm_chip *chip, u8 *buf, size_t count)
@@ -442,7 +466,7 @@ static inline void vtpm_proxy_delete_proxy_dev(struct proxy_dev *proxy_dev)
 /*
  * Create a /dev/tpm%d and 'server side' file descriptor pair
  *
- * Return value:
+ * Return:
  *      Returns file pointer on success, an error value otherwise
  */
 static struct file *vtpm_proxy_create_device(
@@ -571,7 +595,7 @@ static long vtpmx_ioc_new_dev(struct file *file, unsigned int ioctl,
 /*
  * vtpmx_fops_ioctl: ioctl on /dev/vtpmx
  *
- * Return value:
+ * Return:
  *      Returns 0 on success, a negative error code otherwise.
  */
 static long vtpmx_fops_ioctl(struct file *f, unsigned int ioctl,
-- 
2.7.4


------------------------------------------------------------------------------

[PATCH v2 4/4] tpm/vtpm: fix kdoc warnings

[Tomas Winkler]

Use corret kdoc format for function description and eliminate warning
of type:

tpm_ibmvtpm.c:66: warning: No description found for parameter 'count'

Signed-off-by: Tomas Winkler <tomas.winkler@intel.com>
---
V2: more fixes
 drivers/char/tpm/tpm_ibmvtpm.c    | 106 ++++++++++++++++++++------------------
 drivers/char/tpm/tpm_vtpm_proxy.c |  48 ++++++++++++-----
 2 files changed, 91 insertions(+), 63 deletions(-)

diff --git a/drivers/char/tpm/tpm_ibmvtpm.c b/drivers/char/tpm/tpm_ibmvtpm.c
index 946025a7413b..1b9d61ffe991 100644
--- a/drivers/char/tpm/tpm_ibmvtpm.c
+++ b/drivers/char/tpm/tpm_ibmvtpm.c
@@ -40,11 +40,12 @@ MODULE_DEVICE_TABLE(vio, tpm_ibmvtpm_device_table);
 
 /**
  * ibmvtpm_send_crq - Send a CRQ request
+ *
  * @vdev:	vio device struct
  * @w1:		first word
  * @w2:		second word
  *
- * Return value:
+ * Return:
  *	0 -Sucess
  *	Non-zero - Failure
  */
@@ -55,11 +56,12 @@ static int ibmvtpm_send_crq(struct vio_dev *vdev, u64 w1, u64 w2)
 
 /**
  * tpm_ibmvtpm_recv - Receive data after send
+ *
  * @chip:	tpm chip struct
  * @buf:	buffer to read
- * count:	size of buffer
+ * @count:	size of buffer
  *
- * Return value:
+ * Return:
  *	Number of bytes read
  */
 static int tpm_ibmvtpm_recv(struct tpm_chip *chip, u8 *buf, size_t count)
@@ -96,12 +98,13 @@ static int tpm_ibmvtpm_recv(struct tpm_chip *chip, u8 *buf, size_t count)
 
 /**
  * tpm_ibmvtpm_send - Send tpm request
+ *
  * @chip:	tpm chip struct
  * @buf:	buffer contains data to send
- * count:	size of buffer
+ * @count:	size of buffer
  *
- * Return value:
- *	Number of bytes sent
+ * Return:
+ *	Number of bytes sent or < 0 on error.
  */
 static int tpm_ibmvtpm_send(struct tpm_chip *chip, u8 *buf, size_t count)
 {
@@ -170,11 +173,12 @@ static u8 tpm_ibmvtpm_status(struct tpm_chip *chip)
 
 /**
  * ibmvtpm_crq_get_rtce_size - Send a CRQ request to get rtce size
+ *
  * @ibmvtpm:	vtpm device struct
  *
- * Return value:
- *	0 - Success
- *	Non-zero - Failure
+ * Return:
+ *	0 on success.
+ *	Non-zero on failure.
  */
 static int ibmvtpm_crq_get_rtce_size(struct ibmvtpm_dev *ibmvtpm)
 {
@@ -197,11 +201,12 @@ static int ibmvtpm_crq_get_rtce_size(struct ibmvtpm_dev *ibmvtpm)
 /**
  * ibmvtpm_crq_get_version - Send a CRQ request to get vtpm version
  *			   - Note that this is vtpm version and not tpm version
+ *
  * @ibmvtpm:	vtpm device struct
  *
- * Return value:
- *	0 - Success
- *	Non-zero - Failure
+ * Return:
+ *	0 on success.
+ *	Non-zero on failure.
  */
 static int ibmvtpm_crq_get_version(struct ibmvtpm_dev *ibmvtpm)
 {
@@ -225,9 +230,9 @@ static int ibmvtpm_crq_get_version(struct ibmvtpm_dev *ibmvtpm)
  * ibmvtpm_crq_send_init_complete - Send a CRQ initialize complete message
  * @ibmvtpm:	vtpm device struct
  *
- * Return value:
- *	0 - Success
- *	Non-zero - Failure
+ * Return:
+ *	0 on success.
+ *	Non-zero on failure.
  */
 static int ibmvtpm_crq_send_init_complete(struct ibmvtpm_dev *ibmvtpm)
 {
@@ -245,9 +250,9 @@ static int ibmvtpm_crq_send_init_complete(struct ibmvtpm_dev *ibmvtpm)
  * ibmvtpm_crq_send_init - Send a CRQ initialize message
  * @ibmvtpm:	vtpm device struct
  *
- * Return value:
- *	0 - Success
- *	Non-zero - Failure
+ * Return:
+ *	0 on success.
+ *	Non-zero on failure.
  */
 static int ibmvtpm_crq_send_init(struct ibmvtpm_dev *ibmvtpm)
 {
@@ -265,8 +270,7 @@ static int ibmvtpm_crq_send_init(struct ibmvtpm_dev *ibmvtpm)
  * tpm_ibmvtpm_remove - ibm vtpm remove entry point
  * @vdev:	vio device struct
  *
- * Return value:
- *	0
+ * Return: Always 0.
  */
 static int tpm_ibmvtpm_remove(struct vio_dev *vdev)
 {
@@ -303,18 +307,19 @@ static int tpm_ibmvtpm_remove(struct vio_dev *vdev)
  * tpm_ibmvtpm_get_desired_dma - Get DMA size needed by this driver
  * @vdev:	vio device struct
  *
- * Return value:
- *	Number of bytes the driver needs to DMA map
+ * Return:
+ *	Number of bytes the driver needs to DMA map.
  */
 static unsigned long tpm_ibmvtpm_get_desired_dma(struct vio_dev *vdev)
 {
 	struct tpm_chip *chip = dev_get_drvdata(&vdev->dev);
 	struct ibmvtpm_dev *ibmvtpm = dev_get_drvdata(&chip->dev);
 
-	/* ibmvtpm initializes at probe time, so the data we are
-	* asking for may not be set yet. Estimate that 4K required
-	* for TCE-mapped buffer in addition to CRQ.
-	*/
+	/*
+	 * ibmvtpm initializes at probe time, so the data we are
+	 * asking for may not be set yet. Estimate that 4K required
+	 * for TCE-mapped buffer in addition to CRQ.
+	 */
 	if (!ibmvtpm)
 		return CRQ_RES_BUF_SIZE + PAGE_SIZE;
 
@@ -325,8 +330,7 @@ static unsigned long tpm_ibmvtpm_get_desired_dma(struct vio_dev *vdev)
  * tpm_ibmvtpm_suspend - Suspend
  * @dev:	device struct
  *
- * Return value:
- *	0
+ * Return: Always 0.
  */
 static int tpm_ibmvtpm_suspend(struct device *dev)
 {
@@ -350,11 +354,12 @@ static int tpm_ibmvtpm_suspend(struct device *dev)
 
 /**
  * ibmvtpm_reset_crq - Reset CRQ
+ *
  * @ibmvtpm:	ibm vtpm struct
  *
- * Return value:
- *	0 - Success
- *	Non-zero - Failure
+ * Return:
+ *	0 on success.
+ *	Non-zero on failure.
  */
 static int ibmvtpm_reset_crq(struct ibmvtpm_dev *ibmvtpm)
 {
@@ -376,10 +381,10 @@ static int ibmvtpm_reset_crq(struct ibmvtpm_dev *ibmvtpm)
 
 /**
  * tpm_ibmvtpm_resume - Resume from suspend
+ *
  * @dev:	device struct
  *
- * Return value:
- *	0
+ * Return: Always 0.
  */
 static int tpm_ibmvtpm_resume(struct device *dev)
 {
@@ -434,10 +439,10 @@ static const struct dev_pm_ops tpm_ibmvtpm_pm_ops = {
 
 /**
  * ibmvtpm_crq_get_next - Get next responded crq
- * @ibmvtpm	vtpm device struct
  *
- * Return value:
- *	vtpm crq pointer
+ * @ibmvtpm:	vtpm device struct
+ *
+ * Return: vtpm crq pointer or NULL.
  */
 static struct ibmvtpm_crq *ibmvtpm_crq_get_next(struct ibmvtpm_dev *ibmvtpm)
 {
@@ -455,11 +460,10 @@ static struct ibmvtpm_crq *ibmvtpm_crq_get_next(struct ibmvtpm_dev *ibmvtpm)
 
 /**
  * ibmvtpm_crq_process - Process responded crq
- * @crq		crq to be processed
- * @ibmvtpm	vtpm device struct
  *
- * Return value:
- *	Nothing
+ * @crq:	crq to be processed
+ * @ibmvtpm:	vtpm device struct
+ *
  */
 static void ibmvtpm_crq_process(struct ibmvtpm_crq *crq,
 				struct ibmvtpm_dev *ibmvtpm)
@@ -528,6 +532,7 @@ static void ibmvtpm_crq_process(struct ibmvtpm_crq *crq,
 
 /**
  * ibmvtpm_interrupt -	Interrupt handler
+ *
  * @irq:		irq number to handle
  * @vtpm_instance:	vtpm that received interrupt
  *
@@ -554,12 +559,13 @@ static irqreturn_t ibmvtpm_interrupt(int irq, void *vtpm_instance)
 
 /**
  * tpm_ibmvtpm_probe - ibm vtpm initialize entry point
+ *
  * @vio_dev:	vio device struct
  * @id:		vio device id struct
  *
- * Return value:
- *	0 - Success
- *	Non-zero - Failure
+ * Return:
+ *	0 on success.
+ *	Non-zero on failure.
  */
 static int tpm_ibmvtpm_probe(struct vio_dev *vio_dev,
 				   const struct vio_device_id *id)
@@ -671,11 +677,12 @@ static struct vio_driver ibmvtpm_driver = {
 };
 
 /**
- * ibmvtpm_module_init - Initialize ibm vtpm module
+ * ibmvtpm_module_init - Initialize ibm vtpm module.
  *
- * Return value:
- *	0 -Success
- *	Non-zero - Failure
+ *
+ * Return:
+ *	0 on success.
+ *	Non-zero on failure.
  */
 static int __init ibmvtpm_module_init(void)
 {
@@ -683,10 +690,7 @@ static int __init ibmvtpm_module_init(void)
 }
 
 /**
- * ibmvtpm_module_exit - Teardown ibm vtpm module
- *
- * Return value:
- *	Nothing
+ * ibmvtpm_module_exit - Tear down ibm vtpm module.
  */
 static void __exit ibmvtpm_module_exit(void)
 {
diff --git a/drivers/char/tpm/tpm_vtpm_proxy.c b/drivers/char/tpm/tpm_vtpm_proxy.c
index 5463b58af26e..751059d2140a 100644
--- a/drivers/char/tpm/tpm_vtpm_proxy.c
+++ b/drivers/char/tpm/tpm_vtpm_proxy.c
@@ -65,7 +65,12 @@ static void vtpm_proxy_delete_device(struct proxy_dev *proxy_dev);
 /**
  * vtpm_proxy_fops_read - Read TPM commands on 'server side'
  *
- * Return value:
+ * @filp: file pointer
+ * @buf: read buffer
+ * @count: number of bytes to read
+ * @off: offset
+ *
+ * Return:
  *	Number of bytes read or negative error code
  */
 static ssize_t vtpm_proxy_fops_read(struct file *filp, char __user *buf,
@@ -115,7 +120,12 @@ static ssize_t vtpm_proxy_fops_read(struct file *filp, char __user *buf,
 /**
  * vtpm_proxy_fops_write - Write TPM responses on 'server side'
  *
- * Return value:
+ * @filp: file pointer
+ * @buf: write buffer
+ * @count: number of bytes to write
+ * @off: offset
+ *
+ * Return:
  *	Number of bytes read or negative error value
  */
 static ssize_t vtpm_proxy_fops_write(struct file *filp, const char __user *buf,
@@ -155,10 +165,12 @@ static ssize_t vtpm_proxy_fops_write(struct file *filp, const char __user *buf,
 }
 
 /*
- * vtpm_proxy_fops_poll: Poll status on 'server side'
+ * vtpm_proxy_fops_poll - Poll status on 'server side'
+ *
+ * @filp: file pointer
+ * @wait: poll table
  *
- * Return value:
- *      Poll flags
+ * Return: Poll flags
  */
 static unsigned int vtpm_proxy_fops_poll(struct file *filp, poll_table *wait)
 {
@@ -185,6 +197,8 @@ static unsigned int vtpm_proxy_fops_poll(struct file *filp, poll_table *wait)
 /*
  * vtpm_proxy_fops_open - Open vTPM device on 'server side'
  *
+ * @filp: file pointer
+ *
  * Called when setting up the anonymous file descriptor
  */
 static void vtpm_proxy_fops_open(struct file *filp)
@@ -196,8 +210,9 @@ static void vtpm_proxy_fops_open(struct file *filp)
 
 /**
  * vtpm_proxy_fops_undo_open - counter-part to vtpm_fops_open
+ *       Call to undo vtpm_proxy_fops_open
  *
- * Call to undo vtpm_proxy_fops_open
+ *@proxy_dev: tpm proxy device
  */
 static void vtpm_proxy_fops_undo_open(struct proxy_dev *proxy_dev)
 {
@@ -212,9 +227,11 @@ static void vtpm_proxy_fops_undo_open(struct proxy_dev *proxy_dev)
 }
 
 /*
- * vtpm_proxy_fops_release: Close 'server side'
+ * vtpm_proxy_fops_release - Close 'server side'
  *
- * Return value:
+ * @inode: inode
+ * @filp: file pointer
+ * Return:
  *      Always returns 0.
  */
 static int vtpm_proxy_fops_release(struct inode *inode, struct file *filp)
@@ -245,7 +262,10 @@ static const struct file_operations vtpm_proxy_fops = {
 /*
  * Called when core TPM driver reads TPM responses from 'server side'
  *
- * Return value:
+ * @chip: tpm chip to use
+ * @buf: receive buffer
+ * @count: bytes to read
+ * Return:
  *      Number of TPM response bytes read, negative error value otherwise
  */
 static int vtpm_proxy_tpm_op_recv(struct tpm_chip *chip, u8 *buf, size_t count)
@@ -282,7 +302,11 @@ static int vtpm_proxy_tpm_op_recv(struct tpm_chip *chip, u8 *buf, size_t count)
 /*
  * Called when core TPM driver forwards TPM requests to 'server side'.
  *
- * Return value:
+ * @chip: tpm chip to use
+ * @buf: send buffer
+ * @count: bytes to send
+ *
+ * Return:
  *      0 in case of success, negative error value otherwise.
  */
 static int vtpm_proxy_tpm_op_send(struct tpm_chip *chip, u8 *buf, size_t count)
@@ -442,7 +466,7 @@ static inline void vtpm_proxy_delete_proxy_dev(struct proxy_dev *proxy_dev)
 /*
  * Create a /dev/tpm%d and 'server side' file descriptor pair
  *
- * Return value:
+ * Return:
  *      Returns file pointer on success, an error value otherwise
  */
 static struct file *vtpm_proxy_create_device(
@@ -571,7 +595,7 @@ static long vtpmx_ioc_new_dev(struct file *file, unsigned int ioctl,
 /*
  * vtpmx_fops_ioctl: ioctl on /dev/vtpmx
  *
- * Return value:
+ * Return:
  *      Returns 0 on success, a negative error code otherwise.
  */
 static long vtpmx_fops_ioctl(struct file *f, unsigned int ioctl,
-- 
2.7.4

Re: [PATCH v2 4/4] tpm/vtpm: fix kdoc warnings

[Jarkko Sakkinen]

On Wed, Nov 23, 2016 at 12:04:14PM +0200, Tomas Winkler wrote:
> Use corret kdoc format for function description and eliminate warning
> of type:
> 
> tpm_ibmvtpm.c:66: warning: No description found for parameter 'count'
> 
> Signed-off-by: Tomas Winkler <tomas.winkler@intel.com>

Reviewed-by: Jarkko Sakkinen <jarkko.sakkinen@linux.intel.com>

/Jarkkko

> ---
> V2: more fixes
>  drivers/char/tpm/tpm_ibmvtpm.c    | 106 ++++++++++++++++++++------------------
>  drivers/char/tpm/tpm_vtpm_proxy.c |  48 ++++++++++++-----
>  2 files changed, 91 insertions(+), 63 deletions(-)
> 
> diff --git a/drivers/char/tpm/tpm_ibmvtpm.c b/drivers/char/tpm/tpm_ibmvtpm.c
> index 946025a7413b..1b9d61ffe991 100644
> --- a/drivers/char/tpm/tpm_ibmvtpm.c
> +++ b/drivers/char/tpm/tpm_ibmvtpm.c
> @@ -40,11 +40,12 @@ MODULE_DEVICE_TABLE(vio, tpm_ibmvtpm_device_table);
>  
>  /**
>   * ibmvtpm_send_crq - Send a CRQ request
> + *
>   * @vdev:	vio device struct
>   * @w1:		first word
>   * @w2:		second word
>   *
> - * Return value:
> + * Return:
>   *	0 -Sucess
>   *	Non-zero - Failure
>   */
> @@ -55,11 +56,12 @@ static int ibmvtpm_send_crq(struct vio_dev *vdev, u64 w1, u64 w2)
>  
>  /**
>   * tpm_ibmvtpm_recv - Receive data after send
> + *
>   * @chip:	tpm chip struct
>   * @buf:	buffer to read
> - * count:	size of buffer
> + * @count:	size of buffer
>   *
> - * Return value:
> + * Return:
>   *	Number of bytes read
>   */
>  static int tpm_ibmvtpm_recv(struct tpm_chip *chip, u8 *buf, size_t count)
> @@ -96,12 +98,13 @@ static int tpm_ibmvtpm_recv(struct tpm_chip *chip, u8 *buf, size_t count)
>  
>  /**
>   * tpm_ibmvtpm_send - Send tpm request
> + *
>   * @chip:	tpm chip struct
>   * @buf:	buffer contains data to send
> - * count:	size of buffer
> + * @count:	size of buffer
>   *
> - * Return value:
> - *	Number of bytes sent
> + * Return:
> + *	Number of bytes sent or < 0 on error.
>   */
>  static int tpm_ibmvtpm_send(struct tpm_chip *chip, u8 *buf, size_t count)
>  {
> @@ -170,11 +173,12 @@ static u8 tpm_ibmvtpm_status(struct tpm_chip *chip)
>  
>  /**
>   * ibmvtpm_crq_get_rtce_size - Send a CRQ request to get rtce size
> + *
>   * @ibmvtpm:	vtpm device struct
>   *
> - * Return value:
> - *	0 - Success
> - *	Non-zero - Failure
> + * Return:
> + *	0 on success.
> + *	Non-zero on failure.
>   */
>  static int ibmvtpm_crq_get_rtce_size(struct ibmvtpm_dev *ibmvtpm)
>  {
> @@ -197,11 +201,12 @@ static int ibmvtpm_crq_get_rtce_size(struct ibmvtpm_dev *ibmvtpm)
>  /**
>   * ibmvtpm_crq_get_version - Send a CRQ request to get vtpm version
>   *			   - Note that this is vtpm version and not tpm version
> + *
>   * @ibmvtpm:	vtpm device struct
>   *
> - * Return value:
> - *	0 - Success
> - *	Non-zero - Failure
> + * Return:
> + *	0 on success.
> + *	Non-zero on failure.
>   */
>  static int ibmvtpm_crq_get_version(struct ibmvtpm_dev *ibmvtpm)
>  {
> @@ -225,9 +230,9 @@ static int ibmvtpm_crq_get_version(struct ibmvtpm_dev *ibmvtpm)
>   * ibmvtpm_crq_send_init_complete - Send a CRQ initialize complete message
>   * @ibmvtpm:	vtpm device struct
>   *
> - * Return value:
> - *	0 - Success
> - *	Non-zero - Failure
> + * Return:
> + *	0 on success.
> + *	Non-zero on failure.
>   */
>  static int ibmvtpm_crq_send_init_complete(struct ibmvtpm_dev *ibmvtpm)
>  {
> @@ -245,9 +250,9 @@ static int ibmvtpm_crq_send_init_complete(struct ibmvtpm_dev *ibmvtpm)
>   * ibmvtpm_crq_send_init - Send a CRQ initialize message
>   * @ibmvtpm:	vtpm device struct
>   *
> - * Return value:
> - *	0 - Success
> - *	Non-zero - Failure
> + * Return:
> + *	0 on success.
> + *	Non-zero on failure.
>   */
>  static int ibmvtpm_crq_send_init(struct ibmvtpm_dev *ibmvtpm)
>  {
> @@ -265,8 +270,7 @@ static int ibmvtpm_crq_send_init(struct ibmvtpm_dev *ibmvtpm)
>   * tpm_ibmvtpm_remove - ibm vtpm remove entry point
>   * @vdev:	vio device struct
>   *
> - * Return value:
> - *	0
> + * Return: Always 0.
>   */
>  static int tpm_ibmvtpm_remove(struct vio_dev *vdev)
>  {
> @@ -303,18 +307,19 @@ static int tpm_ibmvtpm_remove(struct vio_dev *vdev)
>   * tpm_ibmvtpm_get_desired_dma - Get DMA size needed by this driver
>   * @vdev:	vio device struct
>   *
> - * Return value:
> - *	Number of bytes the driver needs to DMA map
> + * Return:
> + *	Number of bytes the driver needs to DMA map.
>   */
>  static unsigned long tpm_ibmvtpm_get_desired_dma(struct vio_dev *vdev)
>  {
>  	struct tpm_chip *chip = dev_get_drvdata(&vdev->dev);
>  	struct ibmvtpm_dev *ibmvtpm = dev_get_drvdata(&chip->dev);
>  
> -	/* ibmvtpm initializes at probe time, so the data we are
> -	* asking for may not be set yet. Estimate that 4K required
> -	* for TCE-mapped buffer in addition to CRQ.
> -	*/
> +	/*
> +	 * ibmvtpm initializes at probe time, so the data we are
> +	 * asking for may not be set yet. Estimate that 4K required
> +	 * for TCE-mapped buffer in addition to CRQ.
> +	 */
>  	if (!ibmvtpm)
>  		return CRQ_RES_BUF_SIZE + PAGE_SIZE;
>  
> @@ -325,8 +330,7 @@ static unsigned long tpm_ibmvtpm_get_desired_dma(struct vio_dev *vdev)
>   * tpm_ibmvtpm_suspend - Suspend
>   * @dev:	device struct
>   *
> - * Return value:
> - *	0
> + * Return: Always 0.
>   */
>  static int tpm_ibmvtpm_suspend(struct device *dev)
>  {
> @@ -350,11 +354,12 @@ static int tpm_ibmvtpm_suspend(struct device *dev)
>  
>  /**
>   * ibmvtpm_reset_crq - Reset CRQ
> + *
>   * @ibmvtpm:	ibm vtpm struct
>   *
> - * Return value:
> - *	0 - Success
> - *	Non-zero - Failure
> + * Return:
> + *	0 on success.
> + *	Non-zero on failure.
>   */
>  static int ibmvtpm_reset_crq(struct ibmvtpm_dev *ibmvtpm)
>  {
> @@ -376,10 +381,10 @@ static int ibmvtpm_reset_crq(struct ibmvtpm_dev *ibmvtpm)
>  
>  /**
>   * tpm_ibmvtpm_resume - Resume from suspend
> + *
>   * @dev:	device struct
>   *
> - * Return value:
> - *	0
> + * Return: Always 0.
>   */
>  static int tpm_ibmvtpm_resume(struct device *dev)
>  {
> @@ -434,10 +439,10 @@ static const struct dev_pm_ops tpm_ibmvtpm_pm_ops = {
>  
>  /**
>   * ibmvtpm_crq_get_next - Get next responded crq
> - * @ibmvtpm	vtpm device struct
>   *
> - * Return value:
> - *	vtpm crq pointer
> + * @ibmvtpm:	vtpm device struct
> + *
> + * Return: vtpm crq pointer or NULL.
>   */
>  static struct ibmvtpm_crq *ibmvtpm_crq_get_next(struct ibmvtpm_dev *ibmvtpm)
>  {
> @@ -455,11 +460,10 @@ static struct ibmvtpm_crq *ibmvtpm_crq_get_next(struct ibmvtpm_dev *ibmvtpm)
>  
>  /**
>   * ibmvtpm_crq_process - Process responded crq
> - * @crq		crq to be processed
> - * @ibmvtpm	vtpm device struct
>   *
> - * Return value:
> - *	Nothing
> + * @crq:	crq to be processed
> + * @ibmvtpm:	vtpm device struct
> + *
>   */
>  static void ibmvtpm_crq_process(struct ibmvtpm_crq *crq,
>  				struct ibmvtpm_dev *ibmvtpm)
> @@ -528,6 +532,7 @@ static void ibmvtpm_crq_process(struct ibmvtpm_crq *crq,
>  
>  /**
>   * ibmvtpm_interrupt -	Interrupt handler
> + *
>   * @irq:		irq number to handle
>   * @vtpm_instance:	vtpm that received interrupt
>   *
> @@ -554,12 +559,13 @@ static irqreturn_t ibmvtpm_interrupt(int irq, void *vtpm_instance)
>  
>  /**
>   * tpm_ibmvtpm_probe - ibm vtpm initialize entry point
> + *
>   * @vio_dev:	vio device struct
>   * @id:		vio device id struct
>   *
> - * Return value:
> - *	0 - Success
> - *	Non-zero - Failure
> + * Return:
> + *	0 on success.
> + *	Non-zero on failure.
>   */
>  static int tpm_ibmvtpm_probe(struct vio_dev *vio_dev,
>  				   const struct vio_device_id *id)
> @@ -671,11 +677,12 @@ static struct vio_driver ibmvtpm_driver = {
>  };
>  
>  /**
> - * ibmvtpm_module_init - Initialize ibm vtpm module
> + * ibmvtpm_module_init - Initialize ibm vtpm module.
>   *
> - * Return value:
> - *	0 -Success
> - *	Non-zero - Failure
> + *
> + * Return:
> + *	0 on success.
> + *	Non-zero on failure.
>   */
>  static int __init ibmvtpm_module_init(void)
>  {
> @@ -683,10 +690,7 @@ static int __init ibmvtpm_module_init(void)
>  }
>  
>  /**
> - * ibmvtpm_module_exit - Teardown ibm vtpm module
> - *
> - * Return value:
> - *	Nothing
> + * ibmvtpm_module_exit - Tear down ibm vtpm module.
>   */
>  static void __exit ibmvtpm_module_exit(void)
>  {
> diff --git a/drivers/char/tpm/tpm_vtpm_proxy.c b/drivers/char/tpm/tpm_vtpm_proxy.c
> index 5463b58af26e..751059d2140a 100644
> --- a/drivers/char/tpm/tpm_vtpm_proxy.c
> +++ b/drivers/char/tpm/tpm_vtpm_proxy.c
> @@ -65,7 +65,12 @@ static void vtpm_proxy_delete_device(struct proxy_dev *proxy_dev);
>  /**
>   * vtpm_proxy_fops_read - Read TPM commands on 'server side'
>   *
> - * Return value:
> + * @filp: file pointer
> + * @buf: read buffer
> + * @count: number of bytes to read
> + * @off: offset
> + *
> + * Return:
>   *	Number of bytes read or negative error code
>   */
>  static ssize_t vtpm_proxy_fops_read(struct file *filp, char __user *buf,
> @@ -115,7 +120,12 @@ static ssize_t vtpm_proxy_fops_read(struct file *filp, char __user *buf,
>  /**
>   * vtpm_proxy_fops_write - Write TPM responses on 'server side'
>   *
> - * Return value:
> + * @filp: file pointer
> + * @buf: write buffer
> + * @count: number of bytes to write
> + * @off: offset
> + *
> + * Return:
>   *	Number of bytes read or negative error value
>   */
>  static ssize_t vtpm_proxy_fops_write(struct file *filp, const char __user *buf,
> @@ -155,10 +165,12 @@ static ssize_t vtpm_proxy_fops_write(struct file *filp, const char __user *buf,
>  }
>  
>  /*
> - * vtpm_proxy_fops_poll: Poll status on 'server side'
> + * vtpm_proxy_fops_poll - Poll status on 'server side'
> + *
> + * @filp: file pointer
> + * @wait: poll table
>   *
> - * Return value:
> - *      Poll flags
> + * Return: Poll flags
>   */
>  static unsigned int vtpm_proxy_fops_poll(struct file *filp, poll_table *wait)
>  {
> @@ -185,6 +197,8 @@ static unsigned int vtpm_proxy_fops_poll(struct file *filp, poll_table *wait)
>  /*
>   * vtpm_proxy_fops_open - Open vTPM device on 'server side'
>   *
> + * @filp: file pointer
> + *
>   * Called when setting up the anonymous file descriptor
>   */
>  static void vtpm_proxy_fops_open(struct file *filp)
> @@ -196,8 +210,9 @@ static void vtpm_proxy_fops_open(struct file *filp)
>  
>  /**
>   * vtpm_proxy_fops_undo_open - counter-part to vtpm_fops_open
> + *       Call to undo vtpm_proxy_fops_open
>   *
> - * Call to undo vtpm_proxy_fops_open
> + *@proxy_dev: tpm proxy device
>   */
>  static void vtpm_proxy_fops_undo_open(struct proxy_dev *proxy_dev)
>  {
> @@ -212,9 +227,11 @@ static void vtpm_proxy_fops_undo_open(struct proxy_dev *proxy_dev)
>  }
>  
>  /*
> - * vtpm_proxy_fops_release: Close 'server side'
> + * vtpm_proxy_fops_release - Close 'server side'
>   *
> - * Return value:
> + * @inode: inode
> + * @filp: file pointer
> + * Return:
>   *      Always returns 0.
>   */
>  static int vtpm_proxy_fops_release(struct inode *inode, struct file *filp)
> @@ -245,7 +262,10 @@ static const struct file_operations vtpm_proxy_fops = {
>  /*
>   * Called when core TPM driver reads TPM responses from 'server side'
>   *
> - * Return value:
> + * @chip: tpm chip to use
> + * @buf: receive buffer
> + * @count: bytes to read
> + * Return:
>   *      Number of TPM response bytes read, negative error value otherwise
>   */
>  static int vtpm_proxy_tpm_op_recv(struct tpm_chip *chip, u8 *buf, size_t count)
> @@ -282,7 +302,11 @@ static int vtpm_proxy_tpm_op_recv(struct tpm_chip *chip, u8 *buf, size_t count)
>  /*
>   * Called when core TPM driver forwards TPM requests to 'server side'.
>   *
> - * Return value:
> + * @chip: tpm chip to use
> + * @buf: send buffer
> + * @count: bytes to send
> + *
> + * Return:
>   *      0 in case of success, negative error value otherwise.
>   */
>  static int vtpm_proxy_tpm_op_send(struct tpm_chip *chip, u8 *buf, size_t count)
> @@ -442,7 +466,7 @@ static inline void vtpm_proxy_delete_proxy_dev(struct proxy_dev *proxy_dev)
>  /*
>   * Create a /dev/tpm%d and 'server side' file descriptor pair
>   *
> - * Return value:
> + * Return:
>   *      Returns file pointer on success, an error value otherwise
>   */
>  static struct file *vtpm_proxy_create_device(
> @@ -571,7 +595,7 @@ static long vtpmx_ioc_new_dev(struct file *file, unsigned int ioctl,
>  /*
>   * vtpmx_fops_ioctl: ioctl on /dev/vtpmx
>   *
> - * Return value:
> + * Return:
>   *      Returns 0 on success, a negative error code otherwise.
>   */
>  static long vtpmx_fops_ioctl(struct file *f, unsigned int ioctl,
> -- 
> 2.7.4
> 

Re: [PATCH v2 4/4] tpm/vtpm: fix kdoc warnings

[Jarkko Sakkinen]

On Sat, Dec 03, 2016 at 05:36:04PM +0200, Jarkko Sakkinen wrote:
> On Wed, Nov 23, 2016 at 12:04:14PM +0200, Tomas Winkler wrote:
> > Use corret kdoc format for function description and eliminate warning
> > of type:
> > 
> > tpm_ibmvtpm.c:66: warning: No description found for parameter 'count'
> > 
> > Signed-off-by: Tomas Winkler <tomas.winkler@intel.com>
> 
> Reviewed-by: Jarkko Sakkinen <jarkko.sakkinen@linux.intel.com>

Tested-by: Jarkko Sakkinen <jarkko.sakkinen@linux.intel.com>

... in the sense that the changes do not break the compilation and do
not produce sparse or cocciheck errors. I guess that should be enough
for these documentation changes.

/Jarkko

Re: [PATCH v2 0/4] tpm: kdoc cleanup

[Jarkko Sakkinen]

On Wed, Nov 23, 2016 at 12:04:10PM +0200, Tomas Winkler wrote:
> Cleanup tpm in-code documentation.
> 
> Tomas Winkler (4):
>   tpm: add kdoc for tpm_transmit and tpm_transmit_cmd
>   tpm/tpm2-chip: fix kdoc errors
>   tmp: use pdev for parent device in tpm_chip_alloc
>   tpm/vtpm: fix kdoc warnings

Thanks. Overally LGTM but I have to postpone the review till' next week.

/Jarkko

> 
>  drivers/char/tpm/tpm-chip.c       |   8 +--
>  drivers/char/tpm/tpm-interface.c  |  33 ++++++++++--
>  drivers/char/tpm/tpm2-cmd.c       | 105 +++++++++++++++++++++-----------------
>  drivers/char/tpm/tpm_ibmvtpm.c    |  51 +++++++++---------
>  drivers/char/tpm/tpm_vtpm_proxy.c |  48 ++++++++++++-----
>  5 files changed, 150 insertions(+), 95 deletions(-)
> 
> -- 
> 2.7.4
> 

------------------------------------------------------------------------------

Re: [PATCH v2 0/4] tpm: kdoc cleanup

[Jarkko Sakkinen]

On Wed, Nov 23, 2016 at 12:04:10PM +0200, Tomas Winkler wrote:
> Cleanup tpm in-code documentation.
> 
> Tomas Winkler (4):
>   tpm: add kdoc for tpm_transmit and tpm_transmit_cmd
>   tpm/tpm2-chip: fix kdoc errors
>   tmp: use pdev for parent device in tpm_chip_alloc
>   tpm/vtpm: fix kdoc warnings

Thanks. Overally LGTM but I have to postpone the review till' next week.

/Jarkko

> 
>  drivers/char/tpm/tpm-chip.c       |   8 +--
>  drivers/char/tpm/tpm-interface.c  |  33 ++++++++++--
>  drivers/char/tpm/tpm2-cmd.c       | 105 +++++++++++++++++++++-----------------
>  drivers/char/tpm/tpm_ibmvtpm.c    |  51 +++++++++---------
>  drivers/char/tpm/tpm_vtpm_proxy.c |  48 ++++++++++++-----
>  5 files changed, 150 insertions(+), 95 deletions(-)
> 
> -- 
> 2.7.4
> 

Re: [PATCH v2 0/4] tpm: kdoc cleanup

[Jarkko Sakkinen]

On Wed, Nov 23, 2016 at 12:04:10PM +0200, Tomas Winkler wrote:
> Cleanup tpm in-code documentation.
> 
> Tomas Winkler (4):
>   tpm: add kdoc for tpm_transmit and tpm_transmit_cmd
>   tpm/tpm2-chip: fix kdoc errors
>   tmp: use pdev for parent device in tpm_chip_alloc
>   tpm/vtpm: fix kdoc warnings

Sorry I my previous comments were meant to this series. I looked them up
from patchwork and replied to wrong series

> 
>  drivers/char/tpm/tpm-chip.c       |   8 +--
>  drivers/char/tpm/tpm-interface.c  |  33 ++++++++++--
>  drivers/char/tpm/tpm2-cmd.c       | 105 +++++++++++++++++++++-----------------
>  drivers/char/tpm/tpm_ibmvtpm.c    |  51 +++++++++---------
>  drivers/char/tpm/tpm_vtpm_proxy.c |  48 ++++++++++++-----
>  5 files changed, 150 insertions(+), 95 deletions(-)
> 
> -- 
> 2.7.4
> 

/Jarkko

------------------------------------------------------------------------------

Re: [PATCH v2 0/4] tpm: kdoc cleanup

[Jarkko Sakkinen]

On Wed, Nov 23, 2016 at 12:04:10PM +0200, Tomas Winkler wrote:
> Cleanup tpm in-code documentation.
> 
> Tomas Winkler (4):
>   tpm: add kdoc for tpm_transmit and tpm_transmit_cmd
>   tpm/tpm2-chip: fix kdoc errors
>   tmp: use pdev for parent device in tpm_chip_alloc
>   tpm/vtpm: fix kdoc warnings

Sorry I my previous comments were meant to this series. I looked them up
from patchwork and replied to wrong series

> 
>  drivers/char/tpm/tpm-chip.c       |   8 +--
>  drivers/char/tpm/tpm-interface.c  |  33 ++++++++++--
>  drivers/char/tpm/tpm2-cmd.c       | 105 +++++++++++++++++++++-----------------
>  drivers/char/tpm/tpm_ibmvtpm.c    |  51 +++++++++---------
>  drivers/char/tpm/tpm_vtpm_proxy.c |  48 ++++++++++++-----
>  5 files changed, 150 insertions(+), 95 deletions(-)
> 
> -- 
> 2.7.4
> 

/Jarkko

Re: [PATCH v2 0/4] tpm: kdoc cleanup

[Jarkko Sakkinen]

On Wed, Nov 23, 2016 at 12:04:10PM +0200, Tomas Winkler wrote:
> Cleanup tpm in-code documentation.

These are all applied to my master branch but please do answer to my
question about TPM_DIGEST_SIZE so I can adjust that.

/Jarkko

------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most 
engaging tech sites, SlashDot.org! http://sdm.link/slashdot

Re: [PATCH v2 0/4] tpm: kdoc cleanup

[Jarkko Sakkinen]

On Wed, Nov 23, 2016 at 12:04:10PM +0200, Tomas Winkler wrote:
> Cleanup tpm in-code documentation.

These are all applied to my master branch but please do answer to my
question about TPM_DIGEST_SIZE so I can adjust that.

/Jarkko