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