[PATCH 2/7] nouveau/gsp: Add documentation for RPC functions return values

[Hongling Zeng]

Add kernel-doc comments to document the return value contracts for
GSP RPC functions. This clarifies which functions can return NULL,
error pointers, or both, making the codebase easier to maintain and
preventing future errors.

As per Danilo Krummrich's feedback: "the changes submitted by Hongling
can add the documentation for the places that are touched."

The following functions are documented:
- r535_gsp_cmdq_get(): Returns ERR_PTR on error, never NULL
- r535_gsp_rpc_get(): Returns ERR_PTR on error, never NULL
- r535_gsp_msgq_peek(): Returns ERR_PTR on error, never NULL
- r535_gsp_msgq_recv_one_elem(): Returns ERR_PTR on error, never NULL
- r535_gsp_msgq_recv(): Returns ERR_PTR on error, never NULL (fixed in
  previous patch)
- r535_gsp_msg_recv(): Returns ERR_PTR on error, never NULL (fixed in
  previous patch)

Signed-off-by: Hongling Zeng <zenghongling@xxxxxxxxxx>
---
 .../drm/nouveau/nvkm/subdev/gsp/rm/r535/rpc.c | 39 +++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/drivers/gpu/drm/nouveau/nvkm/subdev/gsp/rm/r535/rpc.c b/drivers/gpu/drm/nouveau/nvkm/subdev/gsp/rm/r535/rpc.c
index ce83a867dd36..9a9ac5e3017e 100644
--- a/drivers/gpu/drm/nouveau/nvkm/subdev/gsp/rm/r535/rpc.c
+++ b/drivers/gpu/drm/nouveau/nvkm/subdev/gsp/rm/r535/rpc.c
@@ -204,6 +204,14 @@ r535_gsp_msgq_get_entry(struct nvkm_gsp *gsp)
  *   The user is responsible for freeing the memory allocated for the GSP
  *   message pages after they have been processed.
  */
+/**
+ * r535_gsp_msgq_peek() - Peek at a GSP message queue element
+ * @gsp: GSP device
+ * @gsp_rpc_len: expected RPC length
+ * @retries: retry counter
+ *
+ * Return: ERR_PTR on error, valid pointer on success, never NULL
+ */
 static void *
 r535_gsp_msgq_peek(struct nvkm_gsp *gsp, u32 gsp_rpc_len, int *retries)
 {
@@ -229,6 +237,13 @@ struct r535_gsp_msg_info {
 static void
 r535_gsp_msg_dump(struct nvkm_gsp *gsp, struct nvfw_gsp_rpc *msg, int lvl);
 
+/**
+ * r535_gsp_msgq_recv_one_elem() - Receive one GSP message queue element
+ * @gsp: GSP device
+ * @info: message queue receive information
+ *
+ * Return: ERR_PTR on error, valid pointer on success, never NULL
+ */
 static void *
 r535_gsp_msgq_recv_one_elem(struct nvkm_gsp *gsp,
 			    struct r535_gsp_msg_info *info)
@@ -283,6 +298,14 @@ r535_gsp_msgq_recv_one_elem(struct nvkm_gsp *gsp,
 	return buf;
 }
 
+/**
+ * r535_gsp_msgq_recv() - Receive a complete GSP message from the message queue
+ * @gsp: GSP device
+ * @gsp_rpc_len: expected RPC length
+ * @retries: retry counter
+ *
+ * Return: ERR_PTR on error, valid pointer on success, never NULL
+ */
 static void *
 r535_gsp_msgq_recv(struct nvkm_gsp *gsp, u32 gsp_rpc_len, int *retries)
 {
@@ -450,6 +473,14 @@ r535_gsp_msg_dump(struct nvkm_gsp *gsp, struct nvfw_gsp_rpc *msg, int lvl)
 	}
 }
 
+/**
+ * r535_gsp_msg_recv() - Receive and validate a GSP RPC message
+ * @gsp: GSP device
+ * @fn: expected function number (0 to skip validation)
+ * @gsp_rpc_len: expected RPC length
+ *
+ * Return: ERR_PTR on error or validation failure, valid pointer on success, never NULL
+ */
 struct nvfw_gsp_rpc *
 r535_gsp_msg_recv(struct nvkm_gsp *gsp, int fn, u32 gsp_rpc_len)
 {
@@ -609,6 +640,14 @@ r535_gsp_rpc_done(struct nvkm_gsp *gsp, void *repv)
 	r535_gsp_msg_done(gsp, rpc);
 }
 
+/**
+ * r535_gsp_rpc_get() - Allocate and initialize a GSP RPC message
+ * @gsp: GSP device
+ * @fn: RPC function number
+ * @payload_size: size of the RPC payload
+ *
+ * Return: ERR_PTR on error, valid pointer on success, never NULL
+ */
 static void *
 r535_gsp_rpc_get(struct nvkm_gsp *gsp, u32 fn, u32 payload_size)
 {
-- 
2.25.1