Date:	Mon, 18 May 2015 11:21:25 -0400
From:	Doug Ledford <dledford@...hat.com>
To:	Michael Wang <yun.wang@...fitbricks.com>
Cc:	Or Gerlitz <gerlitz.or@...il.com>,
	Roland Dreier <roland@...nel.org>,
	Sean Hefty <sean.hefty@...el.com>,
	Hal Rosenstock <hal@....mellanox.co.il>,
	"linux-rdma@...r.kernel.org" <linux-rdma@...r.kernel.org>,
	Linux Kernel <linux-kernel@...r.kernel.org>,
	linux-doc@...r.kernel.org, Or Gerlitz <ogerlitz@...lanox.com>,
	Ira Weiny <ira.weiny@...el.com>,
	Jason Gunthorpe <jgunthorpe@...idianresearch.com>
Subject: Re: [PATCH RFC v2] Documentation/infiniband: Add docs for
 rdma-helpers

On Mon, 2015-05-18 at 12:06 +0200, Michael Wang wrote:
> Hi, Or
> 
> On 05/18/2015 11:47 AM, Or Gerlitz wrote:
> [snip]
> >> Highlights:
> >>   There could be many missing/mistakes/misunderstanding, please don't
> >>   be hesitate to point out the issues, any suggestions to improve or
> >>   complete the description are very welcomed ;-)
> > 
> > Michael, none of what you wrote above belongs to the change-log which
> > is going to stay for-ever in the upstream git repo. You should put it
> > all belong the --- line after your S.O.B and add proper change log
> > telling what this patch is about
> 
> Thanks for point out this for me :-)
> 
> I'll put the highlights and changelog under '---' in next version, is it
> looks like this?

