Re: [PATCH v3 1/5] gpu: nova-core: gsp: fix stale doc comments on command queue methods

["Gary Guo" <gary@garyguo.net>]

On Wed Mar 4, 2026 at 2:46 AM GMT, Eliot Courtney wrote:
> Fix some inaccuracies / old doc comments.
>
> Reviewed-by: Zhi Wang <zhiw@nvidia.com>
> Tested-by: Zhi Wang <zhiw@nvidia.com>
> Signed-off-by: Eliot Courtney <ecourtney@nvidia.com>
> ---
>  drivers/gpu/nova-core/gsp/cmdq.rs | 17 ++++++++---------
>  1 file changed, 8 insertions(+), 9 deletions(-)
>
> diff --git a/drivers/gpu/nova-core/gsp/cmdq.rs b/drivers/gpu/nova-core/gsp/cmdq.rs
> index 492e9489e808..4829830b6921 100644
> --- a/drivers/gpu/nova-core/gsp/cmdq.rs
> +++ b/drivers/gpu/nova-core/gsp/cmdq.rs
> @@ -531,6 +531,7 @@ fn notify_gsp(bar: &Bar0) {
>      ///
>      /// # Errors
>      ///
> +    /// - `EMSGSIZE` if the command exceeds the maximum queue element size.
>      /// - `ETIMEDOUT` if space does not become available within the timeout.
>      /// - `EIO` if the variable payload requested by the command has not been entirely

What's the benefit of enumerating all the error codes like this? Unless all the
mentioned error code here is supposed to be handled, then it doesn't gain much
for them to be mentioned, no?

For the errors that do need special handling, we probably want to use enums to
force their handling.

Best,
Gary


>      ///   written to by its [`CommandToGsp::init_variable_payload`] method.
> @@ -711,22 +712,20 @@ fn wait_for_msg(&self, timeout: Delta) -> Result<GspMessage<'_>> {
>  
>      /// Receive a message from the GSP.
>      ///
> -    /// `init` is a closure tasked with processing the message. It receives a reference to the
> -    /// message in the message queue, and a [`SBufferIter`] pointing to its variable-length
> -    /// payload, if any.
> +    /// The expected message type is specified using the `M` generic parameter. If the pending
> +    /// message has a different function code, `ERANGE` is returned and the message is consumed.
>      ///
> -    /// The expected message is specified using the `M` generic parameter. If the pending message
> -    /// is different, `EAGAIN` is returned and the unexpected message is dropped.
> -    ///
> -    /// This design is by no means final, but it is simple and will let us go through GSP
> -    /// initialization.
> +    /// The read pointer is always advanced past the message, regardless of whether it matched.
>      ///
>      /// # Errors
>      ///
>      /// - `ETIMEDOUT` if `timeout` has elapsed before any message becomes available.
>      /// - `EIO` if there was some inconsistency (e.g. message shorter than advertised) on the
>      ///   message queue.
> -    /// - `EINVAL` if the function of the message was unrecognized.
> +    /// - `EINVAL` if the function code of the message was not recognized.
> +    /// - `ERANGE` if the message had a recognized but non-matching function code.
> +    ///
> +    /// Error codes returned by [`MessageFromGsp::read`] are propagated as-is.
>      pub(crate) fn receive_msg<M: MessageFromGsp>(&mut self, timeout: Delta) -> Result<M>
>      where
>          // This allows all error types, including `Infallible`, to be used for `M::InitError`.