Nouveau - Dec 2024 - [PATCH v3 01/15] nvkm: add a kernel doc to introduce the GSP RPC

In order to explain the name clean-ups in GSP RPC routines, a kernel
doc to explain the memory layout and terms is required.

Add a kernel doc to introduce the GSP RPC.

Signed-off-by: Zhi Wang <zhiw at nvidia.com>
---
 .../gpu/drm/nouveau/nvkm/subdev/gsp/r535.c    | 46 +++++++++++++++++++
 1 file changed, 46 insertions(+)

diff --git a/drivers/gpu/drm/nouveau/nvkm/subdev/gsp/r535.c
b/drivers/gpu/drm/nouveau/nvkm/subdev/gsp/r535.c
index a4b8381c4e3e..1a07c0191356 100644
--- a/drivers/gpu/drm/nouveau/nvkm/subdev/gsp/r535.c
+++ b/drivers/gpu/drm/nouveau/nvkm/subdev/gsp/r535.c
@@ -60,6 +60,52 @@
 #define GSP_MSG_MIN_SIZE GSP_PAGE_SIZE
 #define GSP_MSG_MAX_SIZE GSP_PAGE_MIN_SIZE * 16
 
+/**
+ * DOC: GSP message queue element
+ *
+ *
https://github.com/NVIDIA/open-gpu-kernel-modules/blob/main/src/nvidia/inc/kernel/gpu/gsp/message_queue_priv.h
+ *
+ * The GSP command queue and status queue are message queues for the
+ * communication between software and GSP. The software submits the GSP
+ * RPC via the GSP command queue, GSP writes the status of the submitted
+ * RPC in the status queue.
+ *
+ * A GSP message queue element consists of three parts:
+ *
+ * - message element header (struct r535_gsp_msg), which mostly maintains
+ * the metadata for queuing the element.
+ *
+ * - RPC message header (struct nvfw_gsp_rpc), which maintains the info
+ * of the RPC. E.g., the RPC function number.
+ *
+ * - The payload, where the RPC message stays. E.g. the params of a
+ * specific RPC function. Some RPC functions also have their headers
+ * in the payload. E.g. rm_alloc, rm_control.
+ *
+ * The memory layout of a GSP message element can be illustrated below:
+ *
+ * +------------------------+
+ * | Message Element Header |
+ * |    (r535_gsp_msg)      |
+ * |                        |
+ * | (r535_gsp_msg.data)    |
+ * |          |             |
+ * |----------V-------------|
+ * |    GSP RPC Header      |
+ * |    (nvfw_gsp_rpc)      |
+ * |                        |
+ * | (nvfw_gsp_rpc.data)    |
+ * |          |             |
+ * |----------V-------------|
+ * |                        |
+ * |       Payload          |
+ * |                        |
+ * |   header(optional)     |
+ * |        params          |
+ * +------------------------+
+ *
+ */
+
 struct r535_gsp_msg {
 	u8 auth_tag_buffer[16];
 	u8 aad_buffer[16];
-- 
2.34.1

Hi Zhi,

On Thu, Oct 31, 2024 at 01:52:36AM -0700, Zhi Wang
wrote:
> In order to explain the name clean-ups in GSP RPC routines, a kernel
> doc to explain the memory layout and terms is required.
> 
> Add a kernel doc to introduce the GSP RPC.
Thanks for adding this -- very much appreciated!
> 
> Signed-off-by: Zhi Wang <zhiw at nvidia.com>
> ---
>  .../gpu/drm/nouveau/nvkm/subdev/gsp/r535.c    | 46 +++++++++++++++++++
>  1 file changed, 46 insertions(+)
> 
> diff --git a/drivers/gpu/drm/nouveau/nvkm/subdev/gsp/r535.c
b/drivers/gpu/drm/nouveau/nvkm/subdev/gsp/r535.c
> index a4b8381c4e3e..1a07c0191356 100644
> --- a/drivers/gpu/drm/nouveau/nvkm/subdev/gsp/r535.c
> +++ b/drivers/gpu/drm/nouveau/nvkm/subdev/gsp/r535.c
I assume the idea is to add this documentation r535 specifically and for it for
new firmware versions?
> @@ -60,6 +60,52 @@
>  #define GSP_MSG_MIN_SIZE GSP_PAGE_SIZE
>  #define GSP_MSG_MAX_SIZE GSP_PAGE_MIN_SIZE * 16
>  
> +/**
> + * DOC: GSP message queue element
We should probably include those DOCs into a Documentation/gpu/nouveau.rst
(which
would need to be created, now that we add documentation).
> + *
> + *
https://github.com/NVIDIA/open-gpu-kernel-modules/blob/main/src/nvidia/inc/kernel/gpu/gsp/message_queue_priv.h
If so, this should not reference the main branch, but rather the corresponding
r535 release?
> + *
> + * The GSP command queue and status queue are message queues for the
> + * communication between software and GSP. The software submits the GSP
> + * RPC via the GSP command queue, GSP writes the status of the submitted
> + * RPC in the status queue.
> + *
> + * A GSP message queue element consists of three parts:
> + *
> + * - message element header (struct r535_gsp_msg), which mostly maintains
> + * the metadata for queuing the element.
> + *
> + * - RPC message header (struct nvfw_gsp_rpc), which maintains the info
> + * of the RPC. E.g., the RPC function number.
> + *
> + * - The payload, where the RPC message stays. E.g. the params of a
> + * specific RPC function. Some RPC functions also have their headers
> + * in the payload. E.g. rm_alloc, rm_control.
> + *
> + * The memory layout of a GSP message element can be illustrated below:
> + *
> + * +------------------------+
> + * | Message Element Header |
> + * |    (r535_gsp_msg)      |
> + * |                        |
> + * | (r535_gsp_msg.data)    |
> + * |          |             |
> + * |----------V-------------|
> + * |    GSP RPC Header      |
> + * |    (nvfw_gsp_rpc)      |
> + * |                        |
> + * | (nvfw_gsp_rpc.data)    |
> + * |          |             |
> + * |----------V-------------|
> + * |                        |
> + * |       Payload          |
> + * |                        |
> + * |   header(optional)     |
> + * |        params          |
> + * +------------------------+
> + *
> + */
> +
>  struct r535_gsp_msg {
>  	u8 auth_tag_buffer[16];
>  	u8 aad_buffer[16];
> -- 
> 2.34.1
>