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

[PATCH 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>
---
 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..56c238a6e005 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 2/4 v2] 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: rework and rebase of tpm_transmit_cmd kdoc fix

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

diff --git a/drivers/char/tpm/tpm2-cmd.c b/drivers/char/tpm/tpm2-cmd.c
index da5b782a9731..6f9eea7eda7a 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,14 @@ 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;
+ *    -EIO on error
  */
 int tpm2_get_random(struct tpm_chip *chip, u8 *out, size_t max)
 {
@@ -404,15 +402,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 +434,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 +540,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,9 +606,10 @@ 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
+ *
+ * @chip: TPM chip to use
+ * @handle: the key data in clear and encrypted form
+ * @flags: tpm transmit flags
  *
  * Return: same as with tpm_transmit_cmd
  */
@@ -632,11 +639,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 +693,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 +728,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 +761,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 +791,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 +816,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 +852,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 +883,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 +936,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 2/4 v2] tpm/tpm2-chip: fix kdoc errors

[Jarkko Sakkinen]

On Wed, Nov 16, 2016 at 07:03:39PM +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>

> ---
> V2: rework and rebase of tpm_transmit_cmd kdoc fix
> 
>  drivers/char/tpm/tpm2-cmd.c | 104 ++++++++++++++++++++++++--------------------
>  1 file changed, 57 insertions(+), 47 deletions(-)
> 
> diff --git a/drivers/char/tpm/tpm2-cmd.c b/drivers/char/tpm/tpm2-cmd.c
> index da5b782a9731..6f9eea7eda7a 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,14 @@ 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;
> + *    -EIO on error
>   */
>  int tpm2_get_random(struct tpm_chip *chip, u8 *out, size_t max)
>  {
> @@ -404,15 +402,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 +434,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 +540,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,9 +606,10 @@ 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
> + *
> + * @chip: TPM chip to use
> + * @handle: the key data in clear and encrypted form
> + * @flags: tpm transmit flags
>   *
>   * Return: same as with tpm_transmit_cmd
>   */
> @@ -632,11 +639,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 +693,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 +728,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 +761,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 +791,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 +816,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 +852,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 +883,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 +936,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 3/4 v2] 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>
---
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 3f27753d96aa..9e36a7f21a6e 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 3/4 v2] tmp: use pdev for parent device in tpm_chip_alloc

[Jarkko Sakkinen]

On Wed, Nov 16, 2016 at 07:03:40PM +0200, Tomas Winkler wrote:
> 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>

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

You should CC patches by default also to linux-security-module. I don't
think for this particular series it is a major concern though.

/Jarkko


> ---
> 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 3f27753d96aa..9e36a7f21a6e 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 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>
---
 drivers/char/tpm/tpm_ibmvtpm.c    | 51 +++++++++++++++++++--------------------
 drivers/char/tpm/tpm_vtpm_proxy.c | 48 +++++++++++++++++++++++++++---------
 2 files changed, 61 insertions(+), 38 deletions(-)

diff --git a/drivers/char/tpm/tpm_ibmvtpm.c b/drivers/char/tpm/tpm_ibmvtpm.c
index 946025a7413b..bd5da4beb012 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,11 +98,12 @@ 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:
+ * Return:
  *	Number of bytes sent
  */
 static int tpm_ibmvtpm_send(struct tpm_chip *chip, u8 *buf, size_t count)
@@ -172,7 +175,7 @@ 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:
+ * Return:
  *	0 - Success
  *	Non-zero - Failure
  */
@@ -199,7 +202,7 @@ static int ibmvtpm_crq_get_rtce_size(struct ibmvtpm_dev *ibmvtpm)
  *			   - Note that this is vtpm version and not tpm version
  * @ibmvtpm:	vtpm device struct
  *
- * Return value:
+ * Return:
  *	0 - Success
  *	Non-zero - Failure
  */
@@ -225,7 +228,7 @@ 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:
+ * Return:
  *	0 - Success
  *	Non-zero - Failure
  */
@@ -245,7 +248,7 @@ 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:
+ * Return:
  *	0 - Success
  *	Non-zero - Failure
  */
@@ -265,7 +268,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:
+ * Return:
  *	0
  */
 static int tpm_ibmvtpm_remove(struct vio_dev *vdev)
@@ -303,7 +306,7 @@ 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:
+ * Return:
  *	Number of bytes the driver needs to DMA map
  */
 static unsigned long tpm_ibmvtpm_get_desired_dma(struct vio_dev *vdev)
@@ -325,7 +328,7 @@ static unsigned long tpm_ibmvtpm_get_desired_dma(struct vio_dev *vdev)
  * tpm_ibmvtpm_suspend - Suspend
  * @dev:	device struct
  *
- * Return value:
+ * Return:
  *	0
  */
 static int tpm_ibmvtpm_suspend(struct device *dev)
@@ -352,7 +355,7 @@ static int tpm_ibmvtpm_suspend(struct device *dev)
  * ibmvtpm_reset_crq - Reset CRQ
  * @ibmvtpm:	ibm vtpm struct
  *
- * Return value:
+ * Return:
  *	0 - Success
  *	Non-zero - Failure
  */
@@ -378,7 +381,7 @@ static int ibmvtpm_reset_crq(struct ibmvtpm_dev *ibmvtpm)
  * tpm_ibmvtpm_resume - Resume from suspend
  * @dev:	device struct
  *
