docs: rapidio: convert to ReST

:orphan:

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

The Linux RapidIO Subsystem

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

.. toctree::

   :maxdepth: 1

   rapidio

   sysfs

   tsi721

   mport_cdev

   rio_cm

RapidIO subsystem mport character device driver (rio_mport_cdev.c)

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

Version History:

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

  1.0.0 - Initial driver release.

RapidIO subsystem mport character device driver (rio_mport_cdev.c)

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

I. Overview

1. Overview

===========

This device driver is the result of collaboration within the RapidIO.org

Software Task Group (STG) between Texas Instruments, Freescale,

  as user-space applications while using remaining functionality provided by

  kernel RapidIO subsystem.

II. Hardware Compatibility

2. Hardware Compatibility

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

This device driver uses standard interfaces defined by kernel RapidIO subsystem

and therefore it can be used with any mport device driver registered by RapidIO

  specific DMA engine support and therefore DMA data transfers mport_cdev driver

  are not available.

III. Module parameters

3. Module parameters

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

- 'dma_timeout' - DMA transfer completion timeout (in msec, default value 3000).

- 'dma_timeout'

      - DMA transfer completion timeout (in msec, default value 3000).

        This parameter set a maximum completion wait time for SYNC mode DMA

        transfer requests and for RIO_WAIT_FOR_ASYNC ioctl requests.

- 'dbg_level' - This parameter allows to control amount of debug information

- 'dbg_level'

      - This parameter allows to control amount of debug information

        generated by this device driver. This parameter is formed by set of

        bit masks that correspond to the specific functional blocks.

        For mask definitions see 'drivers/rapidio/devices/rio_mport_cdev.c'

        This parameter can be changed dynamically.

        Use CONFIG_RAPIDIO_DEBUG=y to enable debug output at the top level.

IV. Known problems

4. Known problems

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

  None.

V. User-space Applications and API

5. User-space Applications and API

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

API library and applications that use this device driver are available from

RapidIO.org.

VI. TODO List

6. TODO List

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

- Add support for sending/receiving "raw" RapidIO messaging packets.

- Add memory mapped DMA data transfers as an option when RapidIO-specific DMA

                          The Linux RapidIO Subsystem

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

Introduction

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

The RapidIO standard is a packet-based fabric interconnect standard designed for

use in embedded systems. Development of the RapidIO standard is directed by the

information on its major components.

1 Overview

----------

==========

Because the RapidIO subsystem follows the Linux device model it is integrated

into the kernel similarly to other buses by defining RapidIO-specific device and

subsystem operations.

2. Core Components

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

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

A typical RapidIO network is a combination of endpoints and switches.

Each of these components is represented in the subsystem by an associated data

in include/linux/rio.h file.

2.1 Master Port

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

A master port (or mport) is a RapidIO interface controller that is local to the

processor executing the Linux code. A master port generates and receives RapidIO

implementations of RapidIO functions.

2.2 Device

----------

A RapidIO device is any endpoint (other than mport) or switch in the network.

All devices are presented in the RapidIO subsystem by corresponding rio_dev data

(depending on number of available mports and networks).

2.3 Switch

----------

A RapidIO switch is a special class of device that routes packets between its

ports towards their final destination. The packet destination port within a

implementation of common switch management routines.

2.4 Network

-----------

A RapidIO network is a combination of interconnected endpoint and switch devices.

Each RapidIO network known to the system is represented by corresponding rio_net

master port that is used to communicate with devices within the network.

2.5 Device Drivers

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

RapidIO device-specific drivers follow Linux Kernel Driver Model and are

intended to support specific RapidIO devices attached to the RapidIO network.

2.6 Subsystem Interfaces

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

RapidIO interconnect specification defines features that may be used to provide

one or more common service layers for all participating RapidIO devices. These

the same device without blocking attachment of a device-specific driver.

3. Subsystem Initialization

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

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

In order to initialize the RapidIO subsystem, a platform must initialize and

register at least one master port within the RapidIO network. To register mport

modular component of the kernel (see details below).

4. Enumeration and Discovery

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

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

4.1 Overview

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

  (b) If the RapidIO subsystem core is built as a loadable module, in addition

  to the method shown above, the host destination ID(s) can be specified using

  traditional methods of passing module parameter "hdid=" during its loading:

  - from command line: "modprobe rapidio hdid=-1,7", or

  - from modprobe configuration file using configuration command "options",

    like in this example: "options rapidio hdid=-1,7". An example of modprobe

NOTES:

  (i) if "hdid=" parameter is omitted all available mport will be assigned

  destination ID = -1;

  (ii) the "hdid=" parameter in systems with multiple mports can have

  destination ID assignments omitted from the end of list (default = -1).

This process can be automated by specifying pre- or post- dependencies in the

RapidIO-specific modprobe configuration file as shown in the example below.

  File /etc/modprobe.d/rapidio.conf:

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

File /etc/modprobe.d/rapidio.conf::

  # Configure RapidIO subsystem modules

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

NOTE: In the example above, one of "softdep" commands must be removed or

NOTE:

  In the example above, one of "softdep" commands must be removed or

  commented out to keep required module loading sequence.

A. References

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

5. References

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

[1] RapidIO Trade Association. RapidIO Interconnect Specifications.

    http://www.rapidio.org.

[2] Rapidio TA. Technology Comparisons.

    http://www.rapidio.org/education/technology_comparisons/

[3] RapidIO support for Linux.

    http://lwn.net/Articles/139118/

