Subject: Re: [PATCH v2] RDMA: Split kernel-only global device caps from uverbs device caps

From: Jason Gunthorpe <[email-masked]>
Date: Thu, 7 Apr 2022 12:52:44 -0300

On Wed, Apr 06, 2022 at 12:57:31PM -0700, Bart Van Assche wrote:
> On 4/6/22 12:27, Jason Gunthorpe wrote:
> > +enum ib_kernel_cap_flags {
> > +	/*
> > +	 * This device supports a per-device lkey or stag that can be
> > +	 * used without performing a memory registration for the local
> > +	 * memory.  Note that ULPs should never check this flag, but
> > +	 * instead of use the local_dma_lkey flag in the ib_pd structure,
> > +	 * which will always contain a usable lkey.
> > +	 */
> > +	IBK_LOCAL_DMA_LKEY = 1 << 0,
> > +	/* IB_QP_CREATE_INTEGRITY_EN is supported to implement T10-PI */
> > +	IBK_INTEGRITY_HANDOVER = 1 << 1,
> > +	/* IB_ACCESS_ON_DEMAND is supported during reg_user_mr() */
> > +	IBK_ON_DEMAND_PAGING = 1 << 2,
> > +	/* IB_MR_TYPE_SG_GAPS is supported */
> > +	IBK_SG_GAPS_REG = 1 << 3,
> > +	/* Driver supports RDMA_NLDEV_CMD_DELLINK */
> > +	IBK_ALLOW_USER_UNREG = 1 << 4,
> > +
> > +	/* ipoib will use IB_QP_CREATE_BLOCK_MULTICAST_LOOPBACK */
> > +	IBK_BLOCK_MULTICAST_LOOPBACK = 1 << 5,
> > +	/* iopib will use IB_QP_CREATE_IPOIB_UD_LSO for its QPs */
> > +	IBK_UD_TSO = 1 << 6,
> > +	/* iopib will use the device ops:
> > +	 *   get_vf_config
> > +	 *   get_vf_guid
> > +	 *   get_vf_stats
> > +	 *   set_vf_guid
> > +	 *   set_vf_link_state
> > +	 */
> > +	IBK_VIRTUAL_FUNCTION = 1 << 7,
> > +	/* ipoib will use IB_QP_CREATE_NETDEV_USE for its QPs */
> > +	IBK_RDMA_NETDEV_OPA = 1 << 8,
> > +};
> 
> Has it been considered to use the kernel-doc syntax? This means moving all
> comments above "enum ib_kernel_cap_flags {".

TBH I'm not a huge fan of kdoc for how wordy it is:

 /** @IBK_RDMA_NETDEV_OPA: ipoib will use IB_QP_CREATE_NETDEV_USE for its QPs */
 IBK_RDMA_NETDEV_OPA = 1 << 8,

Is the shortest format and still a bit awkward.

Given that we don't have a proper kdoc for rdma I haven't been putting
much energy there.

If someone came with patches to make a kdoc chapter and start to
organize it nicely I could see enforcing kdoc format..

Jason