| Message ID | 1431938505-31779-1-git-send-email-yun.wang@profitbricks.com (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
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 -- 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
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 -- 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
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
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 > > -- 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
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.
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 > -- 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
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.
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