0001 ==================================================================
0002 RapidIO subsystem mport character device driver (rio_mport_cdev.c)
0003 ==================================================================
0004
0005 1. Overview
0006 ===========
0007
0008 This device driver is the result of collaboration within the RapidIO.org
0009 Software Task Group (STG) between Texas Instruments, Freescale,
0010 Prodrive Technologies, Nokia Networks, BAE and IDT. Additional input was
0011 received from other members of RapidIO.org. The objective was to create a
0012 character mode driver interface which exposes the capabilities of RapidIO
0013 devices directly to applications, in a manner that allows the numerous and
0014 varied RapidIO implementations to interoperate.
0015
0016 This driver (MPORT_CDEV) provides access to basic RapidIO subsystem operations
0017 for user-space applications. Most of RapidIO operations are supported through
0018 'ioctl' system calls.
0019
0020 When loaded this device driver creates filesystem nodes named rio_mportX in /dev
0021 directory for each registered RapidIO mport device. 'X' in the node name matches
0022 to unique port ID assigned to each local mport device.
0023
0024 Using available set of ioctl commands user-space applications can perform
0025 following RapidIO bus and subsystem operations:
0026
0027 - Reads and writes from/to configuration registers of mport devices
0028 (RIO_MPORT_MAINT_READ_LOCAL/RIO_MPORT_MAINT_WRITE_LOCAL)
0029 - Reads and writes from/to configuration registers of remote RapidIO devices.
0030 This operations are defined as RapidIO Maintenance reads/writes in RIO spec.
0031 (RIO_MPORT_MAINT_READ_REMOTE/RIO_MPORT_MAINT_WRITE_REMOTE)
0032 - Set RapidIO Destination ID for mport devices (RIO_MPORT_MAINT_HDID_SET)
0033 - Set RapidIO Component Tag for mport devices (RIO_MPORT_MAINT_COMPTAG_SET)
0034 - Query logical index of mport devices (RIO_MPORT_MAINT_PORT_IDX_GET)
0035 - Query capabilities and RapidIO link configuration of mport devices
0036 (RIO_MPORT_GET_PROPERTIES)
0037 - Enable/Disable reporting of RapidIO doorbell events to user-space applications
0038 (RIO_ENABLE_DOORBELL_RANGE/RIO_DISABLE_DOORBELL_RANGE)
0039 - Enable/Disable reporting of RIO port-write events to user-space applications
0040 (RIO_ENABLE_PORTWRITE_RANGE/RIO_DISABLE_PORTWRITE_RANGE)
0041 - Query/Control type of events reported through this driver: doorbells,
0042 port-writes or both (RIO_SET_EVENT_MASK/RIO_GET_EVENT_MASK)
0043 - Configure/Map mport's outbound requests window(s) for specific size,
0044 RapidIO destination ID, hopcount and request type
0045 (RIO_MAP_OUTBOUND/RIO_UNMAP_OUTBOUND)
0046 - Configure/Map mport's inbound requests window(s) for specific size,
0047 RapidIO base address and local memory base address
0048 (RIO_MAP_INBOUND/RIO_UNMAP_INBOUND)
0049 - Allocate/Free contiguous DMA coherent memory buffer for DMA data transfers
0050 to/from remote RapidIO devices (RIO_ALLOC_DMA/RIO_FREE_DMA)
0051 - Initiate DMA data transfers to/from remote RapidIO devices (RIO_TRANSFER).
0052 Supports blocking, asynchronous and posted (a.k.a 'fire-and-forget') data
0053 transfer modes.
0054 - Check/Wait for completion of asynchronous DMA data transfer
0055 (RIO_WAIT_FOR_ASYNC)
0056 - Manage device objects supported by RapidIO subsystem (RIO_DEV_ADD/RIO_DEV_DEL).
0057 This allows implementation of various RapidIO fabric enumeration algorithms
0058 as user-space applications while using remaining functionality provided by
0059 kernel RapidIO subsystem.
0060
0061 2. Hardware Compatibility
0062 =========================
0063
0064 This device driver uses standard interfaces defined by kernel RapidIO subsystem
0065 and therefore it can be used with any mport device driver registered by RapidIO
0066 subsystem with limitations set by available mport implementation.
0067
0068 At this moment the most common limitation is availability of RapidIO-specific
0069 DMA engine framework for specific mport device. Users should verify available
0070 functionality of their platform when planning to use this driver:
0071
0072 - IDT Tsi721 PCIe-to-RapidIO bridge device and its mport device driver are fully
0073 compatible with this driver.
0074 - Freescale SoCs 'fsl_rio' mport driver does not have implementation for RapidIO
0075 specific DMA engine support and therefore DMA data transfers mport_cdev driver
0076 are not available.
0077
0078 3. Module parameters
0079 ====================
0080
0081 - 'dma_timeout'
0082 - DMA transfer completion timeout (in msec, default value 3000).
0083 This parameter set a maximum completion wait time for SYNC mode DMA
0084 transfer requests and for RIO_WAIT_FOR_ASYNC ioctl requests.
0085
0086 - 'dbg_level'
0087 - This parameter allows to control amount of debug information
0088 generated by this device driver. This parameter is formed by set of
0089 bit masks that correspond to the specific functional blocks.
0090 For mask definitions see 'drivers/rapidio/devices/rio_mport_cdev.c'
0091 This parameter can be changed dynamically.
0092 Use CONFIG_RAPIDIO_DEBUG=y to enable debug output at the top level.
0093
0094 4. Known problems
0095 =================
0096
0097 None.
0098
0099 5. User-space Applications and API
0100 ==================================
0101
0102 API library and applications that use this device driver are available from
0103 RapidIO.org.
0104
0105 6. TODO List
0106 ============
0107
0108 - Add support for sending/receiving "raw" RapidIO messaging packets.
0109 - Add memory mapped DMA data transfers as an option when RapidIO-specific DMA
0110 is not available.
