xiaomi-sm8450/android_kernel_xiaomi_sm8450
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: rapidio: add it to the driver API

Browse Source 
This is actually a subsystem description, with contains both
kAPI and uAPI.

While it should ideally be slplit, let's place it at driver-api,
as most things are related to kAPI and driver-specific info.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
This commit is contained in:
Mauro Carvalho Chehab
2019-06-18 16:03:23 -03:00
parent 74684f8ff4
commit d2bdd48a65
10 changed files with 3 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
Documentation/driver-api/index.rst
View File

@@ -45,7 +45,7 @@ available subsections can be seen below.
miscellaneous
mei/index
w1
rapidio
rapidio/index
s390-drivers
vme
80211/index

107
Documentation/driver-api/rapidio.rst
View File

@@ -1,107 +0,0 @@
=======================
RapidIO Subsystem Guide
=======================
:Author: Matt Porter
Introduction
============
RapidIO is a high speed switched fabric interconnect with features aimed
at the embedded market. RapidIO provides support for memory-mapped I/O
as well as message-based transactions over the switched fabric network.
RapidIO has a standardized discovery mechanism not unlike the PCI bus
standard that allows simple detection of devices in a network.
This documentation is provided for developers intending to support
RapidIO on new architectures, write new drivers, or to understand the
subsystem internals.
Known Bugs and Limitations
==========================
Bugs
----
None. ;)
Limitations
-----------
1. Access/management of RapidIO memory regions is not supported
2. Multiple host enumeration is not supported
RapidIO driver interface
========================
Drivers are provided a set of calls in order to interface with the
subsystem to gather info on devices, request/map memory region
resources, and manage mailboxes/doorbells.
Functions
---------
.. kernel-doc:: include/linux/rio_drv.h
:internal:
.. kernel-doc:: drivers/rapidio/rio-driver.c
:export:
.. kernel-doc:: drivers/rapidio/rio.c
:export:
Internals
=========
This chapter contains the autogenerated documentation of the RapidIO
subsystem.
Structures
----------
.. kernel-doc:: include/linux/rio.h
:internal:
Enumeration and Discovery
-------------------------
.. kernel-doc:: drivers/rapidio/rio-scan.c
:internal:
Driver functionality
--------------------
.. kernel-doc:: drivers/rapidio/rio.c
:internal:
.. kernel-doc:: drivers/rapidio/rio-access.c
:internal:
Device model support
--------------------
.. kernel-doc:: drivers/rapidio/rio-driver.c
:internal:
PPC32 support
-------------
.. kernel-doc:: arch/powerpc/sysdev/fsl_rio.c
:internal:
Credits
=======
The following people have contributed to the RapidIO subsystem directly
or indirectly:
1. Matt Porter\ mporter@kernel.crashing.org
2. Randy Vinson\ rvinson@mvista.com
3. Dan Malek\ dan@embeddedalley.com
The following people have contributed to this document:
1. Matt Porter\ mporter@kernel.crashing.org

13
Documentation/driver-api/rapidio/index.rst Normal file
View File

@@ -0,0 +1,13 @@
===========================
The Linux RapidIO Subsystem
===========================
.. toctree::
:maxdepth: 1
rapidio
sysfs
tsi721
mport_cdev
rio_cm

110
Documentation/driver-api/rapidio/mport_cdev.rst Normal file
View File

