Mauro Carvalho Chehab | e0ae154 | 2019-04-18 16:49:39 -0300 | [diff] [blame] | 1 | ========================================================================== |
Alexandre Bounine | b6e8d4a | 2016-08-02 14:06:25 -0700 | [diff] [blame] | 2 | RapidIO subsystem Channelized Messaging character device driver (rio_cm.c) |
| 3 | ========================================================================== |
| 4 | |
Alexandre Bounine | b6e8d4a | 2016-08-02 14:06:25 -0700 | [diff] [blame] | 5 | |
Mauro Carvalho Chehab | e0ae154 | 2019-04-18 16:49:39 -0300 | [diff] [blame] | 6 | 1. Overview |
| 7 | =========== |
Alexandre Bounine | b6e8d4a | 2016-08-02 14:06:25 -0700 | [diff] [blame] | 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 | |
Mauro Carvalho Chehab | e0ae154 | 2019-04-18 16:49:39 -0300 | [diff] [blame] | 41 | - RIO_CM_MPORT_GET_LIST: |
| 42 | Returns to caller list of local mport devices that |
Alexandre Bounine | b6e8d4a | 2016-08-02 14:06:25 -0700 | [diff] [blame] | 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. |
Mauro Carvalho Chehab | e0ae154 | 2019-04-18 16:49:39 -0300 | [diff] [blame] | 46 | - RIO_CM_EP_GET_LIST_SIZE: |
| 47 | Returns number of messaging capable remote endpoints |
Alexandre Bounine | b6e8d4a | 2016-08-02 14:06:25 -0700 | [diff] [blame] | 48 | in a RapidIO network associated with the specified mport device. |
Mauro Carvalho Chehab | e0ae154 | 2019-04-18 16:49:39 -0300 | [diff] [blame] | 49 | - RIO_CM_EP_GET_LIST: |
| 50 | Returns list of RapidIO destination IDs for messaging |
Alexandre Bounine | b6e8d4a | 2016-08-02 14:06:25 -0700 | [diff] [blame] | 51 | capable remote endpoints (peers) available in a RapidIO network associated |
| 52 | with the specified mport device. |
Mauro Carvalho Chehab | e0ae154 | 2019-04-18 16:49:39 -0300 | [diff] [blame] | 53 | - RIO_CM_CHAN_CREATE: |
| 54 | Creates RapidIO message exchange channel data structure |
Alexandre Bounine | b6e8d4a | 2016-08-02 14:06:25 -0700 | [diff] [blame] | 55 | with channel ID assigned automatically or as requested by a caller. |
Mauro Carvalho Chehab | e0ae154 | 2019-04-18 16:49:39 -0300 | [diff] [blame] | 56 | - RIO_CM_CHAN_BIND: |
| 57 | Binds the specified channel data structure to the specified |
Alexandre Bounine | b6e8d4a | 2016-08-02 14:06:25 -0700 | [diff] [blame] | 58 | mport device. |
Mauro Carvalho Chehab | e0ae154 | 2019-04-18 16:49:39 -0300 | [diff] [blame] | 59 | - RIO_CM_CHAN_LISTEN: |
| 60 | Enables listening for connection requests on the specified |
Alexandre Bounine | b6e8d4a | 2016-08-02 14:06:25 -0700 | [diff] [blame] | 61 | channel. |
Mauro Carvalho Chehab | e0ae154 | 2019-04-18 16:49:39 -0300 | [diff] [blame] | 62 | - RIO_CM_CHAN_ACCEPT: |
| 63 | Accepts a connection request from peer on the specified |
Alexandre Bounine | b6e8d4a | 2016-08-02 14:06:25 -0700 | [diff] [blame] | 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. |
Mauro Carvalho Chehab | e0ae154 | 2019-04-18 16:49:39 -0300 | [diff] [blame] | 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. |
Alexandre Bounine | b6e8d4a | 2016-08-02 14:06:25 -0700 | [diff] [blame] | 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. |
Mauro Carvalho Chehab | e0ae154 | 2019-04-18 16:49:39 -0300 | [diff] [blame] | 75 | - RIO_CM_CHAN_RECEIVE: |
| 76 | Receives a data message through a connected channel. |
Alexandre Bounine | b6e8d4a | 2016-08-02 14:06:25 -0700 | [diff] [blame] | 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. |
Mauro Carvalho Chehab | e0ae154 | 2019-04-18 16:49:39 -0300 | [diff] [blame] | 81 | - RIO_CM_CHAN_CLOSE: |
| 82 | Closes a specified channel and frees associated buffers. |
Alexandre Bounine | b6e8d4a | 2016-08-02 14:06:25 -0700 | [diff] [blame] | 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 | |
Mauro Carvalho Chehab | e0ae154 | 2019-04-18 16:49:39 -0300 | [diff] [blame] | 89 | 2. Hardware Compatibility |
| 90 | ========================= |
Alexandre Bounine | b6e8d4a | 2016-08-02 14:06:25 -0700 | [diff] [blame] | 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 | |
Mauro Carvalho Chehab | e0ae154 | 2019-04-18 16:49:39 -0300 | [diff] [blame] | 97 | 3. Module parameters |
| 98 | ==================== |
Alexandre Bounine | b6e8d4a | 2016-08-02 14:06:25 -0700 | [diff] [blame] | 99 | |
Mauro Carvalho Chehab | e0ae154 | 2019-04-18 16:49:39 -0300 | [diff] [blame] | 100 | - 'dbg_level' |
| 101 | - This parameter allows to control amount of debug information |
Alexandre Bounine | b6e8d4a | 2016-08-02 14:06:25 -0700 | [diff] [blame] | 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 | |
Mauro Carvalho Chehab | e0ae154 | 2019-04-18 16:49:39 -0300 | [diff] [blame] | 108 | - 'cmbox' |
| 109 | - Number of RapidIO mailbox to use (default value is 1). |
Alexandre Bounine | b6e8d4a | 2016-08-02 14:06:25 -0700 | [diff] [blame] | 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 | |
Mauro Carvalho Chehab | e0ae154 | 2019-04-18 16:49:39 -0300 | [diff] [blame] | 115 | - 'chstart' |
| 116 | - Start channel number for dynamic assignment. Default value - 256. |
Alexandre Bounine | b6e8d4a | 2016-08-02 14:06:25 -0700 | [diff] [blame] | 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 | |
Mauro Carvalho Chehab | e0ae154 | 2019-04-18 16:49:39 -0300 | [diff] [blame] | 121 | 4. Known problems |
| 122 | ================= |
Alexandre Bounine | b6e8d4a | 2016-08-02 14:06:25 -0700 | [diff] [blame] | 123 | |
| 124 | None. |
| 125 | |
Mauro Carvalho Chehab | e0ae154 | 2019-04-18 16:49:39 -0300 | [diff] [blame] | 126 | 5. User-space Applications and API Library |
| 127 | ========================================== |
Alexandre Bounine | b6e8d4a | 2016-08-02 14:06:25 -0700 | [diff] [blame] | 128 | |
| 129 | Messaging API library and applications that use this device driver are available |
| 130 | from RapidIO.org. |
| 131 | |
Mauro Carvalho Chehab | e0ae154 | 2019-04-18 16:49:39 -0300 | [diff] [blame] | 132 | 6. TODO List |
| 133 | ============ |
Alexandre Bounine | b6e8d4a | 2016-08-02 14:06:25 -0700 | [diff] [blame] | 134 | |
| 135 | - Add support for system notification messages (reserved channel 0). |