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

[Tony Nguyen <anthony.l.nguyen@intel.com>]

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;
> +};
> +