@@ -0,0 +1,110 @@
==================================================================
RapidIO subsystem mport character device driver (rio_mport_cdev.c)
==================================================================
1. Overview
===========
This device driver is the result of collaboration within the RapidIO.org
Software Task Group (STG) between Texas Instruments, Freescale,
Prodrive Technologies, Nokia Networks, BAE and IDT. Additional input was
received from other members of RapidIO.org. The objective was to create a
character mode driver interface which exposes the capabilities of RapidIO
devices directly to applications, in a manner that allows the numerous and
varied RapidIO implementations to interoperate.
This driver (MPORT_CDEV) provides access to basic RapidIO subsystem operations
for user-space applications. Most of RapidIO operations are supported through
'ioctl' system calls.
When loaded this device driver creates filesystem nodes named rio_mportX in /dev
directory for each registered RapidIO mport device. 'X' in the node name matches
to unique port ID assigned to each local mport device.
Using available set of ioctl commands user-space applications can perform
following RapidIO bus and subsystem operations:
- Reads and writes from/to configuration registers of mport devices
(RIO_MPORT_MAINT_READ_LOCAL/RIO_MPORT_MAINT_WRITE_LOCAL)
- Reads and writes from/to configuration registers of remote RapidIO devices.
This operations are defined as RapidIO Maintenance reads/writes in RIO spec.
(RIO_MPORT_MAINT_READ_REMOTE/RIO_MPORT_MAINT_WRITE_REMOTE)
- Set RapidIO Destination ID for mport devices (RIO_MPORT_MAINT_HDID_SET)
- Set RapidIO Component Tag for mport devices (RIO_MPORT_MAINT_COMPTAG_SET)
- Query logical index of mport devices (RIO_MPORT_MAINT_PORT_IDX_GET)
- Query capabilities and RapidIO link configuration of mport devices
(RIO_MPORT_GET_PROPERTIES)
- Enable/Disable reporting of RapidIO doorbell events to user-space applications
(RIO_ENABLE_DOORBELL_RANGE/RIO_DISABLE_DOORBELL_RANGE)
- Enable/Disable reporting of RIO port-write events to user-space applications
(RIO_ENABLE_PORTWRITE_RANGE/RIO_DISABLE_PORTWRITE_RANGE)
- Query/Control type of events reported through this driver: doorbells,
port-writes or both (RIO_SET_EVENT_MASK/RIO_GET_EVENT_MASK)
- Configure/Map mport's outbound requests window(s) for specific size,
RapidIO destination ID, hopcount and request type
(RIO_MAP_OUTBOUND/RIO_UNMAP_OUTBOUND)
- Configure/Map mport's inbound requests window(s) for specific size,
RapidIO base address and local memory base address
(RIO_MAP_INBOUND/RIO_UNMAP_INBOUND)
- Allocate/Free contiguous DMA coherent memory buffer for DMA data transfers
to/from remote RapidIO devices (RIO_ALLOC_DMA/RIO_FREE_DMA)
- Initiate DMA data transfers to/from remote RapidIO devices (RIO_TRANSFER).
Supports blocking, asynchronous and posted (a.k.a 'fire-and-forget') data
transfer modes.
- Check/Wait for completion of asynchronous DMA data transfer
(RIO_WAIT_FOR_ASYNC)
- Manage device objects supported by RapidIO subsystem (RIO_DEV_ADD/RIO_DEV_DEL).
This allows implementation of various RapidIO fabric enumeration algorithms
as user-space applications while using remaining functionality provided by
kernel RapidIO subsystem.
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 implementation.
At this moment the most common limitation is availability of RapidIO-specific
DMA engine framework for specific mport device. Users should verify available
functionality of their platform when planning to use this driver:
- IDT Tsi721 PCIe-to-RapidIO bridge device and its mport device driver are fully
compatible with this driver.
- Freescale SoCs 'fsl_rio' mport driver does not have implementation for RapidIO
specific DMA engine support and therefore DMA data transfers mport_cdev driver
are not available.
3. Module parameters
====================
- '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
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.
4. Known problems
=================
None.
5. User-space Applications and API
==================================
API library and applications that use this device driver are available from
RapidIO.org.
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
is not available.

362
Documentation/driver-api/rapidio/rapidio.rst Normal file
View File

