Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1753867AbbERP1S (ORCPT ); Mon, 18 May 2015 11:27:18 -0400 Received: from mail-wg0-f44.google.com ([74.125.82.44]:33379 "EHLO mail-wg0-f44.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1753007AbbERP1I (ORCPT ); Mon, 18 May 2015 11:27:08 -0400 Message-ID: <555A04C8.10802@profitbricks.com> Date: Mon, 18 May 2015 17:27:04 +0200 From: Michael Wang User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:31.0) Gecko/20100101 Thunderbird/31.6.0 MIME-Version: 1.0 To: Doug Ledford CC: Or Gerlitz , Roland Dreier , Sean Hefty , Hal Rosenstock , "linux-rdma@vger.kernel.org" , Linux Kernel , linux-doc@vger.kernel.org, Or Gerlitz , Ira Weiny , Jason Gunthorpe Subject: Re: [PATCH RFC v2] Documentation/infiniband: Add docs for rdma-helpers References: <1431938505-31779-1-git-send-email-yun.wang@profitbricks.com> <5559B997.1030502@profitbricks.com> <1431962485.3114.8.camel@redhat.com> In-Reply-To: <1431962485.3114.8.camel@redhat.com> Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 7bit Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Length: 6873 Lines: 173 On 05/18/2015 05:21 PM, Doug Ledford wrote: [snip] >> >> 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. I see :-) I've not work with the kdoc yet, not sure if there is any guidelines on how to write the header of inline func for kdoc? > > 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. Got it, if there is anything I could help, please let me know ;-) Regards, Michael Wang > >> >> 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 >> --- >> 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 >>>> --- >>>> 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@vger.kernel.org >>>> More majordomo info at http://vger.kernel.org/majordomo-info.html > > -- To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/