driver-api/rapidio/rapidio.rst

5 The RapidIO standard is a packet-based fabric interconnect standard designed for
8 is publicly available for download from the RTA web-site [1].
16 Because the RapidIO subsystem follows the Linux device model it is integrated
17 into the kernel similarly to other buses by defining RapidIO-specific device and
18 bus types and registering them within the device model.
21 architecture-specific interfaces that provide support for common RapidIO
33 ---------------
38 by a rio_mport data structure. This structure contains master port specific
40 host device ID that is valid when a master port is configured as an enumerating
43 RapidIO master ports are serviced by subsystem specific mport device drivers
46 includes rio_ops data structure which contains pointers to hardware specific
49 2.2 Device
50 ----------
52 A RapidIO device is any endpoint (other than mport) or switch in the network.
54 structure. Devices form one global device list and per-network device lists
58 ----------
60 A RapidIO switch is a special class of device that routes packets between its
64 data structure, which contains switch specific information such as copy of the
65 routing table and pointers to switch specific functions.
68 specific switch drivers that are designed to provide hardware-specific
72 -----------
80 2.5 Device Drivers
81 ------------------
83 RapidIO device-specific drivers follow Linux Kernel Driver Model and are
84 intended to support specific RapidIO devices attached to the RapidIO network.
87 ------------------------
91 common services may act separately from device-specific drivers or be used by
92 device-specific drivers. Example of such service provider is the RIONET driver
93 which implements Ethernet-over-RapidIO interface. Because only one driver can be
94 registered for a device, all common RapidIO services have to be registered as
96 the same device without blocking attachment of a device-specific driver.
108 by user-space command.
117 ------------
123 simply to all available mports OR individually to the specified mport device.
132   'rio-scan.scan' for existing basic enumeration/discovery method.
140   a user-space command as it is described below (if the given endpoint was
147   started first by issuing a user-space command, after an enumeration is
152   process can be started by issuing a user-space command.
169   device registration. For example, in a system with two RapidIO controllers
170   the command line parameter "rapidio.hdid=-1,7" will result in assignment of
172   one will be assigned destination ID=-1.
178   - from command line: "modprobe rapidio hdid=-1,7", or
179   - from modprobe configuration file using configuration command "options",
180     like in this example: "options rapidio hdid=-1,7". An example of modprobe
185   destination ID = -1;
188   destination ID assignments omitted from the end of list (default = -1).
190 If the host device ID for a specific master port is set to -1, the discovery
196 NOTE: If RapidIO switch-specific device drivers are built as loadable modules
199 vendor-specific callbacks on early stages.
202 ------------------------------------------------
204 Automatic enumeration/discovery start method is applicable only to built-in
207 command line parameter "rio-scan.scan=1".
224 4.3 User-space Start of Enumeration and Discovery
225 -------------------------------------------------
227 User-space start of enumeration and discovery can be used with built-in and
228 modular build configurations. For user-space controlled start RapidIO subsystem
229 creates the sysfs write-only attribute file '/sys/bus/rapidio/scan'. To initiate
230 an enumeration or discovery process on specific mport device, a user needs to
232 sequential number (0 ... RIO_MAX_MPORTS) assigned during mport device
237 write '-1' (or RIO_MPORT_ANY) into the scan attribute file.
240 ----------------------------
254 The enumeration process traverses the network using a recursive depth-first
255 algorithm. When a new device is found, the enumerator takes ownership of that
256 device by writing into the Host Device ID Lock CSR. It does this to ensure that
257 the enumerator has exclusive right to enumerate the device. If device ownership
259 initializes it according to device capabilities.
261 If the device is an endpoint, a unique device ID is assigned to it and its value
262 is written into the device's Base Device ID CSR.
264 If the device is a switch, the enumerator allocates an additional rio_switch
265 structure to store switch specific information. Then the switch's vendor ID and
266 device ID are queried against a table of known RapidIO switches. Each switch
267 table entry contains a pointer to a switch-specific initialization routine that
268 initializes pointers to the rest of switch specific operations, and performs
270 device ID; it relies on hopcount and routing for device ID of an attached
273 it, a fake device ID will be assigned to configure a route to that switch.
274 In the case of a chain of switches without endpoint, one fake device ID is used
279 into device's Component Tag CSR. That unique value is used by the error
280 management notification mechanism to identify a device that is reporting an
284 port of that switch. For each active link, a route to a default device ID
285 (0xFF for 8-bit systems and 0xFFFF for 16-bit systems) is temporarily written
287 and the default device ID in order to access the device on the active port.
290 devices by clearing device ID locks (calls rio_clear_locks()). For each endpoint
299 devices. This way each Linux-based component of the RapidIO subsystem has
308 -------------------------------------------
317 an enumerator to a specified mport device (or devices). The basic enumerator
321 -----------------------------------------
325 This process can be automated by specifying pre- or post- dependencies in the
326 RapidIO-specific modprobe configuration file as shown in the example below.
333   options rapidio hdid=-1,2
340   # Load RapidIO switch drivers just before rio-scan enumerator module is loaded
341   softdep rio-scan pre: idt_gen2 idtcps tsi57x
343   --------------------------
362     https://www.kernel.org/doc/ols/2005/ols2005v2-pages-43-56.pdf