Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 97162a1e authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab Committed by Jason Gunthorpe
Browse files

docs: infiniband: convert docs to ReST and rename to *.rst 



The InfiniBand docs are plain text with no markups.  So, all we needed to
do were to add the title markups and some markup sequences in order to
properly parse tables, lists and literal blocks.

At its new index.rst, let's add a :orphan: while this is not linked to the
main index.rst file, in order to avoid build warnings.

Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: default avatarJason Gunthorpe <jgg@mellanox.com>
parent b417c087

Documentation/infiniband/core_locking.txt→Documentation/infiniband/core_locking.rst

+35 −29
Original line number Diff line number Diff line 
INFINIBAND MIDLAYER LOCKING

===========================

InfiniBand Midlayer Locking

===========================



  This guide is an attempt to make explicit the locking assumptions

  made by the InfiniBand midlayer.  It describes the requirements on
@@ -6,45 +8,47 @@ INFINIBAND MIDLAYER LOCKING 
  protocols that use the midlayer.



Sleeping and interrupt context

==============================



  With the following exceptions, a low-level driver implementation of

  all of the methods in struct ib_device may sleep.  The exceptions

  are any methods from the list:



    create_ah

    modify_ah

    query_ah

    destroy_ah

    post_send

    post_recv

    poll_cq

    req_notify_cq

    map_phys_fmr

    - create_ah

    - modify_ah

    - query_ah

    - destroy_ah

    - post_send

    - post_recv

    - poll_cq

    - req_notify_cq

    - map_phys_fmr



  which may not sleep and must be callable from any context.



  The corresponding functions exported to upper level protocol

  consumers:



    ib_create_ah

    ib_modify_ah

    ib_query_ah

    ib_destroy_ah

    ib_post_send

    ib_post_recv

    ib_req_notify_cq

    ib_map_phys_fmr

    - ib_create_ah

    - ib_modify_ah

    - ib_query_ah

    - ib_destroy_ah

    - ib_post_send

    - ib_post_recv

    - ib_req_notify_cq

    - ib_map_phys_fmr



  are therefore safe to call from any context.



  In addition, the function



    ib_dispatch_event

    - ib_dispatch_event



  used by low-level drivers to dispatch asynchronous events through

  the midlayer is also safe to call from any context.



Reentrancy

----------



  All of the methods in struct ib_device exported by a low-level

  driver must be fully reentrant.  The low-level driver is required to
@@ -62,6 +66,7 @@ Reentrancy 
  information between different calls of ib_poll_cq() is not defined.



Callbacks

---------



  A low-level driver must not perform a callback directly from the

  same callchain as an ib_device method call.  For example, it is not
@@ -74,7 +79,7 @@ Callbacks 
  completion event handlers for the same CQ are not called

  simultaneously.  The driver must guarantee that only one CQ event

  handler for a given CQ is running at a time.  In other words, the

  following situation is not allowed:

  following situation is not allowed::



          CPU1                                    CPU2
@@ -93,6 +98,7 @@ Callbacks 
  Upper level protocol consumers may not sleep in a callback.



Hot-plug

--------



  A low-level driver announces that a device is ready for use by

  consumers when it calls ib_register_device(), all initialization

Documentation/infiniband/index.rst

0 → 100644
+23 −0
Original line number Diff line number Diff line 
:orphan:



==========

InfiniBand

==========



.. toctree::

   :maxdepth: 1



   core_locking

   ipoib

   opa_vnic

   sysfs

   tag_matching

   user_mad

   user_verbs



.. only::  subproject and html



   Indices

   =======



   * :ref:`genindex`

Documentation/infiniband/ipoib.txt→Documentation/infiniband/ipoib.rst

+17 −7
Original line number Diff line number Diff line 
IP OVER INFINIBAND

==================

IP over InfiniBand

==================



  The ib_ipoib driver is an implementation of the IP over InfiniBand

  protocol as specified by RFC 4391 and 4392, issued by the IETF ipoib
@@ -8,16 +10,17 @@ IP OVER INFINIBAND 
  masqueraded to the kernel as ethernet interfaces).



Partitions and P_Keys

=====================



  When the IPoIB driver is loaded, it creates one interface for each

  port using the P_Key at index 0.  To create an interface with a

  different P_Key, write the desired P_Key into the main interface's

  /sys/class/net/<intf name>/create_child file.  For example:

  /sys/class/net/<intf name>/create_child file.  For example::



    echo 0x8001 > /sys/class/net/ib0/create_child



  This will create an interface named ib0.8001 with P_Key 0x8001.  To

  remove a subinterface, use the "delete_child" file:

  remove a subinterface, use the "delete_child" file::



    echo 0x8001 > /sys/class/net/ib0/delete_child