- * Return value:
+ * Return:
  *	0
  */
 static int tpm_ibmvtpm_resume(struct device *dev)
@@ -434,10 +437,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 +458,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)
@@ -557,7 +559,7 @@ static irqreturn_t ibmvtpm_interrupt(int irq, void *vtpm_instance)
  * @vio_dev:	vio device struct
  * @id:		vio device id struct
  *
- * Return value:
+ * Return:
  *	0 - Success
  *	Non-zero - Failure
  */
@@ -673,7 +675,7 @@ static struct vio_driver ibmvtpm_driver = {
 /**
  * ibmvtpm_module_init - Initialize ibm vtpm module
  *
- * Return value:
+ * Return:
  *	0 -Success
  *	Non-zero - Failure
  */
@@ -684,9 +686,6 @@ static int __init ibmvtpm_module_init(void)
 
 /**
  * ibmvtpm_module_exit - Teardown ibm vtpm module
- *
- * Return value:
- *	Nothing
  */
 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 3d6f6ca81def..f973d8840e07 100644
--- a/drivers/char/tpm/tpm_vtpm_proxy.c
+++ b/drivers/char/tpm/tpm_vtpm_proxy.c
@@ -64,7 +64,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,
@@ -114,7 +119,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,
@@ -154,10 +164,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)
 {
@@ -184,6 +196,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)
@@ -195,8 +209,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)
 {
@@ -211,9 +226,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)
@@ -244,7 +261,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)
@@ -281,7 +301,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)
@@ -444,7 +468,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(
@@ -572,7 +596,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 1/4] tpm: add kdoc for tpm_transmit and tpm_transmit_cmd

[Jarkko Sakkinen]

On Wed, Nov 16, 2016 at 07:03:38PM +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 know how to make "make htmldocs" to generate documentation for
the source tree? I do not except the ones that I imported when I created
an RST version of the Stefans documentation.

I'm mainly concerned having one line per error code. My guess it that
Sphinx will remove the newline characters.

The way I sorted that out in Stefans documentation was '|' prefix on the
beginning of line, which does newline enforcement.

So you would have something along the lines:

* | 0 when the operation is successful
* | negative number for system errors (errno)
* | A positive number for a TPM error.

It's uglier in unrendered form but still kind of sustainable and in the
rendered output things won't fall apart...

/Jarkko

> ---
>  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..56c238a6e005 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 1/4] tpm: add kdoc for tpm_transmit and tpm_transmit_cmd

[Winkler, Tomas]

> 
> On Wed, Nov 16, 2016 at 07:03:38PM +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 know how to make "make htmldocs" to generate documentation for the
> source tree? I do not except the ones that I imported when I created an RST
> version of the Stefans documentation.

I'm using a quick script like that
RES=tpm-kdoc.html
rm -r $RES kdoc.err
files=$(git ls-files drivers/char/tpm/*.[ch] includ/linux/tpm.h includ/linux/tpm_command.h)

echo '<html>' > $RES
for f in ${files}; do
        ./scripts/kernel-doc -html $f >> $RES 2>> kdoc.err
done
echo '</html>' >> $RES
cat kdoc.err | grep -v 'warning: no structured comments found'

> 
> I'm mainly concerned having one line per error code. My guess it that Sphinx
> will remove the newline characters.

Why do you find it tragic that the new line is removed, we just need to make sure it's readable in both cases.

> The way I sorted that out in Stefans documentation was '|' prefix on the
> beginning of line, which does newline enforcement.
> 
> So you would have something along the lines:
> 
> * | 0 when the operation is successful
> * | negative number for system errors (errno)
> * | A positive number for a TPM error.
> 
> It's uglier in unrendered form but still kind of sustainable and in the rendered
> output things won't fall apart...

I'm not sure it matters much regarding the readability of the document but the old html format will have then those strange 'I' rendered. 

Let me know which why you won't to go frankly I don't have strong opinion either way,  I will respin the patch anyhow as I've missed some '.' 

Thanks
Tomas


 
> /Jarkko
> 
> > ---
> >  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..56c238a6e005 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 1/4] tpm: add kdoc for tpm_transmit and tpm_transmit_cmd

[Jarkko Sakkinen]

On Tue, Nov 22, 2016 at 09:44:20AM +0000, Winkler, Tomas wrote:
> > 
> > On Wed, Nov 16, 2016 at 07:03:38PM +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 know how to make "make htmldocs" to generate documentation for the
> > source tree? I do not except the ones that I imported when I created an RST
> > version of the Stefans documentation.
> 
> I'm using a quick script like that
> RES=tpm-kdoc.html
> rm -r $RES kdoc.err
> files=$(git ls-files drivers/char/tpm/*.[ch] includ/linux/tpm.h includ/linux/tpm_command.h)
> 
> echo '<html>' > $RES
> for f in ${files}; do
>         ./scripts/kernel-doc -html $f >> $RES 2>> kdoc.err
> done
> echo '</html>' >> $RES
> cat kdoc.err | grep -v 'warning: no structured comments found'

Thanks. I'll try this as soon as the release chaos is over.

/Jarkko

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

[Jarkko Sakkinen]

On Wed, Nov 16, 2016 at 07:03:38PM +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>
> ---
>  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..56c238a6e005 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

I think we should scrap this stupid constant away but its not this
patches fault :-) Would be better to just use SHA1_DIGEST_SIZE.

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

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

I'm applying this and other patches in this series post pull requeest as
it is not release critical.

/Jarkko