Commit | Line | Data |
---|---|---|
e8de3701 AB |
1 | RapidIO subsystem mport character device driver (rio_mport_cdev.c) |
2 | ================================================================== | |
3 | ||
4 | Version History: | |
5 | ---------------- | |
6 | 1.0.0 - Initial driver release. | |
7 | ||
8 | ================================================================== | |
9 | ||
10 | I. Overview | |
11 | ||
12 | This device driver is the result of collaboration within the RapidIO.org | |
13 | Software Task Group (STG) between Texas Instruments, Freescale, | |
14 | Prodrive Technologies, Nokia Networks, BAE and IDT. Additional input was | |
15 | received from other members of RapidIO.org. The objective was to create a | |
16 | character mode driver interface which exposes the capabilities of RapidIO | |
17 | devices directly to applications, in a manner that allows the numerous and | |
18 | varied RapidIO implementations to interoperate. | |
19 | ||
20 | This driver (MPORT_CDEV) provides access to basic RapidIO subsystem operations | |
21 | for user-space applications. Most of RapidIO operations are supported through | |
22 | 'ioctl' system calls. | |
23 | ||
24 | When loaded this device driver creates filesystem nodes named rio_mportX in /dev | |
25 | directory for each registered RapidIO mport device. 'X' in the node name matches | |
26 | to unique port ID assigned to each local mport device. | |
27 | ||
28 | Using available set of ioctl commands user-space applications can perform | |
29 | following RapidIO bus and subsystem operations: | |
30 | ||
31 | - Reads and writes from/to configuration registers of mport devices | |
32 | (RIO_MPORT_MAINT_READ_LOCAL/RIO_MPORT_MAINT_WRITE_LOCAL) | |
33 | - Reads and writes from/to configuration registers of remote RapidIO devices. | |
34 | This operations are defined as RapidIO Maintenance reads/writes in RIO spec. | |
35 | (RIO_MPORT_MAINT_READ_REMOTE/RIO_MPORT_MAINT_WRITE_REMOTE) | |
36 | - Set RapidIO Destination ID for mport devices (RIO_MPORT_MAINT_HDID_SET) | |
37 | - Set RapidIO Component Tag for mport devices (RIO_MPORT_MAINT_COMPTAG_SET) | |
38 | - Query logical index of mport devices (RIO_MPORT_MAINT_PORT_IDX_GET) | |
39 | - Query capabilities and RapidIO link configuration of mport devices | |
40 | (RIO_MPORT_GET_PROPERTIES) | |
41 | - Enable/Disable reporting of RapidIO doorbell events to user-space applications | |
42 | (RIO_ENABLE_DOORBELL_RANGE/RIO_DISABLE_DOORBELL_RANGE) | |
43 | - Enable/Disable reporting of RIO port-write events to user-space applications | |
44 | (RIO_ENABLE_PORTWRITE_RANGE/RIO_DISABLE_PORTWRITE_RANGE) | |
45 | - Query/Control type of events reported through this driver: doorbells, | |
46 | port-writes or both (RIO_SET_EVENT_MASK/RIO_GET_EVENT_MASK) | |
47 | - Configure/Map mport's outbound requests window(s) for specific size, | |
48 | RapidIO destination ID, hopcount and request type | |
49 | (RIO_MAP_OUTBOUND/RIO_UNMAP_OUTBOUND) | |
50 | - Configure/Map mport's inbound requests window(s) for specific size, | |
51 | RapidIO base address and local memory base address | |
52 | (RIO_MAP_INBOUND/RIO_UNMAP_INBOUND) | |
53 | - Allocate/Free contiguous DMA coherent memory buffer for DMA data transfers | |
54 | to/from remote RapidIO devices (RIO_ALLOC_DMA/RIO_FREE_DMA) | |
55 | - Initiate DMA data transfers to/from remote RapidIO devices (RIO_TRANSFER). | |
56 | Supports blocking, asynchronous and posted (a.k.a 'fire-and-forget') data | |
57 | transfer modes. | |
58 | - Check/Wait for completion of asynchronous DMA data transfer | |
59 | (RIO_WAIT_FOR_ASYNC) | |
60 | - Manage device objects supported by RapidIO subsystem (RIO_DEV_ADD/RIO_DEV_DEL). | |
61 | This allows implementation of various RapidIO fabric enumeration algorithms | |
62 | as user-space applications while using remaining functionality provided by | |
63 | kernel RapidIO subsystem. | |
64 | ||
65 | II. Hardware Compatibility | |
66 | ||
67 | This device driver uses standard interfaces defined by kernel RapidIO subsystem | |
68 | and therefore it can be used with any mport device driver registered by RapidIO | |
69 | subsystem with limitations set by available mport implementation. | |
70 | ||
71 | At this moment the most common limitation is availability of RapidIO-specific | |
72 | DMA engine framework for specific mport device. Users should verify available | |
73 | functionality of their platform when planning to use this driver: | |
74 | ||
75 | - IDT Tsi721 PCIe-to-RapidIO bridge device and its mport device driver are fully | |
76 | compatible with this driver. | |
77 | - Freescale SoCs 'fsl_rio' mport driver does not have implementation for RapidIO | |
78 | specific DMA engine support and therefore DMA data transfers mport_cdev driver | |
79 | are not available. | |
80 | ||
81 | III. Module parameters | |
82 | ||
83 | - 'dbg_level' - This parameter allows to control amount of debug information | |
84 | generated by this device driver. This parameter is formed by set of | |
85 | This parameter can be changed bit masks that correspond to the specific | |
86 | functional block. | |
87 | For mask definitions see 'drivers/rapidio/devices/rio_mport_cdev.c' | |
88 | This parameter can be changed dynamically. | |
89 | Use CONFIG_RAPIDIO_DEBUG=y to enable debug output at the top level. | |
90 | ||
91 | IV. Known problems | |
92 | ||
93 | None. | |
94 | ||
95 | V. User-space Applications and API | |
96 | ||
97 | API library and applications that use this device driver are available from | |
98 | RapidIO.org. | |
99 | ||
100 | VI. TODO List | |
101 | ||
102 | - Add support for sending/receiving "raw" RapidIO messaging packets. | |
103 | - Add memory mapped DMA data transfers as an option when RapidIO-specific DMA | |
104 | is not available. |