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