Re: [PATCH v3 01/15] nvkm: add a kernel doc to introduce the GSP RPC

[Zhi Wang <zhiw@nvidia.com>]

On 11/12/2024 12.14, Danilo Krummrich wrote:
> 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@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?
> 

I think it is to depict the general idea for people to understand. For 
newer firmware version (just checked the code in openrm main branch), 
the idea is still valid. Suppose the minor changes on some data 
structures can be self-documented by definitions.

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

Sounds a good idea.

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