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