[4] Matt Porter. RapidIO for Linux. Ottawa Linux Symposium, 2005

    http://www.kernel.org/doc/ols/2005/ols2005v2-pages-43-56.pdf

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

RapidIO subsystem Channelized Messaging character device driver (rio_cm.c)

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

Version History:

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

  1.0.0 - Initial driver release.

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

I. Overview

1. Overview

===========

This device driver is the result of collaboration within the RapidIO.org

Software Task Group (STG) between Texas Instruments, Prodrive Technologies,

Following ioctl commands are available to user-space applications:

- RIO_CM_MPORT_GET_LIST : Returns to caller list of local mport devices that

- RIO_CM_MPORT_GET_LIST:

    Returns to caller list of local mport devices that

    support messaging operations (number of entries up to RIO_MAX_MPORTS).

    Each list entry is combination of mport's index in the system and RapidIO

    destination ID assigned to the port.

- RIO_CM_EP_GET_LIST_SIZE : Returns number of messaging capable remote endpoints

- RIO_CM_EP_GET_LIST_SIZE:

    Returns number of messaging capable remote endpoints

    in a RapidIO network associated with the specified mport device.

- RIO_CM_EP_GET_LIST : Returns list of RapidIO destination IDs for messaging

- RIO_CM_EP_GET_LIST:

    Returns list of RapidIO destination IDs for messaging

    capable remote endpoints (peers) available in a RapidIO network associated

    with the specified mport device.

- RIO_CM_CHAN_CREATE : Creates RapidIO message exchange channel data structure

- RIO_CM_CHAN_CREATE:

    Creates RapidIO message exchange channel data structure

    with channel ID assigned automatically or as requested by a caller.

- RIO_CM_CHAN_BIND : Binds the specified channel data structure to the specified

- RIO_CM_CHAN_BIND:

    Binds the specified channel data structure to the specified

    mport device.

- RIO_CM_CHAN_LISTEN : Enables listening for connection requests on the specified

- RIO_CM_CHAN_LISTEN:

    Enables listening for connection requests on the specified

    channel.

- RIO_CM_CHAN_ACCEPT : Accepts a connection request from peer on the specified

- RIO_CM_CHAN_ACCEPT:

    Accepts a connection request from peer on the specified

    channel. If wait timeout for this request is specified by a caller it is

    a blocking call. If timeout set to 0 this is non-blocking call - ioctl

    handler checks for a pending connection request and if one is not available

    exits with -EGAIN error status immediately.

- RIO_CM_CHAN_CONNECT : Sends a connection request to a remote peer/channel.

- RIO_CM_CHAN_SEND : Sends a data message through the specified channel.

- RIO_CM_CHAN_CONNECT:

    Sends a connection request to a remote peer/channel.

- RIO_CM_CHAN_SEND:

    Sends a data message through the specified channel.

    The handler for this request assumes that message buffer specified by

    a caller includes the reserved space for a packet header required by

    this driver.

- RIO_CM_CHAN_RECEIVE : Receives a data message through a connected channel.

- RIO_CM_CHAN_RECEIVE:

    Receives a data message through a connected channel.

    If the channel does not have an incoming message ready to return this ioctl

    handler will wait for new message until timeout specified by a caller

    expires. If timeout value is set to 0, ioctl handler uses a default value

    defined by MAX_SCHEDULE_TIMEOUT.

- RIO_CM_CHAN_CLOSE : Closes a specified channel and frees associated buffers.

- RIO_CM_CHAN_CLOSE:

    Closes a specified channel and frees associated buffers.

    If the specified channel is in the CONNECTED state, sends close notification

    to the remote peer.

The ioctl command codes and corresponding data structures intended for use by

user-space applications are defined in 'include/uapi/linux/rio_cm_cdev.h'.

II. Hardware Compatibility

2. Hardware Compatibility

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

This device driver uses standard interfaces defined by kernel RapidIO subsystem

and therefore it can be used with any mport device driver registered by RapidIO

subsystem with limitations set by available mport HW implementation of messaging

mailboxes.

III. Module parameters

3. Module parameters

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

- 'dbg_level' - This parameter allows to control amount of debug information

- 'dbg_level'

      - This parameter allows to control amount of debug information

        generated by this device driver. This parameter is formed by set of

        bit masks that correspond to the specific functional block.

        For mask definitions see 'drivers/rapidio/devices/rio_cm.c'

        This parameter can be changed dynamically.

        Use CONFIG_RAPIDIO_DEBUG=y to enable debug output at the top level.

- 'cmbox' - Number of RapidIO mailbox to use (default value is 1).

- 'cmbox'

      - Number of RapidIO mailbox to use (default value is 1).

        This parameter allows to set messaging mailbox number that will be used

        within entire RapidIO network. It can be used when default mailbox is

        used by other device drivers or is not supported by some nodes in the

        RapidIO network.

- 'chstart' - Start channel number for dynamic assignment. Default value - 256.

- 'chstart'

      - Start channel number for dynamic assignment. Default value - 256.

        Allows to exclude channel numbers below this parameter from dynamic

        allocation to avoid conflicts with software components that use

        reserved predefined channel numbers.

IV. Known problems

4. Known problems

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

  None.

V. User-space Applications and API Library

5. User-space Applications and API Library

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

Messaging API library and applications that use this device driver are available

from RapidIO.org.

VI. TODO List

6. TODO List

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

- Add support for system notification messages (reserved channel 0).

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

Sysfs entries

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

The RapidIO sysfs files have moved to:

Documentation/ABI/testing/sysfs-bus-rapidio and

Documentation/ABI/testing/sysfs-class-rapidio