From d2bdd48a652bd0f7a5c78f3e418b4529fc469e1f Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 18 Jun 2019 16:03:23 -0300 Subject: docs: rapidio: add it to the driver API 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 --- Documentation/admin-guide/index.rst | 1 + Documentation/admin-guide/rapidio.rst | 107 +++++++ Documentation/driver-api/index.rst | 2 +- Documentation/driver-api/rapidio.rst | 107 ------- Documentation/driver-api/rapidio/index.rst | 13 + Documentation/driver-api/rapidio/mport_cdev.rst | 110 +++++++ Documentation/driver-api/rapidio/rapidio.rst | 362 ++++++++++++++++++++++++ Documentation/driver-api/rapidio/rio_cm.rst | 135 +++++++++ Documentation/driver-api/rapidio/sysfs.rst | 7 + Documentation/driver-api/rapidio/tsi721.rst | 112 ++++++++ Documentation/rapidio/index.rst | 15 - Documentation/rapidio/mport_cdev.rst | 110 ------- Documentation/rapidio/rapidio.rst | 362 ------------------------ Documentation/rapidio/rio_cm.rst | 135 --------- Documentation/rapidio/sysfs.rst | 7 - Documentation/rapidio/tsi721.rst | 112 -------- drivers/rapidio/Kconfig | 2 +- 17 files changed, 849 insertions(+), 850 deletions(-) create mode 100644 Documentation/admin-guide/rapidio.rst delete mode 100644 Documentation/driver-api/rapidio.rst create mode 100644 Documentation/driver-api/rapidio/index.rst create mode 100644 Documentation/driver-api/rapidio/mport_cdev.rst create mode 100644 Documentation/driver-api/rapidio/rapidio.rst create mode 100644 Documentation/driver-api/rapidio/rio_cm.rst create mode 100644 Documentation/driver-api/rapidio/sysfs.rst create mode 100644 Documentation/driver-api/rapidio/tsi721.rst delete mode 100644 Documentation/rapidio/index.rst delete mode 100644 Documentation/rapidio/mport_cdev.rst delete mode 100644 Documentation/rapidio/rapidio.rst delete mode 100644 Documentation/rapidio/rio_cm.rst delete mode 100644 Documentation/rapidio/sysfs.rst delete mode 100644 Documentation/rapidio/tsi721.rst diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst index 24fbe0568eff..8853c95ef0d4 100644 --- a/Documentation/admin-guide/index.rst +++ b/Documentation/admin-guide/index.rst @@ -61,6 +61,7 @@ configure specific aspects of kernel behavior to your liking. parport md module-signing + rapidio sysrq unicode vga-softcursor diff --git a/Documentation/admin-guide/rapidio.rst b/Documentation/admin-guide/rapidio.rst new file mode 100644 index 000000000000..71ff658ab78e --- /dev/null +++ b/Documentation/admin-guide/rapidio.rst @@ -0,0 +1,107 @@ +======================= +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 diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index 6cd750a03ea0..d665cd9ab95f 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -45,7 +45,7 @@ available subsections can be seen below. miscellaneous mei/index w1 - rapidio + rapidio/index s390-drivers vme 80211/index diff --git a/Documentation/driver-api/rapidio.rst b/Documentation/driver-api/rapidio.rst deleted file mode 100644 index 71ff658ab78e..000000000000 --- a/Documentation/driver-api/rapidio.rst +++ /dev/null @@ -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 diff --git a/Documentation/driver-api/rapidio/index.rst b/Documentation/driver-api/rapidio/index.rst new file mode 100644 index 000000000000..4c5e51a05134 --- /dev/null +++ b/Documentation/driver-api/rapidio/index.rst @@ -0,0 +1,13 @@ +=========================== +The Linux RapidIO Subsystem +=========================== + +.. toctree:: + :maxdepth: 1 + + rapidio + sysfs + + tsi721 + mport_cdev + rio_cm diff --git a/Documentation/driver-api/rapidio/mport_cdev.rst b/Documentation/driver-api/rapidio/mport_cdev.rst new file mode 100644 index 000000000000..df77a7f7be7d --- /dev/null +++ b/Documentation/driver-api/rapidio/mport_cdev.rst @@ -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. diff --git a/Documentation/driver-api/rapidio/rapidio.rst b/Documentation/driver-api/rapidio/rapidio.rst new file mode 100644 index 000000000000..fb8942d3ba85 --- /dev/null +++ b/Documentation/driver-api/rapidio/rapidio.rst @@ -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 diff --git a/Documentation/driver-api/rapidio/rio_cm.rst b/Documentation/driver-api/rapidio/rio_cm.rst new file mode 100644 index 000000000000..5294430a7a74 --- /dev/null +++ b/Documentation/driver-api/rapidio/rio_cm.rst @@ -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). diff --git a/Documentation/driver-api/rapidio/sysfs.rst b/Documentation/driver-api/rapidio/sysfs.rst new file mode 100644 index 000000000000..540f72683496 --- /dev/null +++ b/Documentation/driver-api/rapidio/sysfs.rst @@ -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 diff --git a/Documentation/driver-api/rapidio/tsi721.rst b/Documentation/driver-api/rapidio/tsi721.rst new file mode 100644 index 000000000000..42aea438cd20 --- /dev/null +++ b/Documentation/driver-api/rapidio/tsi721.rst @@ -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. diff --git a/Documentation/rapidio/index.rst b/Documentation/rapidio/index.rst deleted file mode 100644 index ab7b5541b346..000000000000 --- a/Documentation/rapidio/index.rst +++ /dev/null @@ -1,15 +0,0 @@ -:orphan: - -=========================== -The Linux RapidIO Subsystem -=========================== - -.. toctree:: - :maxdepth: 1 - - rapidio - sysfs - - tsi721 - mport_cdev - rio_cm diff --git a/Documentation/rapidio/mport_cdev.rst b/Documentation/rapidio/mport_cdev.rst deleted file mode 100644 index df77a7f7be7d..000000000000 --- a/Documentation/rapidio/mport_cdev.rst +++ /dev/null @@ -1,110 +0,0 @@ -================================================================== -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. diff --git a/Documentation/rapidio/rapidio.rst b/Documentation/rapidio/rapidio.rst deleted file mode 100644 index fb8942d3ba85..000000000000 --- a/Documentation/rapidio/rapidio.rst +++ /dev/null @@ -1,362 +0,0 @@ -============ -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 diff --git a/Documentation/rapidio/rio_cm.rst b/Documentation/rapidio/rio_cm.rst deleted file mode 100644 index 5294430a7a74..000000000000 --- a/Documentation/rapidio/rio_cm.rst +++ /dev/null @@ -1,135 +0,0 @@ -========================================================================== -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). diff --git a/Documentation/rapidio/sysfs.rst b/Documentation/rapidio/sysfs.rst deleted file mode 100644 index 540f72683496..000000000000 --- a/Documentation/rapidio/sysfs.rst +++ /dev/null @@ -1,7 +0,0 @@ -============= -Sysfs entries -============= - -The RapidIO sysfs files have moved to: -Documentation/ABI/testing/sysfs-bus-rapidio and -Documentation/ABI/testing/sysfs-class-rapidio diff --git a/Documentation/rapidio/tsi721.rst b/Documentation/rapidio/tsi721.rst deleted file mode 100644 index 42aea438cd20..000000000000 --- a/Documentation/rapidio/tsi721.rst +++ /dev/null @@ -1,112 +0,0 @@ -========================================================================= -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. diff --git a/drivers/rapidio/Kconfig b/drivers/rapidio/Kconfig index 467e8fa06904..677d1aff61b7 100644 --- a/drivers/rapidio/Kconfig +++ b/drivers/rapidio/Kconfig @@ -86,7 +86,7 @@ config RAPIDIO_CHMAN This option includes RapidIO channelized messaging driver which provides socket-like interface to allow sharing of single RapidIO messaging mailbox between multiple user-space applications. - See "Documentation/rapidio/rio_cm.rst" for driver description. + See "Documentation/driver-api/rapidio/rio_cm.rst" for driver description. config RAPIDIO_MPORT_CDEV tristate "RapidIO /dev mport device driver" -- cgit v1.2.3