xref: /openbmc/linux/Documentation/driver-api/rapidio/rio_cm.rst (revision 0898782247ae533d1f4e47a06bc5d4870931b284)
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