Add kernel-doc comments to document the return value semantics of RPC functions in r535/rpc.c. This clarifies which functions can return NULL, error pointers, or both, helping maintainers validate future changes.
Return value analysis: - r535_gsp_msgq_peek(): Never returns NULL - r535_gsp_msgq_recv_one_elem(): Never returns NULL - r535_gsp_msgq_recv(): CAN return NULL (when RPC length invalid) - r535_gsp_msg_recv(): CAN return NULL (queue drained/no matching message) - r535_gsp_rpc_get(): Never returns NULL - r535_gsp_rpc_handle_reply(): CAN return NULL (NOWAIT/NOSEQ policies) - r535_gsp_rpc_send(): CAN return NULL (via handle_reply) - r535_gsp_rpc_push(): CAN return NULL (via handle_reply) Signed-off-by: Hongling Zeng <[email protected]> --- .../drm/nouveau/nvkm/subdev/gsp/rm/r535/rpc.c | 75 +++++++++++++++++++ 1 file changed, 75 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 3ca3de8f4340..7dd43fa38c41 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,15 @@ 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 next message in GSP command queue + * @gsp: GSP device + * @gsp_rpc_len: Expected RPC length + * @retries: Retry counter + * + * Return: Pointer to RPC message on success, or ERR_PTR() on error. + * Never returns NULL. + */ static void * r535_gsp_msgq_peek(struct nvkm_gsp *gsp, u32 gsp_rpc_len, int *retries) { @@ -229,6 +238,14 @@ 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 message element from GSP queue + * @gsp: GSP device + * @info: Message queue information + * + * Return: Pointer to received buffer on success, or ERR_PTR() on error. + * Never returns NULL. + */ static void * r535_gsp_msgq_recv_one_elem(struct nvkm_gsp *gsp, struct r535_gsp_msg_info *info) @@ -283,6 +300,15 @@ r535_gsp_msgq_recv_one_elem(struct nvkm_gsp *gsp, return buf; } +/** + * r535_gsp_msgq_recv - Receive RPC message(s) from GSP queue + * @gsp: GSP device + * @gsp_rpc_len: Expected RPC length + * @retries: Retry counter + * + * Return: Pointer to received buffer on success, ERR_PTR() on error, + * or NULL if RPC length is invalid. + */ static void * r535_gsp_msgq_recv(struct nvkm_gsp *gsp, u32 gsp_rpc_len, int *retries) { @@ -450,6 +476,15 @@ r535_gsp_msg_dump(struct nvkm_gsp *gsp, struct nvfw_gsp_rpc *msg, int lvl) } } +/** + * r535_gsp_msg_recv - Receive RPC message from GSP message queue + * @gsp: GSP device + * @fn: Expected RPC function number (0 to accept any) + * @gsp_rpc_len: Expected RPC length + * + * Return: Pointer to RPC message on success, ERR_PTR() on error, + * or NULL if queue is drained or no matching message found. + */ struct nvfw_gsp_rpc * r535_gsp_msg_recv(struct nvkm_gsp *gsp, int fn, u32 gsp_rpc_len) { @@ -547,6 +582,17 @@ r535_gsp_rpc_poll(struct nvkm_gsp *gsp, u32 fn) return 0; } +/** + * r535_gsp_rpc_handle_reply - Handle RPC reply based on policy + * @gsp: GSP device + * @fn: RPC function number + * @policy: Reply policy (NOWAIT, NOSEQ, RECV, or POLL) + * @gsp_rpc_len: Expected RPC length + * + * Return: NULL when policy is NOWAIT or NOSEQ (no reply expected), + * pointer to reply data on success, ERR_PTR() on error, + * or NULL if no message available. + */ static void * r535_gsp_rpc_handle_reply(struct nvkm_gsp *gsp, u32 fn, enum nvkm_gsp_rpc_reply_policy policy, @@ -574,6 +620,16 @@ r535_gsp_rpc_handle_reply(struct nvkm_gsp *gsp, u32 fn, return repv; } +/** + * r535_gsp_rpc_send - Send RPC message and handle reply + * @gsp: GSP device + * @payload: RPC payload to send + * @policy: Reply policy (NOWAIT, NOSEQ, RECV, or POLL) + * @gsp_rpc_len: Expected RPC length for reply + * + * Return: NULL if policy is NOWAIT/NOSEQ (no reply expected), + * pointer to reply data on success, or ERR_PTR() on error. + */ static void * r535_gsp_rpc_send(struct nvkm_gsp *gsp, void *payload, enum nvkm_gsp_rpc_reply_policy policy, u32 gsp_rpc_len) @@ -601,6 +657,15 @@ r535_gsp_rpc_send(struct nvkm_gsp *gsp, void *payload, return r535_gsp_rpc_handle_reply(gsp, fn, policy, gsp_rpc_len); } +/** + * r535_gsp_rpc_get - Allocate and initialize an RPC message + * @gsp: GSP device + * @fn: RPC function number + * @payload_size: Size of the payload + * + * Return: Pointer to RPC payload data on success, or ERR_PTR() on error. + * Never returns NULL. + */ static void r535_gsp_rpc_done(struct nvkm_gsp *gsp, void *repv) { @@ -628,6 +693,16 @@ r535_gsp_rpc_get(struct nvkm_gsp *gsp, u32 fn, u32 payload_size) return rpc->data; } +/** + * r535_gsp_rpc_push - Push RPC message to GSP and wait for reply + * @gsp: GSP device + * @payload: RPC payload to send + * @policy: Reply policy (NOWAIT, NOSEQ, RECV, or POLL) + * @gsp_rpc_len: Expected RPC length in the reply + * + * Return: NULL when policy is NOWAIT/NOSEQ (no reply expected), + * pointer to reply data on success, or ERR_PTR() on error. + */ static void * r535_gsp_rpc_push(struct nvkm_gsp *gsp, void *payload, enum nvkm_gsp_rpc_reply_policy policy, u32 gsp_rpc_len) -- 2.25.1
