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