About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / rapidio / mport_cdev.txt


Based on kernel version 4.16.1. Page generated on 2018-04-09 11:53 EST.

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	- 'dma_timeout' - DMA transfer completion timeout (in msec, default value 3000).
84	        This parameter set a maximum completion wait time for SYNC mode DMA
85	        transfer requests and for RIO_WAIT_FOR_ASYNC ioctl requests.
86	
87	- 'dbg_level' - 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	
94	IV. Known problems
95	
96	  None.
97	
98	V. User-space Applications and API
99	
100	API library and applications that use this device driver are available from
101	RapidIO.org.
102	
103	VI. TODO List
104	
105	- Add support for sending/receiving "raw" RapidIO messaging packets.
106	- Add memory mapped DMA data transfers as an option when RapidIO-specific DMA
107	  is not available.
Hide Line Numbers


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog