|
| 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. |
0 commit comments