[PATCH RFC v2] Documentation/infiniband: Add docs for rdma-helpers

[PATCH RFC v2] Documentation/infiniband: Add docs for rdma-helpers

[Michael Wang]

Since v1:
  * Merge the descriptions from Doug:
    http://www.spinics.net/lists/linux-rdma/msg25172.html

This is the following patch for:
  https://lkml.org/lkml/2015/5/5/417
which try to document the settled rdma_cap_XX().

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 ;-)

Signed-off-by: Michael Wang <yun.wang@profitbricks.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

Re: [PATCH RFC v2] Documentation/infiniband: Add docs for rdma-helpers

[Or Gerlitz]

On Mon, May 18, 2015 at 11:41 AM, Michael Wang
<yun.wang@profitbricks.com> wrote:
> Since v1:
>   * Merge the descriptions from Doug:
>     http://www.spinics.net/lists/linux-rdma/msg25172.html
>
> This is the following patch for:
>   https://lkml.org/lkml/2015/5/5/417
> which try to document the settled rdma_cap_XX().
>
> 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

>
> Signed-off-by: Michael Wang <yun.wang@profitbricks.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@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH RFC v2] Documentation/infiniband: Add docs for rdma-helpers

[Michael Wang]

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?


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@profitbricks.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@profitbricks.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@vger.kernel.org
>> More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH RFC v2] Documentation/infiniband: Add docs for rdma-helpers

[Doug Ledford]

[-- Attachment #1: Type: text/plain, Size: 7182 bytes --]

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@profitbricks.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@profitbricks.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@vger.kernel.org
> >> More majordomo info at  http://vger.kernel.org/majordomo-info.html


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


[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 819 bytes --]

Re: [PATCH RFC v2] Documentation/infiniband: Add docs for rdma-helpers

[Michael Wang]

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 <yun.wang@profitbricks.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@profitbricks.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@vger.kernel.org
>>>> More majordomo info at  http://vger.kernel.org/majordomo-info.html
> 
> 

Re: [PATCH RFC v2] Documentation/infiniband: Add docs for rdma-helpers

[Doug Ledford]

[-- Attachment #1: Type: text/plain, Size: 1670 bytes --]

On Mon, 2015-05-18 at 17:27 +0200, Michael Wang wrote:
> 
> 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?

It's an automated tool thing.  Any comment section that starts with /**
is automatically included as a kdoc.  Then there is an expected format
after that.  See Documentation/kernel-doc-nano-HOWTO.txt.

> > 
> > 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 ;-)

I'm sending the patch for review, please let me know if you are OK with
how I handled the attribution.

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


[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 819 bytes --]

Re: [PATCH RFC v2] Documentation/infiniband: Add docs for rdma-helpers

[Michael Wang]

On 05/18/2015 06:58 PM, Doug Ledford wrote:
[snip]
>> 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?
> 
> It's an automated tool thing.  Any comment section that starts with /**
> is automatically included as a kdoc.  Then there is an expected format
> after that.  See Documentation/kernel-doc-nano-HOWTO.txt.

Got it :-)

> 
>>>
>>> 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 ;-)
> 
> I'm sending the patch for review, please let me know if you are OK with
> how I handled the attribution.

The definition is far more detailed and accurate, it's already good enough
according to my understanding, should benefit the developer a lot ;-)

Regards,
Michael Wang

>