Commit | Line | Data |
---|---|---|
b6e8d4aa AB |
1 | RapidIO subsystem Channelized Messaging character device driver (rio_cm.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, Prodrive Technologies, | |
14 | Nokia Networks, BAE and IDT. Additional input was received from other members | |
15 | of RapidIO.org. | |
16 | ||
17 | The objective was to create a character mode driver interface which exposes | |
18 | messaging capabilities of RapidIO endpoint devices (mports) directly | |
19 | to applications, in a manner that allows the numerous and varied RapidIO | |
20 | implementations to interoperate. | |
21 | ||
22 | This driver (RIO_CM) provides to user-space applications shared access to | |
23 | RapidIO mailbox messaging resources. | |
24 | ||
25 | RapidIO specification (Part 2) defines that endpoint devices may have up to four | |
26 | messaging mailboxes in case of multi-packet message (up to 4KB) and | |
27 | up to 64 mailboxes if single-packet messages (up to 256 B) are used. In addition | |
28 | to protocol definition limitations, a particular hardware implementation can | |
29 | have reduced number of messaging mailboxes. RapidIO aware applications must | |
30 | therefore share the messaging resources of a RapidIO endpoint. | |
31 | ||
32 | Main purpose of this device driver is to provide RapidIO mailbox messaging | |
33 | capability to large number of user-space processes by introducing socket-like | |
34 | operations using a single messaging mailbox. This allows applications to | |
35 | use the limited RapidIO messaging hardware resources efficiently. | |
36 | ||
37 | Most of device driver's operations are supported through 'ioctl' system calls. | |
38 | ||
39 | When loaded this device driver creates a single file system node named rio_cm | |
40 | in /dev directory common for all registered RapidIO mport devices. | |
41 | ||
42 | Following ioctl commands are available to user-space applications: | |
43 | ||
44 | - RIO_CM_MPORT_GET_LIST : Returns to caller list of local mport devices that | |
45 | support messaging operations (number of entries up to RIO_MAX_MPORTS). | |
46 | Each list entry is combination of mport's index in the system and RapidIO | |
47 | destination ID assigned to the port. | |
48 | - RIO_CM_EP_GET_LIST_SIZE : Returns number of messaging capable remote endpoints | |
49 | in a RapidIO network associated with the specified mport device. | |
50 | - RIO_CM_EP_GET_LIST : Returns list of RapidIO destination IDs for messaging | |
51 | capable remote endpoints (peers) available in a RapidIO network associated | |
52 | with the specified mport device. | |
53 | - RIO_CM_CHAN_CREATE : Creates RapidIO message exchange channel data structure | |
54 | with channel ID assigned automatically or as requested by a caller. | |
55 | - RIO_CM_CHAN_BIND : Binds the specified channel data structure to the specified | |
56 | mport device. | |
57 | - RIO_CM_CHAN_LISTEN : Enables listening for connection requests on the specified | |
58 | channel. | |
59 | - RIO_CM_CHAN_ACCEPT : Accepts a connection request from peer on the specified | |
60 | channel. If wait timeout for this request is specified by a caller it is | |
61 | a blocking call. If timeout set to 0 this is non-blocking call - ioctl | |
62 | handler checks for a pending connection request and if one is not available | |
63 | exits with -EGAIN error status immediately. | |
64 | - RIO_CM_CHAN_CONNECT : Sends a connection request to a remote peer/channel. | |
65 | - RIO_CM_CHAN_SEND : Sends a data message through the specified channel. | |
66 | The handler for this request assumes that message buffer specified by | |
67 | a caller includes the reserved space for a packet header required by | |
68 | this driver. | |
69 | - RIO_CM_CHAN_RECEIVE : Receives a data message through a connected channel. | |
70 | If the channel does not have an incoming message ready to return this ioctl | |
71 | handler will wait for new message until timeout specified by a caller | |
72 | expires. If timeout value is set to 0, ioctl handler uses a default value | |
73 | defined by MAX_SCHEDULE_TIMEOUT. | |
74 | - RIO_CM_CHAN_CLOSE : Closes a specified channel and frees associated buffers. | |
75 | If the specified channel is in the CONNECTED state, sends close notification | |
76 | to the remote peer. | |
77 | ||
78 | The ioctl command codes and corresponding data structures intended for use by | |
79 | user-space applications are defined in 'include/uapi/linux/rio_cm_cdev.h'. | |
80 | ||
81 | II. Hardware Compatibility | |
82 | ||
83 | This device driver uses standard interfaces defined by kernel RapidIO subsystem | |
84 | and therefore it can be used with any mport device driver registered by RapidIO | |
85 | subsystem with limitations set by available mport HW implementation of messaging | |
86 | mailboxes. | |
87 | ||
88 | III. Module parameters | |
89 | ||
90 | - 'dbg_level' - This parameter allows to control amount of debug information | |
91 | generated by this device driver. This parameter is formed by set of | |
92 | bit masks that correspond to the specific functional block. | |
93 | For mask definitions see 'drivers/rapidio/devices/rio_cm.c' | |
94 | This parameter can be changed dynamically. | |
95 | Use CONFIG_RAPIDIO_DEBUG=y to enable debug output at the top level. | |
96 | ||
97 | - 'cmbox' - Number of RapidIO mailbox to use (default value is 1). | |
98 | This parameter allows to set messaging mailbox number that will be used | |
99 | within entire RapidIO network. It can be used when default mailbox is | |
100 | used by other device drivers or is not supported by some nodes in the | |
101 | RapidIO network. | |
102 | ||
103 | - 'chstart' - Start channel number for dynamic assignment. Default value - 256. | |
104 | Allows to exclude channel numbers below this parameter from dynamic | |
105 | allocation to avoid conflicts with software components that use | |
106 | reserved predefined channel numbers. | |
107 | ||
108 | IV. Known problems | |
109 | ||
110 | None. | |
111 | ||
112 | V. User-space Applications and API Library | |
113 | ||
114 | Messaging API library and applications that use this device driver are available | |
115 | from RapidIO.org. | |
116 | ||
117 | VI. TODO List | |
118 | ||
119 | - Add support for system notification messages (reserved channel 0). |