diff options
Diffstat (limited to 'kernel/Documentation/rapidio')
| -rw-r--r-- | kernel/Documentation/rapidio/rapidio.txt | 351 | ||||
| -rw-r--r-- | kernel/Documentation/rapidio/sysfs.txt | 158 | ||||
| -rw-r--r-- | kernel/Documentation/rapidio/tsi721.txt | 62 |
3 files changed, 571 insertions, 0 deletions
diff --git a/kernel/Documentation/rapidio/rapidio.txt b/kernel/Documentation/rapidio/rapidio.txt new file mode 100644 index 000000000..28fbd877f --- /dev/null +++ b/kernel/Documentation/rapidio/rapidio.txt @@ -0,0 +1,351 @@ + The Linux RapidIO Subsystem + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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. + +A. 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 diff --git a/kernel/Documentation/rapidio/sysfs.txt b/kernel/Documentation/rapidio/sysfs.txt new file mode 100644 index 000000000..47ce9a533 --- /dev/null +++ b/kernel/Documentation/rapidio/sysfs.txt @@ -0,0 +1,158 @@ + RapidIO sysfs Files + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. RapidIO Device Subdirectories +-------------------------------- + +For each RapidIO device, the RapidIO subsystem creates files in an individual +subdirectory with the following name, /sys/bus/rapidio/devices/<device_name>. + +The format of device_name is "nn:d:iiii", where: + +nn - two-digit hexadecimal ID of RapidIO network where the device resides +d - device typr: 'e' - for endpoint or 's' - for switch +iiii - four-digit device destID for endpoints, or switchID for switches + +For example, below is a list of device directories that represents a typical +RapidIO network with one switch, one host, and two agent endpoints, as it is +seen by the enumerating host (destID = 1): + +/sys/bus/rapidio/devices/00:e:0000 +/sys/bus/rapidio/devices/00:e:0002 +/sys/bus/rapidio/devices/00:s:0001 + +NOTE: An enumerating or discovering endpoint does not create a sysfs entry for +itself, this is why an endpoint with destID=1 is not shown in the list. + +2. Attributes Common for All RapidIO Devices +-------------------------------------------- + +Each device subdirectory contains the following informational read-only files: + + did - returns the device identifier + vid - returns the device vendor identifier +device_rev - returns the device revision level + asm_did - returns identifier for the assembly containing the device + asm_rev - returns revision level of the assembly containing the device + asm_vid - returns vendor identifier of the assembly containing the device + destid - returns device destination ID assigned by the enumeration routine + (see 4.1 for switch specific details) + lprev - returns name of previous device (switch) on the path to the device + that that owns this attribute + modalias - returns the device modalias + +In addition to the files listed above, each device has a binary attribute file +that allows read/write access to the device configuration registers using +the RapidIO maintenance transactions: + + config - reads from and writes to the device configuration registers. + +This attribute is similar in behavior to the "config" attribute of PCI devices +and provides an access to the RapidIO device registers using standard file read +and write operations. + +3. RapidIO Endpoint Device Attributes +------------------------------------- + +Currently Linux RapidIO subsystem does not create any endpoint specific sysfs +attributes. It is possible that RapidIO master port drivers and endpoint device +drivers will add their device-specific sysfs attributes but such attributes are +outside the scope of this document. + +4. RapidIO Switch Device Attributes +----------------------------------- + +RapidIO switches have additional attributes in sysfs. RapidIO subsystem supports +common and device-specific sysfs attributes for switches. Because switches are +integrated into the RapidIO subsystem, it offers a method to create +device-specific sysfs attributes by specifying a callback function that may be +set by the switch initialization routine during enumeration or discovery process. + +4.1 Common Switch Attributes + + routes - reports switch routing information in "destID port" format. This + attribute reports only valid routing table entries, one line for + each entry. + destid - device destination ID that defines a route to the switch + hopcount - number of hops on the path to the switch + lnext - returns names of devices linked to the switch except one of a device + linked to the ingress port (reported as "lprev"). This is an array + names with number of lines equal to number of ports in switch. If + a switch port has no attached device, returns "null" instead of + a device name. + +4.2 Device-specific Switch Attributes + +Device-specific switch attributes are listed for each RapidIO switch driver +that exports additional attributes. + +IDT_GEN2: + errlog - reads contents of device error log until it is empty. + + +5. RapidIO Bus Attributes +------------------------- + +RapidIO bus subdirectory /sys/bus/rapidio implements the following bus-specific +attribute: + + scan - allows to trigger enumeration discovery process from user space. This + is a write-only attribute. To initiate an enumeration or discovery + process on specific mport device, a user needs to write mport_ID (not + RapidIO destination ID) into this file. The mport_ID is a sequential + number (0 ... RIO_MAX_MPORTS) assigned to the mport device. + For example, for a machine with a single RapidIO controller, mport_ID + for that controller always will be 0. + To initiate RapidIO enumeration/discovery on all available mports + a user must write '-1' (or RIO_MPORT_ANY) into this attribute file. + + +6. RapidIO Bus Controllers/Ports +-------------------------------- + +On-chip RapidIO controllers and PCIe-to-RapidIO bridges (referenced as +"Master Port" or "mport") are presented in sysfs as the special class of +devices: "rapidio_port". + +The /sys/class/rapidio_port subdirectory contains individual subdirectories +named as "rapidioN" where N = mport ID registered with RapidIO subsystem. + +NOTE: An mport ID is not a RapidIO destination ID assigned to a given local +mport device. + +Each mport device subdirectory in addition to standard entries contains the +following device-specific attributes: + + port_destid - reports RapidIO destination ID assigned to the given RapidIO + mport device. If value 0xFFFFFFFF is returned this means that + no valid destination ID have been assigned to the mport (yet). + Normally, before enumeration/discovery have been executed only + fabric enumerating mports have a valid destination ID assigned + to them using "hdid=..." rapidio module parameter. + sys_size - reports RapidIO common transport system size: + 0 = small (8-bit destination ID, max. 256 devices), + 1 = large (16-bit destination ID, max. 65536 devices). + +After enumeration or discovery was performed for a given mport device, +the corresponding subdirectory will also contain subdirectories for each +child RapidIO device connected to the mport. Naming conventions for RapidIO +devices are described in Section 1 above. + +The example below shows mport device subdirectory with several child RapidIO +devices attached to it. + +[rio@rapidio ~]$ ls /sys/class/rapidio_port/rapidio0/ -l +total 0 +drwxr-xr-x 3 root root 0 Feb 11 15:10 00:e:0001 +drwxr-xr-x 3 root root 0 Feb 11 15:10 00:e:0004 +drwxr-xr-x 3 root root 0 Feb 11 15:10 00:e:0007 +drwxr-xr-x 3 root root 0 Feb 11 15:10 00:s:0002 +drwxr-xr-x 3 root root 0 Feb 11 15:10 00:s:0003 +drwxr-xr-x 3 root root 0 Feb 11 15:10 00:s:0005 +lrwxrwxrwx 1 root root 0 Feb 11 15:11 device -> ../../../0000:01:00.0 +-r--r--r-- 1 root root 4096 Feb 11 15:11 port_destid +drwxr-xr-x 2 root root 0 Feb 11 15:11 power +lrwxrwxrwx 1 root root 0 Feb 11 15:04 subsystem -> ../../../../../../class/rapidio_port +-r--r--r-- 1 root root 4096 Feb 11 15:11 sys_size +-rw-r--r-- 1 root root 4096 Feb 11 15:04 uevent diff --git a/kernel/Documentation/rapidio/tsi721.txt b/kernel/Documentation/rapidio/tsi721.txt new file mode 100644 index 000000000..626052f40 --- /dev/null +++ b/kernel/Documentation/rapidio/tsi721.txt @@ -0,0 +1,62 @@ +RapidIO subsystem mport driver for IDT Tsi721 PCI Express-to-SRIO bridge. +========================================================================= + +I. 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). + +II. Known problems + + None. + +III. 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). + +IV. 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. + +V. 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. |