diff mbox series

[v4,03/13] tpm: add kernel doc to buffer handling functions

Message ID 20230403214003.32093-4-James.Bottomley@HansenPartnership.com (mailing list archive)
State New, archived
Headers show
Series add integrity and security to TPM2 transactions | expand

Commit Message

James Bottomley April 3, 2023, 9:39 p.m. UTC 
Signed-off-by: James Bottomley <James.Bottomley@HansenPartnership.com>
---
 drivers/char/tpm/tpm-buf.c | 65 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 65 insertions(+)

Comments

Jarkko Sakkinen April 23, 2023, 3:40 a.m. UTC | #1 
On Tue Apr 4, 2023 at 12:39 AM EEST, James Bottomley wrote:
> Signed-off-by: James Bottomley <James.Bottomley@HansenPartnership.com>
> ---
>  drivers/char/tpm/tpm-buf.c | 65 ++++++++++++++++++++++++++++++++++++++
>  1 file changed, 65 insertions(+)
>
> diff --git a/drivers/char/tpm/tpm-buf.c b/drivers/char/tpm/tpm-buf.c
> index baa4866d53a9..3351db515e6b 100644
> --- a/drivers/char/tpm/tpm-buf.c
> +++ b/drivers/char/tpm/tpm-buf.c
> @@ -6,6 +6,16 @@
>  #include <linux/module.h>
>  #include <linux/tpm.h>
>  
> +/**
> + * tpm_buf_init - initialize a TPM command buffer
> + * @buf: pointer to a tpm_buf structure (usually on stack)
> + * @tag: command tag
> + * @ordinal: command ordinal
> + *
> + * Allocates a 4k buffer to hold the command structure.
> + *
> + * @return: 0 on success or -ENOMEM
> + */
>  int tpm_buf_init(struct tpm_buf *buf, u16 tag, u32 ordinal)
>  {
>  	buf->data = (u8 *)__get_free_page(GFP_KERNEL);
> @@ -18,6 +28,16 @@ int tpm_buf_init(struct tpm_buf *buf, u16 tag, u32 ordinal)
>  }
>  EXPORT_SYMBOL_GPL(tpm_buf_init);
>  
> +/**
> + * tpm_buf_reset - reset an initialized TPM command buffer
> + * @buf: pointer to a tpm_buf structure (usually on stack)
> + * @tag: command tag
> + * @ordinal: command ordinal
> + *
> + * Repurposes an already allocated @buf for a new command.
> + * Identical to calling tpm_buf_destroy/tpm_buf_init except it keeps
> + * the 4k allocated page and cannot fail.
> + */
>  void tpm_buf_reset(struct tpm_buf *buf, u16 tag, u32 ordinal)
>  {
>  	struct tpm_header *head = (struct tpm_header *) buf->data;
> @@ -28,12 +48,24 @@ void tpm_buf_reset(struct tpm_buf *buf, u16 tag, u32 ordinal)
>  }
>  EXPORT_SYMBOL_GPL(tpm_buf_reset);
>  
> +/**
> + * tpm_buf_destroy - destroy an initialized TPM command buffer
> + * @buf: pointer to a tpm_buf structure (usually on stack)
> + *
> + * Frees the memory allocated to @buf.
> + */
>  void tpm_buf_destroy(struct tpm_buf *buf)
>  {
>  	free_page((unsigned long)buf->data);
>  }
>  EXPORT_SYMBOL_GPL(tpm_buf_destroy);
>  
> +/**
> + * tpm_buf_length - get the current length of a TPM command
> + * @buf: pointer to a tpm_buf structure (usually on stack)
> + *
> + * @return: the current length of the @buf.
> + */
>  u32 tpm_buf_length(struct tpm_buf *buf)
>  {
>  	struct tpm_header *head = (struct tpm_header *)buf->data;
> @@ -42,6 +74,15 @@ u32 tpm_buf_length(struct tpm_buf *buf)
>  }
>  EXPORT_SYMBOL_GPL(tpm_buf_length);
>  
> +/**
> + * tpm_buf_append - append data to an initialized TPM command buffer
> + * @buf: pointer to a tpm_buf structure (usually on stack)
> + * @new_data: pointer to the added data
> + * @new_len: length of the added data
> + *
> + * Appends @new_data to the end of the current @buf and updates the
> + * length.
> + */
>  void tpm_buf_append(struct tpm_buf *buf,
>  		    const unsigned char *new_data,
>  		    unsigned int new_len)
> @@ -64,12 +105,28 @@ void tpm_buf_append(struct tpm_buf *buf,
>  }
>  EXPORT_SYMBOL_GPL(tpm_buf_append);
>  
> +/**
> + * tpm_buf_append_u8 - append u8 data to an initialized TPM command buffer
> + * @buf: pointer to a tpm_buf structure (usually on stack)
> + * @value: the value of the data to append
> + *
> + * Appends @value as a byte to the end of the current @buf and updates
> + * the length.
> + */
>  void tpm_buf_append_u8(struct tpm_buf *buf, const u8 value)
>  {
>  	tpm_buf_append(buf, &value, 1);
>  }
>  EXPORT_SYMBOL_GPL(tpm_buf_append_u8);
>  
> +/**
> + * tpm_buf_append_u16 - append u16 data to an initialized TPM command buffer
> + * @buf: pointer to a tpm_buf structure (usually on stack)
> + * @value: the value of the data to append
> + *
> + * Appends @value as a big endian short to the end of the current @buf
> + * and updates the length.
> + */
>  void tpm_buf_append_u16(struct tpm_buf *buf, const u16 value)
>  {
>  	__be16 value2 = cpu_to_be16(value);
> @@ -78,6 +135,14 @@ void tpm_buf_append_u16(struct tpm_buf *buf, const u16 value)
>  }
>  EXPORT_SYMBOL_GPL(tpm_buf_append_u16);
>  
> +/**
> + * tpm_buf_append_u32 - append u32 data to an initialized TPM command buffer
> + * @buf: pointer to a tpm_buf structure (usually on stack)
> + * @value: the value of the data to append
> + *
> + * Appends @value as a big endian word to the end of the current @buf
> + * and updates the length.
> + */
>  void tpm_buf_append_u32(struct tpm_buf *buf, const u32 value)
>  {
>  	__be32 value2 = cpu_to_be32(value);
> -- 
> 2.35.3

Reviewed-by: Jarkko Sakkinen <jarkko@kernel.org>

BR, Jarkko
diff mbox series

Patch

diff --git a/drivers/char/tpm/tpm-buf.c b/drivers/char/tpm/tpm-buf.c
index baa4866d53a9..3351db515e6b 100644
--- a/drivers/char/tpm/tpm-buf.c
+++ b/drivers/char/tpm/tpm-buf.c
@@ -6,6 +6,16 @@ 
 #include <linux/module.h>
 #include <linux/tpm.h>
 
+/**
+ * tpm_buf_init - initialize a TPM command buffer
+ * @buf: pointer to a tpm_buf structure (usually on stack)
+ * @tag: command tag
+ * @ordinal: command ordinal
+ *
+ * Allocates a 4k buffer to hold the command structure.
+ *
+ * @return: 0 on success or -ENOMEM
+ */
 int tpm_buf_init(struct tpm_buf *buf, u16 tag, u32 ordinal)
 {
 	buf->data = (u8 *)__get_free_page(GFP_KERNEL);
@@ -18,6 +28,16 @@  int tpm_buf_init(struct tpm_buf *buf, u16 tag, u32 ordinal)
 }
 EXPORT_SYMBOL_GPL(tpm_buf_init);
 
+/**
+ * tpm_buf_reset - reset an initialized TPM command buffer
+ * @buf: pointer to a tpm_buf structure (usually on stack)
+ * @tag: command tag
+ * @ordinal: command ordinal
+ *
+ * Repurposes an already allocated @buf for a new command.
+ * Identical to calling tpm_buf_destroy/tpm_buf_init except it keeps
+ * the 4k allocated page and cannot fail.
+ */
 void tpm_buf_reset(struct tpm_buf *buf, u16 tag, u32 ordinal)
 {
 	struct tpm_header *head = (struct tpm_header *) buf->data;
@@ -28,12 +48,24 @@  void tpm_buf_reset(struct tpm_buf *buf, u16 tag, u32 ordinal)
 }
 EXPORT_SYMBOL_GPL(tpm_buf_reset);
 
+/**
+ * tpm_buf_destroy - destroy an initialized TPM command buffer
+ * @buf: pointer to a tpm_buf structure (usually on stack)
+ *
+ * Frees the memory allocated to @buf.
+ */
 void tpm_buf_destroy(struct tpm_buf *buf)
 {
 	free_page((unsigned long)buf->data);
 }
 EXPORT_SYMBOL_GPL(tpm_buf_destroy);
 
+/**
+ * tpm_buf_length - get the current length of a TPM command
+ * @buf: pointer to a tpm_buf structure (usually on stack)
+ *
+ * @return: the current length of the @buf.
+ */
 u32 tpm_buf_length(struct tpm_buf *buf)
 {
 	struct tpm_header *head = (struct tpm_header *)buf->data;
@@ -42,6 +74,15 @@  u32 tpm_buf_length(struct tpm_buf *buf)
 }
 EXPORT_SYMBOL_GPL(tpm_buf_length);
 
+/**
+ * tpm_buf_append - append data to an initialized TPM command buffer
+ * @buf: pointer to a tpm_buf structure (usually on stack)
+ * @new_data: pointer to the added data
+ * @new_len: length of the added data
+ *
+ * Appends @new_data to the end of the current @buf and updates the
+ * length.
+ */
 void tpm_buf_append(struct tpm_buf *buf,
 		    const unsigned char *new_data,
 		    unsigned int new_len)
@@ -64,12 +105,28 @@  void tpm_buf_append(struct tpm_buf *buf,
 }
 EXPORT_SYMBOL_GPL(tpm_buf_append);
 
+/**
+ * tpm_buf_append_u8 - append u8 data to an initialized TPM command buffer
+ * @buf: pointer to a tpm_buf structure (usually on stack)
+ * @value: the value of the data to append
+ *
+ * Appends @value as a byte to the end of the current @buf and updates
+ * the length.
+ */
 void tpm_buf_append_u8(struct tpm_buf *buf, const u8 value)
 {
 	tpm_buf_append(buf, &value, 1);
 }
 EXPORT_SYMBOL_GPL(tpm_buf_append_u8);
 
+/**
+ * tpm_buf_append_u16 - append u16 data to an initialized TPM command buffer
+ * @buf: pointer to a tpm_buf structure (usually on stack)
+ * @value: the value of the data to append
+ *
+ * Appends @value as a big endian short to the end of the current @buf
+ * and updates the length.
+ */
 void tpm_buf_append_u16(struct tpm_buf *buf, const u16 value)
 {
 	__be16 value2 = cpu_to_be16(value);
@@ -78,6 +135,14 @@  void tpm_buf_append_u16(struct tpm_buf *buf, const u16 value)
 }
 EXPORT_SYMBOL_GPL(tpm_buf_append_u16);
 
+/**
+ * tpm_buf_append_u32 - append u32 data to an initialized TPM command buffer
+ * @buf: pointer to a tpm_buf structure (usually on stack)
+ * @value: the value of the data to append
+ *
+ * Appends @value as a big endian word to the end of the current @buf
+ * and updates the length.
+ */
 void tpm_buf_append_u32(struct tpm_buf *buf, const u32 value)
 {
 	__be32 value2 = cpu_to_be32(value);