[PATCH v3] NTB: switchtec_ntb: Update switchtec documentation with pre-requisites for NTB

[PATCH v3] NTB: switchtec_ntb: Update switchtec documentation with pre-requisites for NTB

[Wesley Sheng]

From: Wesley Yung <wesley.yung@microchip.com>

The ntb_hw_switchtec driver has requirements on kernel configuration
so we add these notes to the documentation and also clean up a few 
other sentences in the documentation.

Signed-off-by: Wesley Yung <wesley.yung@microchip.com>
Signed-off-by: Kelvin Cao <kelvin.cao@microchip.com>
Signed-off-by: Wesley Sheng <wesley.sheng@microchip.com>
---
 Documentation/switchtec.txt | 30 ++++++++++++++++++++----------
 1 file changed, 20 insertions(+), 10 deletions(-)

diff --git a/Documentation/switchtec.txt b/Documentation/switchtec.txt
index f788264..d6f04dcc 100644
--- a/Documentation/switchtec.txt
+++ b/Documentation/switchtec.txt
@@ -23,7 +23,7 @@ The primary means of communicating with the Switchtec management firmware is
 through the Memory-mapped Remote Procedure Call (MRPC) interface.
 Commands are submitted to the interface with a 4-byte command
 identifier and up to 1KB of command specific data. The firmware will
-respond with a 4 bytes return code and up to 1KB of command specific
+respond with a 4-byte return code and up to 1KB of command specific
 data. The interface only processes a single command at a time.
 
 
@@ -36,8 +36,8 @@ device: /dev/switchtec#, one for each management endpoint in the system.
 The char device has the following semantics:
 
 * A write must consist of at least 4 bytes and no more than 1028 bytes.
-  The first four bytes will be interpreted as the command to run and
-  the remainder will be used as the input data. A write will send the
+  The first 4 bytes will be interpreted as the Command ID and the
+  remainder will be used as the input data. A write will send the
   command to the firmware to begin processing.
 
 * Each write must be followed by exactly one read. Any double write will
@@ -45,9 +45,9 @@ The char device has the following semantics:
   produce an error.
 
 * A read will block until the firmware completes the command and return