We're still missing Jason's feedback request though.  Specifically, he
pointed out that kdocs are usually not done in Documentation/*, they are
done in the .c files where the function is (or the .h file if the
function is an inline, which these all are).  So, you included some
limited documentation for each of these items in your original patches
that added them.  His request was that you put this expanded information
not in Documentation/infiniband where someone has to go looking for it,
but as part of the kdoc header for each of the various helpers in
ib_verbs.h itself.

Just because I want to move this along versus waiting for another
respin, I'm going to copy and paste these into those locations and clean
up the changelog when I integrate this patch.

> 
> Subject: [PATCH RFC v3] Documentation/infiniband: Add docs for rdma-helpers
> 
> This is the following patch for:
>   https://lkml.org/lkml/2015/5/5/417
> which try to document the settled rdma_cap_XX().
> 
> Signed-off-by: Michael Wang <yun.wang@...fitbricks.com>
> ---
> Highlights:
>   There could be many missing/mistakes/misunderstanding, please don't
>   be hesitate to point out the issues, any suggestions to improve or
>   complete the description are very welcomed ;-)
> 
> v2:
>   * Merge the descriptions from Doug:
>     http://www.spinics.net/lists/linux-rdma/msg25172.html
> 
> v3:
>   ...
> 
>  Documentation/infiniband/rdma_helpers.txt | 79 +++++++++++++++++++++++++++++++
>  1 file changed, 79 insertions(+)
>  create mode 100644 Documentation/infiniband/rdma_helpers.txt
> 
> diff --git a/Documentation/infiniband/rdma_helpers.txt b/Documentation/infiniband/rdma_helpers.txt
> new file mode 100644
> index 0000000..be9416d
> --- /dev/null
> +++ b/Documentation/infiniband/rdma_helpers.txt
> 
> Regards,
> Michael Wang
> 
> > 
> >>
> >> Signed-off-by: Michael Wang <yun.wang@...fitbricks.com>
> >> ---
> >>  Documentation/infiniband/rdma_helpers.txt | 79 +++++++++++++++++++++++++++++++
> >>  1 file changed, 79 insertions(+)
> >>  create mode 100644 Documentation/infiniband/rdma_helpers.txt
> >>
> >> diff --git a/Documentation/infiniband/rdma_helpers.txt b/Documentation/infiniband/rdma_helpers.txt
> >> new file mode 100644
> >> index 0000000..be9416d
> >> --- /dev/null
> >> +++ b/Documentation/infiniband/rdma_helpers.txt
> >> @@ -0,0 +1,79 @@
> >> +RDMA HELPERS
> >> +
> >> +  The following helpers are used to check the specific capabilities of a
> >> +  particular port before utilizing those capabilities.
> >> +
> >> +    rdma_cap_ib_mad            - Infiniband Management Datagrams.
> >> +    rdma_cap_ib_smi            - Infiniband Subnet Management Interface.
> >> +    rdma_cap_ib_cm             - Infiniband Communication Manager.
> >> +    rdma_cap_iw_cm             - IWARP Communication Manager.
> >> +    rdma_cap_ib_sa             - Infiniband Subnet Administration.
> >> +    rdma_cap_ib_mcast          - Infiniband Multicast Join/Leave Protocol.
> >> +    rdma_cap_read_multi_sge    - RDMA Read Work Request Support Multiple SGE.
> >> +    rdma_cap_af_ib             - Native Infiniband Address.
> >> +    rdma_cap_eth_ah            - InfiniBand Transport With Ethernet Address.
> >> +
> >> +USAGE
> >> +
> >> +  if (rdma_cap_XX(device, i)) {
> >> +       /* The port i of device support XX */
> >> +       ...
> >> +  } else {
> >> +       /* The port i of device don't support XX */
> >> +       ...
> >> +  }
> >> +
> >> +  rdma_cap_ib_mad
> >> +  ---------------
> >> +    Management Datagrams (MAD) are a required part of the InfiniBand
> >> +    specification and are supported on all InfiniBand devices.  A slightly
> >> +    extended version are also supported on OPA interfaces.
> >> +
> >> +  rdma_cap_ib_smi
> >> +  ---------------
> >> +    Subnet Management Interface (SMI) will handle SMP packet from SM
> >> +    in an infiniband fabric.
> >> +
> >> +  rdma_cap_ib_cm
> >> +  ---------------
> >> +    Communication Manager (CM) service, used to ease the process of connecting
> >> +    to a remote host.  The IB-CM can be used to connect to remote hosts using
> >> +    either InfiniBand or RoCE connections, iWARP has its own CM.
> >> +
> >> +  rdma_cap_iw_cm
> >> +  ---------------
> >> +    iWARP Communication Manager (CM), Similar to the IB-CM, but only used on
> >> +    iWARP devices.
> >> +
> >> +  rdma_cap_ib_sa
> >> +  ---------------
> >> +    Subnet Administration (SA) is the database built by SM in an
> >> +    infiniband fabric.
> >> +
> >> +  rdma_cap_ib_mcast
> >> +  ---------------
> >> +    InfiniBand (and OPA) use a different multicast mechanism rather than
> >> +    traditional IP multicast found on Ethernet devices.  If this is true, then
> >> +    traditional IPv4/IPv6 multicast is handled by the IPoIB layer and direct
> >> +    multicast joins and leaves are handled per the InfiniBand specifications.
> >> +
> >> +  rdma_cap_read_multi_sge
> >> +  ---------------
> >> +    Certain devices (iWARP in particular) have restrictions on the number of
> >> +    scatter gather elements that can be present in an RDMA READ work request,
> >> +    this is true if the device does not have that restriction.
> >> +
> >> +  rdma_cap_af_ib
> >> +  ---------------
> >> +    Many code paths for traditional InfiniBand and RoCE links are the same,
> >> +    but need minor differences to accommodate the different addresses on the
> >> +    two types of connections.  This helper is true when the address of the
> >> +    specific connection is of the InfiniBand native variety.
> >> +
> >> +  rdma_cap_eth_ah
> >> +  ---------------
> >> +    Queue Pair is InfiniBand transport, but uses Ethernet address instead
> >> +    of native InfiniBand address (aka, this is a RoCE QP, and that means
> >> +    ethertype 0x8915 + GRH for RoCEv1 and IP/UDP to well known UDP port for
> >> +    RoCEv2), this is true when the address family of the specific queue pair
> >> +    is of the Ethernet (RoCE) variety.
> >> --
> >> 2.1.0
> >>
> >> --
> >> To unsubscribe from this list: send the line "unsubscribe linux-rdma" in
> >> the body of a message to majordomo@...r.kernel.org
> >> More majordomo info at  http://vger.kernel.org/majordomo-info.html


-- 
Doug Ledford <dledford@...hat.com>
              GPG KeyID: 0E572FDD


Download attachment "signature.asc" of type "application/pgp-signature" (820 bytes)

Powered by blists - more mailing lists