@@ -28,6 +31,7 @@ Partitions and P_Keys 
  rtnl_link_ops, where children created using either way behave the same.



Datagram vs Connected modes

===========================



  The IPoIB driver supports two modes of operation: datagram and

  connected.  The mode is set and read through an interface's
@@ -51,6 +55,7 @@ Datagram vs Connected modes 
  networking stack to use the smaller UD MTU for these neighbours.



Stateless offloads

==================



  If the IB HW supports IPoIB stateless offloads, IPoIB advertises

  TCP/IP checksum and/or Large Send (LSO) offloading capability to the
@@ -63,6 +68,7 @@ Stateless offloads 
  Stateless offloads are supported only in datagram mode.



Interrupt moderation

====================



  If the underlying IB device supports CQ event moderation, one can

  use ethtool to set interrupt mitigation parameters and thus reduce
@@ -71,6 +77,7 @@ Interrupt moderation 
  moderation is supported.



Debugging Information

=====================



  By compiling the IPoIB driver with CONFIG_INFINIBAND_IPOIB_DEBUG set

  to 'y', tracing messages are compiled into the driver.  They are
@@ -79,7 +86,7 @@ Debugging Information 
  runtime through files in /sys/module/ib_ipoib/.



  CONFIG_INFINIBAND_IPOIB_DEBUG also enables files in the debugfs

  virtual filesystem.  By mounting this filesystem, for example with

  virtual filesystem.  By mounting this filesystem, for example with::



    mount -t debugfs none /sys/kernel/debug
@@ -96,10 +103,13 @@ Debugging Information 
  performance, because it adds tests to the fast path.



References

==========



  Transmission of IP over InfiniBand (IPoIB) (RFC 4391)

    http://ietf.org/rfc/rfc4391.txt



  IP over InfiniBand (IPoIB) Architecture (RFC 4392)

    http://ietf.org/rfc/rfc4392.txt



  IP over InfiniBand: Connected Mode (RFC 4755)

    http://ietf.org/rfc/rfc4755.txt

Documentation/infiniband/opa_vnic.txt→Documentation/infiniband/opa_vnic.rst

+58 −52
Original line number Diff line number Diff line 
=================================================================

Intel Omni-Path (OPA) Virtual Network Interface Controller (VNIC)

=================================================================



Intel Omni-Path (OPA) Virtual Network Interface Controller (VNIC) feature

supports Ethernet functionality over Omni-Path fabric by encapsulating

the Ethernet packets between HFI nodes.
@@ -17,7 +21,7 @@ an independent Ethernet network. The configuration is performed by an 
Ethernet Manager (EM) which is part of the trusted Fabric Manager (FM)

application. HFI nodes can have multiple VNICs each connected to a

different virtual Ethernet switch. The below diagram presents a case

of two virtual Ethernet switches with two HFI nodes.

of two virtual Ethernet switches with two HFI nodes::



                               +-------------------+

                               |      Subnet/      |
@@ -47,8 +51,9 @@ of two virtual Ethernet switches with two HFI nodes. 


The Omni-Path encapsulated Ethernet packet format is as described below.



==================== ================================

Bits                 Field

------------------------------------

==================== ================================

Quad Word 0:

0-19                 SLID (lower 20 bits)

20-30                Length (in Quad Words)
@@ -81,6 +86,7 @@ Quad Word N (last): 
24-55                ICRC

56-61                Tail

62-63                LT (=01, Link Transfer Tail Flit)

==================== ================================



Ethernet packet is padded on the transmit side to ensure that the VNIC OPA

packet is quad word aligned. The 'Tail' field contains the number of bytes
@@ -123,7 +129,7 @@ operation. It also handles the encapsulation of Ethernet packets with an 
Omni-Path header in the transmit path. For each VNIC interface, the

information required for encapsulation is configured by the EM via VEMA MAD

interface. It also passes any control information to the HW dependent driver

by invoking the RDMA netdev control operations.

by invoking the RDMA netdev control operations::



        +-------------------+ +----------------------+

        |                   | |       Linux          |

Documentation/infiniband/sysfs.txt→Documentation/infiniband/sysfs.rst

+3 −1
Original line number Diff line number Diff line 
SYSFS FILES

===========

Sysfs files

===========



The sysfs interface has moved to

Documentation/ABI/stable/sysfs-class-infiniband.