@@ -0,0 +1,362 @@
============
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
RapidIO Trade Association (RTA). The current version of the RapidIO specification
is publicly available for download from the RTA web-site [1].
This document describes the basics of the Linux RapidIO subsystem and provides
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
bus types and registering them within the device model.
The Linux RapidIO subsystem is architecture independent and therefore defines
architecture-specific interfaces that provide support for common RapidIO
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
structure. The core logical components of the RapidIO subsystem are defined
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
packets (transactions). In the RapidIO subsystem each master port is represented
by a rio_mport data structure. This structure contains master port specific
resources such as mailboxes and doorbells. The rio_mport also includes a unique
host device ID that is valid when a master port is configured as an enumerating
host.
RapidIO master ports are serviced by subsystem specific mport device drivers
that provide functionality defined for this subsystem. To provide a hardware
independent interface for RapidIO subsystem operations, rio_mport structure
includes rio_ops data structure which contains pointers to hardware specific
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
structure. Devices form one global device list and per-network device lists
(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
switch is defined by an internal routing table. A switch is presented in the
RapidIO subsystem by rio_dev data structure expanded by additional rio_switch
data structure, which contains switch specific information such as copy of the
routing table and pointers to switch specific functions.
The RapidIO subsystem defines the format and initialization method for subsystem
specific switch drivers that are designed to provide hardware-specific
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
data structure. This structure includes lists of all devices and local master
ports that form the same network. It also contains a pointer to the default
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
common services may act separately from device-specific drivers or be used by
device-specific drivers. Example of such service provider is the RIONET driver
which implements Ethernet-over-RapidIO interface. Because only one driver can be
registered for a device, all common RapidIO services have to be registered as
subsystem interfaces. This allows to have multiple common services attached to
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
within the subsystem controller driver's initialization code calls function
rio_register_mport() for each available master port.
After all active master ports are registered with a RapidIO subsystem,
an enumeration and/or discovery routine may be called automatically or
by user-space command.
RapidIO subsystem can be configured to be built as a statically linked or
modular component of the kernel (see details below).
4. Enumeration and Discovery
============================
4.1 Overview
------------
RapidIO subsystem configuration options allow users to build enumeration and
discovery methods as statically linked components or loadable modules.
An enumeration/discovery method implementation and available input parameters
define how any given method can be attached to available RapidIO mports:
simply to all available mports OR individually to the specified mport device.
Depending on selected enumeration/discovery build configuration, there are
several methods to initiate an enumeration and/or discovery process:
(a) Statically linked enumeration and discovery process can be started
automatically during kernel initialization time using corresponding module
parameters. This was the original method used since introduction of RapidIO
subsystem. Now this method relies on enumerator module parameter which is
'rio-scan.scan' for existing basic enumeration/discovery method.
When automatic start of enumeration/discovery is used a user has to ensure
that all discovering endpoints are started before the enumerating endpoint
and are waiting for enumeration to be completed.
Configuration option CONFIG_RAPIDIO_DISC_TIMEOUT defines time that discovering
endpoint waits for enumeration to be completed. If the specified timeout
expires the discovery process is terminated without obtaining RapidIO network
information. NOTE: a timed out discovery process may be restarted later using
a user-space command as it is described below (if the given endpoint was
enumerated successfully).
(b) Statically linked enumeration and discovery process can be started by
a command from user space. This initiation method provides more flexibility
for a system startup compared to the option (a) above. After all participating
endpoints have been successfully booted, an enumeration process shall be
started first by issuing a user-space command, after an enumeration is
completed a discovery process can be started on all remaining endpoints.
(c) Modular enumeration and discovery process can be started by a command from
user space. After an enumeration/discovery module is loaded, a network scan
process can be started by issuing a user-space command.
Similar to the option (b) above, an enumerator has to be started first.
(d) Modular enumeration and discovery process can be started by a module
initialization routine. In this case an enumerating module shall be loaded
first.
When a network scan process is started it calls an enumeration or discovery
routine depending on the configured role of a master port: host or agent.
Enumeration is performed by a master port if it is configured as a host port by
assigning a host destination ID greater than or equal to zero. The host
destination ID can be assigned to a master port using various methods depending
on RapidIO subsystem build configuration:
(a) For a statically linked RapidIO subsystem core use command line parameter
"rapidio.hdid=" with a list of destination ID assignments in order of mport
device registration. For example, in a system with two RapidIO controllers
the command line parameter "rapidio.hdid=-1,7" will result in assignment of
the host destination ID=7 to the second RapidIO controller, while the first
one will be assigned destination ID=-1.
(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
configuration file is provided in the section below.
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).
If the host device ID for a specific master port is set to -1, the discovery
process will be performed for it.
The enumeration and discovery routines use RapidIO maintenance transactions
to access the configuration space of devices.
NOTE: If RapidIO switch-specific device drivers are built as loadable modules
they must be loaded before enumeration/discovery process starts.
This requirement is cased by the fact that enumeration/discovery methods invoke
vendor-specific callbacks on early stages.
4.2 Automatic Start of Enumeration and Discovery
------------------------------------------------
Automatic enumeration/discovery start method is applicable only to built-in
enumeration/discovery RapidIO configuration selection. To enable automatic
enumeration/discovery start by existing basic enumerator method set use boot
command line parameter "rio-scan.scan=1".
This configuration requires synchronized start of all RapidIO endpoints that
form a network which will be enumerated/discovered. Discovering endpoints have
to be started before an enumeration starts to ensure that all RapidIO
controllers have been initialized and are ready to be discovered. Configuration
parameter CONFIG_RAPIDIO_DISC_TIMEOUT defines time (in seconds) which
a discovering endpoint will wait for enumeration to be completed.
When automatic enumeration/discovery start is selected, basic method's
initialization routine calls rio_init_mports() to perform enumeration or
discovery for all known mport devices.
Depending on RapidIO network size and configuration this automatic
enumeration/discovery start method may be difficult to use due to the
requirement for synchronized start of all endpoints.
4.3 User-space Start of Enumeration and Discovery
-------------------------------------------------
User-space start of enumeration and discovery can be used with built-in and
modular build configurations. For user-space controlled start RapidIO subsystem
creates the sysfs write-only attribute file '/sys/bus/rapidio/scan'. To initiate
an enumeration or discovery process on specific mport device, a user needs to
write mport_ID (not RapidIO destination ID) into that file. The mport_ID is a
sequential number (0 ... RIO_MAX_MPORTS) assigned during mport device
registration. For example for machine with single RapidIO controller, mport_ID
for that controller always will be 0.
To initiate RapidIO enumeration/discovery on all available mports a user may
write '-1' (or RIO_MPORT_ANY) into the scan attribute file.
4.4 Basic Enumeration Method
----------------------------
This is an original enumeration/discovery method which is available since
first release of RapidIO subsystem code. The enumeration process is
implemented according to the enumeration algorithm outlined in the RapidIO
Interconnect Specification: Annex I [1].
This method can be configured as statically linked or loadable module.
The method's single parameter "scan" allows to trigger the enumeration/discovery
process from module initialization routine.
This enumeration/discovery method can be started only once and does not support
unloading if it is built as a module.
The enumeration process traverses the network using a recursive depth-first
algorithm. When a new device is found, the enumerator takes ownership of that
device by writing into the Host Device ID Lock CSR. It does this to ensure that
the enumerator has exclusive right to enumerate the device. If device ownership
is successfully acquired, the enumerator allocates a new rio_dev structure and
initializes it according to device capabilities.
If the device is an endpoint, a unique device ID is assigned to it and its value
is written into the device's Base Device ID CSR.
If the device is a switch, the enumerator allocates an additional rio_switch
structure to store switch specific information. Then the switch's vendor ID and
device ID are queried against a table of known RapidIO switches. Each switch
table entry contains a pointer to a switch-specific initialization routine that
initializes pointers to the rest of switch specific operations, and performs
hardware initialization if necessary. A RapidIO switch does not have a unique
device ID; it relies on hopcount and routing for device ID of an attached
endpoint if access to its configuration registers is required. If a switch (or
chain of switches) does not have any endpoint (except enumerator) attached to
it, a fake device ID will be assigned to configure a route to that switch.
In the case of a chain of switches without endpoint, one fake device ID is used
to configure a route through the entire chain and switches are differentiated by
their hopcount value.
For both endpoints and switches the enumerator writes a unique component tag
into device's Component Tag CSR. That unique value is used by the error
management notification mechanism to identify a device that is reporting an
error management event.
Enumeration beyond a switch is completed by iterating over each active egress
port of that switch. For each active link, a route to a default device ID
(0xFF for 8-bit systems and 0xFFFF for 16-bit systems) is temporarily written
into the routing table. The algorithm recurs by calling itself with hopcount + 1
and the default device ID in order to access the device on the active port.
After the host has completed enumeration of the entire network it releases
devices by clearing device ID locks (calls rio_clear_locks()). For each endpoint
in the system, it sets the Discovered bit in the Port General Control CSR
to indicate that enumeration is completed and agents are allowed to execute
passive discovery of the network.
The discovery process is performed by agents and is similar to the enumeration
process that is described above. However, the discovery process is performed
without changes to the existing routing because agents only gather information
about RapidIO network structure and are building an internal map of discovered
devices. This way each Linux-based component of the RapidIO subsystem has
a complete view of the network. The discovery process can be performed
simultaneously by several agents. After initializing its RapidIO master port
each agent waits for enumeration completion by the host for the configured wait
time period. If this wait time period expires before enumeration is completed,
an agent skips RapidIO discovery and continues with remaining kernel
initialization.
4.5 Adding New Enumeration/Discovery Method
-------------------------------------------
RapidIO subsystem code organization allows addition of new enumeration/discovery
methods as new configuration options without significant impact to the core
RapidIO code.
A new enumeration/discovery method has to be attached to one or more mport
devices before an enumeration/discovery process can be started. Normally,
method's module initialization routine calls rio_register_scan() to attach
an enumerator to a specified mport device (or devices). The basic enumerator
implementation demonstrates this process.
4.6 Using Loadable RapidIO Switch Drivers
-----------------------------------------
In the case when RapidIO switch drivers are built as loadable modules a user
must ensure that they are loaded before the enumeration/discovery starts.
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::
# Configure RapidIO subsystem modules
# Set enumerator host destination ID (overrides kernel command line option)
options rapidio hdid=-1,2
# Load RapidIO switch drivers immediately after rapidio core module was loaded
softdep rapidio post: idt_gen2 idtcps tsi57x
# OR :
# Load RapidIO switch drivers just before rio-scan enumerator module is loaded
softdep rio-scan pre: idt_gen2 idtcps tsi57x
--------------------------
NOTE:
In the example above, one of "softdep" commands must be removed or
commented out to keep required module loading sequence.
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

135
Documentation/driver-api/rapidio/rio_cm.rst Normal file
View File

@@ -0,0 +1,135 @@
==========================================================================
RapidIO subsystem Channelized Messaging character device driver (rio_cm.c)
==========================================================================
1. Overview
===========
This device driver is the result of collaboration within the RapidIO.org
Software Task Group (STG) between Texas Instruments, Prodrive Technologies,
Nokia Networks, BAE and IDT. Additional input was received from other members
of RapidIO.org.
The objective was to create a character mode driver interface which exposes
messaging capabilities of RapidIO endpoint devices (mports) directly
to applications, in a manner that allows the numerous and varied RapidIO
implementations to interoperate.
This driver (RIO_CM) provides to user-space applications shared access to
RapidIO mailbox messaging resources.
RapidIO specification (Part 2) defines that endpoint devices may have up to four
messaging mailboxes in case of multi-packet message (up to 4KB) and
up to 64 mailboxes if single-packet messages (up to 256 B) are used. In addition
to protocol definition limitations, a particular hardware implementation can
have reduced number of messaging mailboxes. RapidIO aware applications must
therefore share the messaging resources of a RapidIO endpoint.
Main purpose of this device driver is to provide RapidIO mailbox messaging
capability to large number of user-space processes by introducing socket-like
operations using a single messaging mailbox. This allows applications to
use the limited RapidIO messaging hardware resources efficiently.
Most of device driver's operations are supported through 'ioctl' system calls.
When loaded this device driver creates a single file system node named rio_cm
in /dev directory common for all registered RapidIO mport devices.
Following ioctl commands are available to user-space applications:
- 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
in a RapidIO network associated with the specified mport device.
- 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
with channel ID assigned automatically or as requested by a caller.
- 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
channel.
- 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.
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.
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.
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'.
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.
3. Module parameters
====================
- '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).
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.
Allows to exclude channel numbers below this parameter from dynamic
allocation to avoid conflicts with software components that use
reserved predefined channel numbers.
4. Known problems
=================
None.
5. User-space Applications and API Library
==========================================
Messaging API library and applications that use this device driver are available
from RapidIO.org.
6. TODO List
============
- Add support for system notification messages (reserved channel 0).

7
Documentation/driver-api/rapidio/sysfs.rst Normal file
View File

@@ -0,0 +1,7 @@
=============
Sysfs entries
=============
The RapidIO sysfs files have moved to:
Documentation/ABI/testing/sysfs-bus-rapidio and
Documentation/ABI/testing/sysfs-class-rapidio

112
Documentation/driver-api/rapidio/tsi721.rst Normal file
View File

@@ -0,0 +1,112 @@
=========================================================================
RapidIO subsystem mport driver for IDT Tsi721 PCI Express-to-SRIO bridge.
=========================================================================
1. Overview
===========
This driver implements all currently defined RapidIO mport callback functions.
It supports maintenance read and write operations, inbound and outbound RapidIO
doorbells, inbound maintenance port-writes and RapidIO messaging.
To generate SRIO maintenance transactions this driver uses one of Tsi721 DMA
channels. This mechanism provides access to larger range of hop counts and
destination IDs without need for changes in outbound window translation.
RapidIO messaging support uses dedicated messaging channels for each mailbox.
For inbound messages this driver uses destination ID matching to forward messages
into the corresponding message queue. Messaging callbacks are implemented to be
fully compatible with RIONET driver (Ethernet over RapidIO messaging services).
1. Module parameters:
- 'dbg_level'
- This parameter allows to control amount of debug information
generated by this device driver. This parameter is formed by set of
This parameter can be changed bit masks that correspond to the specific
functional block.
For mask definitions see 'drivers/rapidio/devices/tsi721.h'
This parameter can be changed dynamically.
Use CONFIG_RAPIDIO_DEBUG=y to enable debug output at the top level.
- 'dma_desc_per_channel'
- This parameter defines number of hardware buffer
descriptors allocated for each registered Tsi721 DMA channel.
Its default value is 128.
- 'dma_txqueue_sz'
- DMA transactions queue size. Defines number of pending
transaction requests that can be accepted by each DMA channel.
Default value is 16.
- 'dma_sel'
- DMA channel selection mask. Bitmask that defines which hardware
DMA channels (0 ... 6) will be registered with DmaEngine core.
If bit is set to 1, the corresponding DMA channel will be registered.
DMA channels not selected by this mask will not be used by this device
driver. Default value is 0x7f (use all channels).
- 'pcie_mrrs'
- override value for PCIe Maximum Read Request Size (MRRS).
This parameter gives an ability to override MRRS value set during PCIe
configuration process. Tsi721 supports read request sizes up to 4096B.
Value for this parameter must be set as defined by PCIe specification:
0 = 128B, 1 = 256B, 2 = 512B, 3 = 1024B, 4 = 2048B and 5 = 4096B.
Default value is '-1' (= keep platform setting).
- 'mbox_sel'
- RIO messaging MBOX selection mask. This is a bitmask that defines
messaging MBOXes are managed by this device driver. Mask bits 0 - 3
correspond to MBOX0 - MBOX3. MBOX is under driver's control if the
corresponding bit is set to '1'. Default value is 0x0f (= all).
2. Known problems
=================
None.
3. DMA Engine Support
=====================
Tsi721 mport driver supports DMA data transfers between local system memory and
remote RapidIO devices. This functionality is implemented according to SLAVE
mode API defined by common Linux kernel DMA Engine framework.
Depending on system requirements RapidIO DMA operations can be included/excluded
by setting CONFIG_RAPIDIO_DMA_ENGINE option. Tsi721 miniport driver uses seven
out of eight available BDMA channels to support DMA data transfers.
One BDMA channel is reserved for generation of maintenance read/write requests.
If Tsi721 mport driver have been built with RAPIDIO_DMA_ENGINE support included,
this driver will accept DMA-specific module parameter:
"dma_desc_per_channel"
- defines number of hardware buffer descriptors used by
each BDMA channel of Tsi721 (by default - 128).
4. Version History
===== ====================================================================
1.1.0 DMA operations re-worked to support data scatter/gather lists larger
than hardware buffer descriptors ring.
1.0.0 Initial driver release.
===== ====================================================================
5. License
===========
Copyright(c) 2011 Integrated Device Technology, Inc. All rights reserved.
This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the Free
Software Foundation; either version 2 of the License, or (at your option)
any later version.
This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
more details.
You should have received a copy of the GNU General Public License along with
this program; if not, write to the Free Software Foundation, Inc.,
59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.