diff options
Diffstat (limited to 'Documentation/rapidio/rapidio.txt')
| -rw-r--r-- | Documentation/rapidio/rapidio.txt | 351 |
1 files changed, 0 insertions, 351 deletions
diff --git a/Documentation/rapidio/rapidio.txt b/Documentation/rapidio/rapidio.txt deleted file mode 100644 index 28fbd877f85a..000000000000 --- a/Documentation/rapidio/rapidio.txt +++ /dev/null @@ -1,351 +0,0 @@ - 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 |