-  the four bytes of status plus up to 1024 bytes of output data. (The
-  length will be specified by the size parameter of the read call --
-  reading less than 4 bytes will produce an error.
+  the 4-byte Command Return Value plus up to 1024 bytes of output
+  data. (The length will be specified by the size parameter of the read
+  call -- reading less than 4 bytes will produce an error.)
 
 * The poll call will also be supported for userspace applications that
   need to do other things while waiting for the command to complete.
@@ -83,10 +83,20 @@ The following IOCTLs are also supported by the device:
 Non-Transparent Bridge (NTB) Driver
 ===================================
 
-An NTB driver is provided for the switchtec hardware in switchtec_ntb.
-Currently, it only supports switches configured with exactly 2
-partitions. It also requires the following configuration settings:
+An NTB hardware driver is provided for the Switchtec hardware in
+ntb_hw_switchtec. Currently, it only supports switches configured with
+exactly 2 NT partitions and zero or more non-NT partitions. It also requires
+the following configuration settings:
 
-* Both partitions must be able to access each other's GAS spaces.
+* Both NT partitions must be able to access each other's GAS spaces.
   Thus, the bits in the GAS Access Vector under Management Settings
   must be set to support this.
+* Kernel configuration MUST include support for NTB (CONFIG_NTB needs
+  to be set)
+
+NT EP BAR 2 will be dynamically configured as a Direct Window, and
+the configuration file does not need to configure it explicitly.
+
+Please refer to Documentation/ntb.txt in Linux source tree for an overall
+understanding of the Linux NTB stack. ntb_hw_switchtec works as an NTB
+Hardware Driver in this stack.
-- 
2.7.4

[PATCH v3] NTB: switchtec_ntb: Update switchtec documentation with pre-requisites for NTB

[Wesley Sheng]

From: Wesley Yung <wesley.yung@microchip.com>

The ntb_hw_switchtec driver has requirements on kernel configuration
so we add these notes to the documentation and also clean up a few 
other sentences in the documentation.

Signed-off-by: Wesley Yung <wesley.yung@microchip.com>
Signed-off-by: Kelvin Cao <kelvin.cao@microchip.com>
Signed-off-by: Wesley Sheng <wesley.sheng@microchip.com>
---
 Documentation/switchtec.txt | 30 ++++++++++++++++++++----------
 1 file changed, 20 insertions(+), 10 deletions(-)

diff --git a/Documentation/switchtec.txt b/Documentation/switchtec.txt
index f788264..d6f04dcc 100644
--- a/Documentation/switchtec.txt
+++ b/Documentation/switchtec.txt
@@ -23,7 +23,7 @@ The primary means of communicating with the Switchtec management firmware is
 through the Memory-mapped Remote Procedure Call (MRPC) interface.
 Commands are submitted to the interface with a 4-byte command
 identifier and up to 1KB of command specific data. The firmware will
-respond with a 4 bytes return code and up to 1KB of command specific
+respond with a 4-byte return code and up to 1KB of command specific
 data. The interface only processes a single command at a time.
 
 
@@ -36,8 +36,8 @@ device: /dev/switchtec#, one for each management endpoint in the system.
 The char device has the following semantics:
 
 * A write must consist of at least 4 bytes and no more than 1028 bytes.
-  The first four bytes will be interpreted as the command to run and
-  the remainder will be used as the input data. A write will send the
+  The first 4 bytes will be interpreted as the Command ID and the
+  remainder will be used as the input data. A write will send the
   command to the firmware to begin processing.
 
 * Each write must be followed by exactly one read. Any double write will
@@ -45,9 +45,9 @@ The char device has the following semantics:
   produce an error.
 
 * A read will block until the firmware completes the command and return
-  the four bytes of status plus up to 1024 bytes of output data. (The
-  length will be specified by the size parameter of the read call --
-  reading less than 4 bytes will produce an error.
+  the 4-byte Command Return Value plus up to 1024 bytes of output
+  data. (The length will be specified by the size parameter of the read
+  call -- reading less than 4 bytes will produce an error.)
 
 * The poll call will also be supported for userspace applications that
   need to do other things while waiting for the command to complete.
@@ -83,10 +83,20 @@ The following IOCTLs are also supported by the device:
 Non-Transparent Bridge (NTB) Driver
 ===================================
 
-An NTB driver is provided for the switchtec hardware in switchtec_ntb.
-Currently, it only supports switches configured with exactly 2
-partitions. It also requires the following configuration settings:
+An NTB hardware driver is provided for the Switchtec hardware in
+ntb_hw_switchtec. Currently, it only supports switches configured with
+exactly 2 NT partitions and zero or more non-NT partitions. It also requires
+the following configuration settings:
 
-* Both partitions must be able to access each other's GAS spaces.
+* Both NT partitions must be able to access each other's GAS spaces.
   Thus, the bits in the GAS Access Vector under Management Settings
   must be set to support this.
+* Kernel configuration MUST include support for NTB (CONFIG_NTB needs
+  to be set)
+
+NT EP BAR 2 will be dynamically configured as a Direct Window, and
+the configuration file does not need to configure it explicitly.
+
+Please refer to Documentation/ntb.txt in Linux source tree for an overall
+understanding of the Linux NTB stack. ntb_hw_switchtec works as an NTB
+Hardware Driver in this stack.
-- 
2.7.4

Re: [PATCH v3] NTB: switchtec_ntb: Update switchtec documentation with pre-requisites for NTB

[Logan Gunthorpe]

On 2018-10-10 8:42 a.m., Wesley Sheng wrote:
> From: Wesley Yung <wesley.yung@microchip.com>
> 
> The ntb_hw_switchtec driver has requirements on kernel configuration
> so we add these notes to the documentation and also clean up a few 
> other sentences in the documentation.
> 
> Signed-off-by: Wesley Yung <wesley.yung@microchip.com>
> Signed-off-by: Kelvin Cao <kelvin.cao@microchip.com>
> Signed-off-by: Wesley Sheng <wesley.sheng@microchip.com>

Reviewed-by: Logan Gunthorpe <logang@deltatee.com>

Re: [PATCH v3] NTB: switchtec_ntb: Update switchtec documentation with pre-requisites for NTB

[Bjorn Helgaas]

[+cc Jon Mason]

On Wed, Oct 10, 2018 at 10:42:55PM +0800, Wesley Sheng wrote:
> From: Wesley Yung <wesley.yung@microchip.com>
> 
> The ntb_hw_switchtec driver has requirements on kernel configuration
> so we add these notes to the documentation and also clean up a few 
> other sentences in the documentation.
> 
> Signed-off-by: Wesley Yung <wesley.yung@microchip.com>
> Signed-off-by: Kelvin Cao <kelvin.cao@microchip.com>
> Signed-off-by: Wesley Sheng <wesley.sheng@microchip.com>

I'm not sure who should really own this file:

  $ ./scripts/get_maintainer.pl -f Documentation/switchtec.txt
  Kurt Schwemmer <kurt.schwemmer@microsemi.com> (maintainer:PCI DRIVER FOR MICROSEMI SWITCHTEC)
  Logan Gunthorpe <logang@deltatee.com> (maintainer:PCI DRIVER FOR MICROSEMI SWITCHTEC)
  Jonathan Corbet <corbet@lwn.net> (maintainer:DOCUMENTATION)
  linux-pci@vger.kernel.org (open list:PCI DRIVER FOR MICROSEMI SWITCHTEC)
  linux-doc@vger.kernel.org (open list:DOCUMENTATION)
  linux-kernel@vger.kernel.org (open list)

and Jon (NTB driver core maintainer) has applied recent updates
to it.

But in the interest of forward progress, I applied this patch with
Logan's ack to pci/misc for v4.20.

> ---
>  Documentation/switchtec.txt | 30 ++++++++++++++++++++----------
>  1 file changed, 20 insertions(+), 10 deletions(-)
> 
> diff --git a/Documentation/switchtec.txt b/Documentation/switchtec.txt
> index f788264..d6f04dcc 100644
> --- a/Documentation/switchtec.txt
> +++ b/Documentation/switchtec.txt
> @@ -23,7 +23,7 @@ The primary means of communicating with the Switchtec management firmware is
>  through the Memory-mapped Remote Procedure Call (MRPC) interface.
>  Commands are submitted to the interface with a 4-byte command
>  identifier and up to 1KB of command specific data. The firmware will
> -respond with a 4 bytes return code and up to 1KB of command specific
> +respond with a 4-byte return code and up to 1KB of command specific
>  data. The interface only processes a single command at a time.
>  
>  
> @@ -36,8 +36,8 @@ device: /dev/switchtec#, one for each management endpoint in the system.
>  The char device has the following semantics:
>  
>  * A write must consist of at least 4 bytes and no more than 1028 bytes.
> -  The first four bytes will be interpreted as the command to run and
> -  the remainder will be used as the input data. A write will send the
> +  The first 4 bytes will be interpreted as the Command ID and the
> +  remainder will be used as the input data. A write will send the
>    command to the firmware to begin processing.
>  
>  * Each write must be followed by exactly one read. Any double write will
> @@ -45,9 +45,9 @@ The char device has the following semantics:
>    produce an error.
>  
>  * A read will block until the firmware completes the command and return
> -  the four bytes of status plus up to 1024 bytes of output data. (The
> -  length will be specified by the size parameter of the read call --
> -  reading less than 4 bytes will produce an error.
> +  the 4-byte Command Return Value plus up to 1024 bytes of output
> +  data. (The length will be specified by the size parameter of the read
> +  call -- reading less than 4 bytes will produce an error.)
>  
>  * The poll call will also be supported for userspace applications that
>    need to do other things while waiting for the command to complete.
> @@ -83,10 +83,20 @@ The following IOCTLs are also supported by the device:
>  Non-Transparent Bridge (NTB) Driver
>  ===================================
>  
> -An NTB driver is provided for the switchtec hardware in switchtec_ntb.
> -Currently, it only supports switches configured with exactly 2
> -partitions. It also requires the following configuration settings:
> +An NTB hardware driver is provided for the Switchtec hardware in
> +ntb_hw_switchtec. Currently, it only supports switches configured with
> +exactly 2 NT partitions and zero or more non-NT partitions. It also requires
> +the following configuration settings:
>  
> -* Both partitions must be able to access each other's GAS spaces.
> +* Both NT partitions must be able to access each other's GAS spaces.
>    Thus, the bits in the GAS Access Vector under Management Settings
>    must be set to support this.
> +* Kernel configuration MUST include support for NTB (CONFIG_NTB needs
> +  to be set)
> +
> +NT EP BAR 2 will be dynamically configured as a Direct Window, and
> +the configuration file does not need to configure it explicitly.
> +
> +Please refer to Documentation/ntb.txt in Linux source tree for an overall
> +understanding of the Linux NTB stack. ntb_hw_switchtec works as an NTB
> +Hardware Driver in this stack.
> -- 
> 2.7.4
> 

Re: [PATCH v3] NTB: switchtec_ntb: Update switchtec documentation with pre-requisites for NTB

[Logan Gunthorpe]

On 2018-10-11 10:27 a.m., Bjorn Helgaas wrote:
> I'm not sure who should really own this file:
> 
>   $ ./scripts/get_maintainer.pl -f Documentation/switchtec.txt
>   Kurt Schwemmer <kurt.schwemmer@microsemi.com> (maintainer:PCI DRIVER FOR MICROSEMI SWITCHTEC)
>   Logan Gunthorpe <logang@deltatee.com> (maintainer:PCI DRIVER FOR MICROSEMI SWITCHTEC)
>   Jonathan Corbet <corbet@lwn.net> (maintainer:DOCUMENTATION)
>   linux-pci@vger.kernel.org (open list:PCI DRIVER FOR MICROSEMI SWITCHTEC)
>   linux-doc@vger.kernel.org (open list:DOCUMENTATION)
>   linux-kernel@vger.kernel.org (open list)
> 
> and Jon (NTB driver core maintainer) has applied recent updates
> to it.
> 
> But in the interest of forward progress, I applied this patch with
> Logan's ack to pci/misc for v4.20.

Thanks. I'm not really sure what's going on in the NTB tree these days
as Jon hasn't picked up anything in a while so it's probably better this
went through PCI. It was originally created through the PCI tree, there
shouldn't be any conflicts, and I can't see anyone else objecting.

Logan

[PATCH v3] NTB: switchtec_ntb: Update switchtec documentation with pre-requisites for NTB

[Wesley Sheng]

From: Wesley Yung <wesley.yung@microchip.com>

The ntb_hw_switchtec driver has requirements on kernel configuration
so we add these notes to the documentation and also clean up a few 
other sentences in the documentation.

Signed-off-by: Wesley Yung <wesley.yung@microchip.com>
Signed-off-by: Kelvin Cao <kelvin.cao@microchip.com>
Signed-off-by: Wesley Sheng <wesleyshenggit@sina.com>
---
 Documentation/switchtec.txt | 30 ++++++++++++++++++++----------
 1 file changed, 20 insertions(+), 10 deletions(-)

diff --git a/Documentation/switchtec.txt b/Documentation/switchtec.txt
index f788264..d6f04dcc 100644
--- a/Documentation/switchtec.txt
+++ b/Documentation/switchtec.txt
@@ -23,7 +23,7 @@ The primary means of communicating with the Switchtec management firmware is
 through the Memory-mapped Remote Procedure Call (MRPC) interface.
 Commands are submitted to the interface with a 4-byte command
 identifier and up to 1KB of command specific data. The firmware will
-respond with a 4 bytes return code and up to 1KB of command specific
+respond with a 4-byte return code and up to 1KB of command specific
 data. The interface only processes a single command at a time.
 
 
@@ -36,8 +36,8 @@ device: /dev/switchtec#, one for each management endpoint in the system.
 The char device has the following semantics:
 
 * A write must consist of at least 4 bytes and no more than 1028 bytes.
-  The first four bytes will be interpreted as the command to run and
-  the remainder will be used as the input data. A write will send the
+  The first 4 bytes will be interpreted as the Command ID and the
+  remainder will be used as the input data. A write will send the
   command to the firmware to begin processing.
 
 * Each write must be followed by exactly one read. Any double write will
@@ -45,9 +45,9 @@ The char device has the following semantics:
   produce an error.
 
 * A read will block until the firmware completes the command and return
-  the four bytes of status plus up to 1024 bytes of output data. (The
-  length will be specified by the size parameter of the read call --
-  reading less than 4 bytes will produce an error.
+  the 4-byte Command Return Value plus up to 1024 bytes of output
+  data. (The length will be specified by the size parameter of the read
+  call -- reading less than 4 bytes will produce an error.)
 
 * The poll call will also be supported for userspace applications that
   need to do other things while waiting for the command to complete.
@@ -83,10 +83,20 @@ The following IOCTLs are also supported by the device:
 Non-Transparent Bridge (NTB) Driver
 ===================================
 
-An NTB driver is provided for the switchtec hardware in switchtec_ntb.
-Currently, it only supports switches configured with exactly 2
-partitions. It also requires the following configuration settings:
+An NTB hardware driver is provided for the Switchtec hardware in
+ntb_hw_switchtec. Currently, it only supports switches configured with
+exactly 2 NT partitions and zero or more non-NT partitions. It also requires
+the following configuration settings:
 
-* Both partitions must be able to access each other's GAS spaces.
+* Both NT partitions must be able to access each other's GAS spaces.
   Thus, the bits in the GAS Access Vector under Management Settings
   must be set to support this.
+* Kernel configuration MUST include support for NTB (CONFIG_NTB needs
+  to be set)
+
+NT EP BAR 2 will be dynamically configured as a Direct Window, and
+the configuration file does not need to configure it explicitly.
+
+Please refer to Documentation/ntb.txt in Linux source tree for an overall
+understanding of the Linux NTB stack. ntb_hw_switchtec works as an NTB
+Hardware Driver in this stack.
-- 
2.7.4

[PATCH v3] NTB: switchtec_ntb: Update switchtec documentation with pre-requisites for NTB

[Wesley Sheng]

From: Wesley Yung <wesley.yung@microchip.com>

The ntb_hw_switchtec driver has requirements on kernel configuration
so we add these notes to the documentation and also clean up a few 
other sentences in the documentation.

Signed-off-by: Wesley Yung <wesley.yung@microchip.com>
Signed-off-by: Kelvin Cao <kelvin.cao@microchip.com>
Signed-off-by: Wesley Sheng <wesleyshenggit@sina.com>
---
 Documentation/switchtec.txt | 30 ++++++++++++++++++++----------
 1 file changed, 20 insertions(+), 10 deletions(-)

diff --git a/Documentation/switchtec.txt b/Documentation/switchtec.txt
index f788264..d6f04dcc 100644
--- a/Documentation/switchtec.txt
+++ b/Documentation/switchtec.txt
@@ -23,7 +23,7 @@ The primary means of communicating with the Switchtec management firmware is
 through the Memory-mapped Remote Procedure Call (MRPC) interface.
 Commands are submitted to the interface with a 4-byte command
 identifier and up to 1KB of command specific data. The firmware will
-respond with a 4 bytes return code and up to 1KB of command specific
+respond with a 4-byte return code and up to 1KB of command specific
 data. The interface only processes a single command at a time.
 
 
@@ -36,8 +36,8 @@ device: /dev/switchtec#, one for each management endpoint in the system.
 The char device has the following semantics:
 
 * A write must consist of at least 4 bytes and no more than 1028 bytes.
-  The first four bytes will be interpreted as the command to run and
-  the remainder will be used as the input data. A write will send the
+  The first 4 bytes will be interpreted as the Command ID and the
+  remainder will be used as the input data. A write will send the
   command to the firmware to begin processing.
 
 * Each write must be followed by exactly one read. Any double write will
@@ -45,9 +45,9 @@ The char device has the following semantics:
   produce an error.
 
 * A read will block until the firmware completes the command and return
-  the four bytes of status plus up to 1024 bytes of output data. (The
-  length will be specified by the size parameter of the read call --
-  reading less than 4 bytes will produce an error.
+  the 4-byte Command Return Value plus up to 1024 bytes of output
+  data. (The length will be specified by the size parameter of the read
+  call -- reading less than 4 bytes will produce an error.)
 
 * The poll call will also be supported for userspace applications that
   need to do other things while waiting for the command to complete.
@@ -83,10 +83,20 @@ The following IOCTLs are also supported by the device:
 Non-Transparent Bridge (NTB) Driver
 ===================================
 
-An NTB driver is provided for the switchtec hardware in switchtec_ntb.
-Currently, it only supports switches configured with exactly 2
-partitions. It also requires the following configuration settings:
+An NTB hardware driver is provided for the Switchtec hardware in
+ntb_hw_switchtec. Currently, it only supports switches configured with
+exactly 2 NT partitions and zero or more non-NT partitions. It also requires
+the following configuration settings:
 
-* Both partitions must be able to access each other's GAS spaces.
+* Both NT partitions must be able to access each other's GAS spaces.
   Thus, the bits in the GAS Access Vector under Management Settings
   must be set to support this.
+* Kernel configuration MUST include support for NTB (CONFIG_NTB needs
+  to be set)
+
+NT EP BAR 2 will be dynamically configured as a Direct Window, and
+the configuration file does not need to configure it explicitly.
+
+Please refer to Documentation/ntb.txt in Linux source tree for an overall
+understanding of the Linux NTB stack. ntb_hw_switchtec works as an NTB
+Hardware Driver in this stack.
-- 
2.7.4

Re: [PATCH v3] NTB: switchtec_ntb: Update switchtec documentation with pre-requisites for NTB

[Jonathan Corbet]

On Wed, 10 Oct 2018 20:33:08 +0800
Wesley Sheng <wesleyshenggit@sina.com> wrote:

> The ntb_hw_switchtec driver has requirements on kernel configuration
> so we add these notes to the documentation and also clean up a few 
> other sentences in the documentation.
> 
> Signed-off-by: Wesley Yung <wesley.yung@microchip.com>
> Signed-off-by: Kelvin Cao <kelvin.cao@microchip.com>
> Signed-off-by: Wesley Sheng <wesleyshenggit@sina.com>

So why all of these signoffs for such a small patch?  Who is the actual
author of the patch?

Thanks,

jon

Re: [PATCH v3] NTB: switchtec_ntb: Update switchtec documentation with pre-requisites for NTB

[Logan Gunthorpe]

On 2018-10-12 11:30 a.m., Jonathan Corbet wrote:
> On Wed, 10 Oct 2018 20:33:08 +0800
> Wesley Sheng <wesleyshenggit@sina.com> wrote:
> 
>> The ntb_hw_switchtec driver has requirements on kernel configuration
>> so we add these notes to the documentation and also clean up a few 
>> other sentences in the documentation.
>>
>> Signed-off-by: Wesley Yung <wesley.yung@microchip.com>
>> Signed-off-by: Kelvin Cao <kelvin.cao@microchip.com>
>> Signed-off-by: Wesley Sheng <wesleyshenggit@sina.com>
> 
> So why all of these signoffs for such a small patch?  Who is the actual
> author of the patch?

It was originally two very small patches from Mr. Yung[1] and Mr. Cao[2]
combined and then cleaned up for upstream by Mr. Sheng.

There will likely be a bit more of this as they intend on upstreaming
more of the work that has been done out-of-tree. I believe most of this
is minor bug fixes and small feature additions.

Logan

[1]
https://github.com/Microsemi/switchtec-kernel/commit/5e7e7709c8ce6f37163113a8b6282aa4a788b6a0

[2]
https://github.com/Microsemi/switchtec-kernel/commit/e25fbb7267a742d08ca0802e0a6886c183e8b7b4