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