mirror of https://github.com/Qortal/Brooklyn
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
362 lines
17 KiB
362 lines
17 KiB
============ |
|
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. |
|
https://lwn.net/Articles/139118/ |
|
|
|
[4] Matt Porter. RapidIO for Linux. Ottawa Linux Symposium, 2005 |
|
https://www.kernel.org/doc/ols/2005/ols2005v2-pages-43-56.pdf
|
|
|