Re: [PATCH iwl-next 06/14] libeth: add bookkeeping support for control queue messages

Tony Nguyen
2025-04-15T18:54:19Z

On 4/8/2025 5:47 AM, Larysa Zaremba wrote:
> From: Phani R Burra <phani.r.burra@intel.com>

...
> +/**
> + * struct libeth_ctlq_xn_manager - structure representing the array of virtchnl
> + * transaction entries
> + * @ctx: pointer to controlq context structure
> + * @free_xns_bm_lock: lock to protect the free Xn entries bit map
> + * @free_xns_bm: bitmap that represents the free Xn entries
> + * @ring: array of Xn entries
> + * @cookie: unique message identifier
> + */

Some kdoc issues:
> include/net/libeth/controlq.h:330: warning: Function parameter or
struct member 'can_destroy' not described in 'libeth_ctlq_xn_manager'
> include/net/libeth/controlq.h:330: warning: Function parameter or
struct member 'shutdown' not described in 'libeth_ctlq_xn_manager'

> +struct libeth_ctlq_xn_manager {
> + struct libeth_ctlq_ctx *ctx;
> + spinlock_t free_xns_bm_lock; /* get/check entries */
> + DECLARE_BITMAP(free_xns_bm, LIBETH_CTLQ_MAX_XN_ENTRIES);
> + struct libeth_ctlq_xn ring[LIBETH_CTLQ_MAX_XN_ENTRIES];
> + struct completion can_destroy;
> + bool shutdown;
> + u8 cookie;
> +};
> +
> +/**
> + * struct libeth_ctlq_xn_send_params - structure representing send Xn entry
> + * @resp_cb: callback to handle the response of an asynchronous virtchnl message
> + * @rel_tx_buf: driver entry point for freeing the send buffer after send
> + * @xnm: Xn manager to process Xn entries
> + * @ctlq: send control queue information
> + * @ctlq_msg: control queue message information
> + * @send_buf: represents the buffer that carries outgoing information
> + * @recv_mem: receive buffer
> + * @send_ctx: context for call back function
> + * @timeout_ms: virtchnl transaction timeout in msecs
> + * @chnl_opcode: virtchnl message opcode
> + */
> +struct libeth_ctlq_xn_send_params {
> + void (*resp_cb)(void *ctx, struct kvec *mem, int status);
> + void (*rel_tx_buf)(const void *buf_va);
> + struct libeth_ctlq_xn_manager *xnm;
> + struct libeth_ctlq_info *ctlq;
> + struct libeth_ctlq_msg *ctlq_msg;
> + struct kvec send_buf;
> + struct kvec recv_mem;
> + void *send_ctx;
> + u64 timeout_ms;
> + u32 chnl_opcode;
> +};
> +
> +/**
> + * libeth_cp_can_send_onstack - find if a virtchnl message can be sent using a
> + * stack variable
> + * @size: virtchnl buffer size
> + */

and here:
> include/net/libeth/controlq.h:364: warning: No description found for
return value of 'libeth_cp_can_send_onstack'

> +static inline bool libeth_cp_can_send_onstack(u32 size)
> +{
> + return size <= LIBETH_CP_TX_COPYBREAK;
> +}
> +
> +/**
> + * struct libeth_ctlq_xn_recv_params - structure representing receive Xn entry
> + * @ctlq_msg_handler: callback to handle a message originated from the peer
> + * @xnm: Xn manager to process Xn entries
> + * @ctx: pointer to context structure
> + * @ctlq: control queue information
> + */

and here:
> include/net/libeth/controlq.h:380: warning: Excess struct member
'ctx' description in 'libeth_ctlq_xn_recv_params'

Thanks,
Tony

> +struct libeth_ctlq_xn_recv_params {
> + void (*ctlq_msg_handler)(struct libeth_ctlq_ctx *ctx,
> + struct libeth_ctlq_msg *msg);
> + struct libeth_ctlq_xn_manager *xnm;
> + struct libeth_ctlq_info *ctlq;
> +};
> +