Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
docs: rapidio: convert to ReST
Rename the rapidio documentation files to ReST, add an
index for them and adjust in order to produce a nice html
output via the Sphinx build system.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
+141
-77
+15
Documentation/rapidio/index.rst
+15
Documentation/rapidio/index.rst
+25
-22
Documentation/rapidio/mport_cdev.txt
Documentation/rapidio/mport_cdev.rst
+25
-22
Documentation/rapidio/mport_cdev.txt
Documentation/rapidio/mport_cdev.rst
···
1
+
==================================================================
1
2
RapidIO subsystem mport character device driver (rio_mport_cdev.c)
2
3
==================================================================
3
4
4
-
Version History:
5
-
----------------
6
-
1.0.0 - Initial driver release.
7
-
8
-
==================================================================
9
-
10
-
I. Overview
5
+
1. Overview
6
+
===========
11
7
12
8
This device driver is the result of collaboration within the RapidIO.org
13
9
Software Task Group (STG) between Texas Instruments, Freescale,
···
25
29
following RapidIO bus and subsystem operations:
26
30
27
31
- Reads and writes from/to configuration registers of mport devices
28
-
(RIO_MPORT_MAINT_READ_LOCAL/RIO_MPORT_MAINT_WRITE_LOCAL)
32
+
(RIO_MPORT_MAINT_READ_LOCAL/RIO_MPORT_MAINT_WRITE_LOCAL)
29
33
- Reads and writes from/to configuration registers of remote RapidIO devices.
30
34
This operations are defined as RapidIO Maintenance reads/writes in RIO spec.
31
-
(RIO_MPORT_MAINT_READ_REMOTE/RIO_MPORT_MAINT_WRITE_REMOTE)
35
+
(RIO_MPORT_MAINT_READ_REMOTE/RIO_MPORT_MAINT_WRITE_REMOTE)
32
36
- Set RapidIO Destination ID for mport devices (RIO_MPORT_MAINT_HDID_SET)
33
37
- Set RapidIO Component Tag for mport devices (RIO_MPORT_MAINT_COMPTAG_SET)
34
38
- Query logical index of mport devices (RIO_MPORT_MAINT_PORT_IDX_GET)
35
39
- Query capabilities and RapidIO link configuration of mport devices
36
-
(RIO_MPORT_GET_PROPERTIES)
40
+
(RIO_MPORT_GET_PROPERTIES)
37
41
- Enable/Disable reporting of RapidIO doorbell events to user-space applications
38
-
(RIO_ENABLE_DOORBELL_RANGE/RIO_DISABLE_DOORBELL_RANGE)
42
+
(RIO_ENABLE_DOORBELL_RANGE/RIO_DISABLE_DOORBELL_RANGE)
39
43
- Enable/Disable reporting of RIO port-write events to user-space applications
40
-
(RIO_ENABLE_PORTWRITE_RANGE/RIO_DISABLE_PORTWRITE_RANGE)
44
+
(RIO_ENABLE_PORTWRITE_RANGE/RIO_DISABLE_PORTWRITE_RANGE)
41
45
- Query/Control type of events reported through this driver: doorbells,
42
46
port-writes or both (RIO_SET_EVENT_MASK/RIO_GET_EVENT_MASK)
43
47
- Configure/Map mport's outbound requests window(s) for specific size,
44
48
RapidIO destination ID, hopcount and request type
45
-
(RIO_MAP_OUTBOUND/RIO_UNMAP_OUTBOUND)
49
+
(RIO_MAP_OUTBOUND/RIO_UNMAP_OUTBOUND)
46
50
- Configure/Map mport's inbound requests window(s) for specific size,
47
51
RapidIO base address and local memory base address
48
-
(RIO_MAP_INBOUND/RIO_UNMAP_INBOUND)
52
+
(RIO_MAP_INBOUND/RIO_UNMAP_INBOUND)
49
53
- Allocate/Free contiguous DMA coherent memory buffer for DMA data transfers
50
54
to/from remote RapidIO devices (RIO_ALLOC_DMA/RIO_FREE_DMA)
51
55
- Initiate DMA data transfers to/from remote RapidIO devices (RIO_TRANSFER).
52
56
Supports blocking, asynchronous and posted (a.k.a 'fire-and-forget') data
53
57
transfer modes.
54
58
- Check/Wait for completion of asynchronous DMA data transfer
55
-
(RIO_WAIT_FOR_ASYNC)
59
+
(RIO_WAIT_FOR_ASYNC)
56
60
- Manage device objects supported by RapidIO subsystem (RIO_DEV_ADD/RIO_DEV_DEL).
57
61
This allows implementation of various RapidIO fabric enumeration algorithms
58
62
as user-space applications while using remaining functionality provided by
59
63
kernel RapidIO subsystem.
60
64
61
-
II. Hardware Compatibility
65
+
2. Hardware Compatibility
66
+
=========================
62
67
63
68
This device driver uses standard interfaces defined by kernel RapidIO subsystem
64
69
and therefore it can be used with any mport device driver registered by RapidIO
···
75
78
specific DMA engine support and therefore DMA data transfers mport_cdev driver
76
79
are not available.
77
80
78
-
III. Module parameters
81
+
3. Module parameters
82
+
====================
79
83
80
-
- 'dma_timeout' - DMA transfer completion timeout (in msec, default value 3000).
84
+
- 'dma_timeout'
85
+
- DMA transfer completion timeout (in msec, default value 3000).
81
86
This parameter set a maximum completion wait time for SYNC mode DMA
82
87
transfer requests and for RIO_WAIT_FOR_ASYNC ioctl requests.
83
88
84
-
- 'dbg_level' - This parameter allows to control amount of debug information
89
+
- 'dbg_level'
90
+
- This parameter allows to control amount of debug information
85
91
generated by this device driver. This parameter is formed by set of
86
92
bit masks that correspond to the specific functional blocks.
87
93
For mask definitions see 'drivers/rapidio/devices/rio_mport_cdev.c'
88
94
This parameter can be changed dynamically.
89
95
Use CONFIG_RAPIDIO_DEBUG=y to enable debug output at the top level.
90
96
91
-
IV. Known problems
97
+
4. Known problems
98
+
=================
92
99
93
100
None.
94
101
95
-
V. User-space Applications and API
102
+
5. User-space Applications and API
103
+
==================================
96
104
97
105
API library and applications that use this device driver are available from
98
106
RapidIO.org.
99
107
100
-
VI. TODO List
108
+
6. TODO List
109
+
============
101
110
102
111
- Add support for sending/receiving "raw" RapidIO messaging packets.
103
112
- Add memory mapped DMA data transfers as an option when RapidIO-specific DMA
+25
-14
Documentation/rapidio/rapidio.txt
Documentation/rapidio/rapidio.rst
+25
-14
Documentation/rapidio/rapidio.txt
Documentation/rapidio/rapidio.rst
···
1
-
The Linux RapidIO Subsystem
2
-
3
-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1
+
============
2
+
Introduction
3
+
============
4
4
5
5
The RapidIO standard is a packet-based fabric interconnect standard designed for
6
6
use in embedded systems. Development of the RapidIO standard is directed by the
···
11
11
information on its major components.
12
12
13
13
1 Overview
14
-
----------
14
+
==========
15
15
16
16
Because the RapidIO subsystem follows the Linux device model it is integrated
17
17
into the kernel similarly to other buses by defining RapidIO-specific device and
···
22
22
subsystem operations.
23
23
24
24
2. Core Components
25
-
------------------
25
+
==================
26
26
27
27
A typical RapidIO network is a combination of endpoints and switches.
28
28
Each of these components is represented in the subsystem by an associated data
···
30
30
in include/linux/rio.h file.
31
31
32
32
2.1 Master Port
33
+
---------------
33
34
34
35
A master port (or mport) is a RapidIO interface controller that is local to the
35
36
processor executing the Linux code. A master port generates and receives RapidIO
···
47
46
implementations of RapidIO functions.
48
47
49
48
2.2 Device
49
+
----------
50
50
51
51
A RapidIO device is any endpoint (other than mport) or switch in the network.
52
52
All devices are presented in the RapidIO subsystem by corresponding rio_dev data
···
55
53
(depending on number of available mports and networks).
56
54
57
55
2.3 Switch
56
+
----------
58
57
59
58
A RapidIO switch is a special class of device that routes packets between its
60
59
ports towards their final destination. The packet destination port within a
···
69
66
implementation of common switch management routines.
70
67
71
68
2.4 Network
69
+
-----------
72
70
73
71
A RapidIO network is a combination of interconnected endpoint and switch devices.
74
72
Each RapidIO network known to the system is represented by corresponding rio_net
···
78
74
master port that is used to communicate with devices within the network.
79
75
80
76
2.5 Device Drivers
77
+
------------------
81
78
82
79
RapidIO device-specific drivers follow Linux Kernel Driver Model and are
83
80
intended to support specific RapidIO devices attached to the RapidIO network.
84
81
85
82
2.6 Subsystem Interfaces
83
+
------------------------
86
84
87
85
RapidIO interconnect specification defines features that may be used to provide
88
86
one or more common service layers for all participating RapidIO devices. These
···
96
90
the same device without blocking attachment of a device-specific driver.
97
91
98
92
3. Subsystem Initialization
99
-
---------------------------
93
+
===========================
100
94
101
95
In order to initialize the RapidIO subsystem, a platform must initialize and
102
96
register at least one master port within the RapidIO network. To register mport
···
111
105
modular component of the kernel (see details below).
112
106
113
107
4. Enumeration and Discovery
114
-
----------------------------
108
+
============================
115
109
116
110
4.1 Overview
117
111
------------
···
174
168
(b) If the RapidIO subsystem core is built as a loadable module, in addition
175
169
to the method shown above, the host destination ID(s) can be specified using
176
170
traditional methods of passing module parameter "hdid=" during its loading:
171
+
177
172
- from command line: "modprobe rapidio hdid=-1,7", or
178
173
- from modprobe configuration file using configuration command "options",
179
174
like in this example: "options rapidio hdid=-1,7". An example of modprobe
180
175
configuration file is provided in the section below.
181
176
182
-
NOTES:
177
+
NOTES:
183
178
(i) if "hdid=" parameter is omitted all available mport will be assigned
184
179
destination ID = -1;
180
+
185
181
(ii) the "hdid=" parameter in systems with multiple mports can have
186
182
destination ID assignments omitted from the end of list (default = -1).
187
183
···
325
317
This process can be automated by specifying pre- or post- dependencies in the
326
318
RapidIO-specific modprobe configuration file as shown in the example below.
327
319
328
-
File /etc/modprobe.d/rapidio.conf:
329
-
----------------------------------
320
+
File /etc/modprobe.d/rapidio.conf::
330
321
331
322
# Configure RapidIO subsystem modules
332
323
···
342
335
343
336
--------------------------
344
337
345
-
NOTE: In the example above, one of "softdep" commands must be removed or
346
-
commented out to keep required module loading sequence.
338
+
NOTE:
339
+
In the example above, one of "softdep" commands must be removed or
340
+
commented out to keep required module loading sequence.
347
341
348
-
A. References
349
-
-------------
342
+
5. References
343
+
=============
350
344
351
345
[1] RapidIO Trade Association. RapidIO Interconnect Specifications.
352
346
http://www.rapidio.org.
347
+
353
348
[2] Rapidio TA. Technology Comparisons.
354
349
http://www.rapidio.org/education/technology_comparisons/
350
+
355
351
[3] RapidIO support for Linux.
356
352
http://lwn.net/Articles/139118/
353
+
357
354
[4] Matt Porter. RapidIO for Linux. Ottawa Linux Symposium, 2005
358
355
http://www.kernel.org/doc/ols/2005/ols2005v2-pages-43-56.pdf
+41
-25
Documentation/rapidio/rio_cm.txt
Documentation/rapidio/rio_cm.rst
+41
-25
Documentation/rapidio/rio_cm.txt
Documentation/rapidio/rio_cm.rst
···
1
+
==========================================================================
1
2
RapidIO subsystem Channelized Messaging character device driver (rio_cm.c)
2
3
==========================================================================
3
4
4
-
Version History:
5
-
----------------
6
-
1.0.0 - Initial driver release.
7
5
8
-
==========================================================================
9
-
10
-
I. Overview
6
+
1. Overview
7
+
===========
11
8
12
9
This device driver is the result of collaboration within the RapidIO.org
13
10
Software Task Group (STG) between Texas Instruments, Prodrive Technologies,
···
38
41
39
42
Following ioctl commands are available to user-space applications:
40
43
41
-
- RIO_CM_MPORT_GET_LIST : Returns to caller list of local mport devices that
44
+
- RIO_CM_MPORT_GET_LIST:
45
+
Returns to caller list of local mport devices that
42
46
support messaging operations (number of entries up to RIO_MAX_MPORTS).
43
47
Each list entry is combination of mport's index in the system and RapidIO
44
48
destination ID assigned to the port.
45
-
- RIO_CM_EP_GET_LIST_SIZE : Returns number of messaging capable remote endpoints
49
+
- RIO_CM_EP_GET_LIST_SIZE:
50
+
Returns number of messaging capable remote endpoints
46
51
in a RapidIO network associated with the specified mport device.
47
-
- RIO_CM_EP_GET_LIST : Returns list of RapidIO destination IDs for messaging
52
+
- RIO_CM_EP_GET_LIST:
53
+
Returns list of RapidIO destination IDs for messaging
48
54
capable remote endpoints (peers) available in a RapidIO network associated
49
55
with the specified mport device.
50
-
- RIO_CM_CHAN_CREATE : Creates RapidIO message exchange channel data structure
56
+
- RIO_CM_CHAN_CREATE:
57
+
Creates RapidIO message exchange channel data structure
51
58
with channel ID assigned automatically or as requested by a caller.
52
-
- RIO_CM_CHAN_BIND : Binds the specified channel data structure to the specified
59
+
- RIO_CM_CHAN_BIND:
60
+
Binds the specified channel data structure to the specified
53
61
mport device.
54
-
- RIO_CM_CHAN_LISTEN : Enables listening for connection requests on the specified
62
+
- RIO_CM_CHAN_LISTEN:
63
+
Enables listening for connection requests on the specified
55
64
channel.
56
-
- RIO_CM_CHAN_ACCEPT : Accepts a connection request from peer on the specified
65
+
- RIO_CM_CHAN_ACCEPT:
66
+
Accepts a connection request from peer on the specified
57
67
channel. If wait timeout for this request is specified by a caller it is
58
68
a blocking call. If timeout set to 0 this is non-blocking call - ioctl
59
69
handler checks for a pending connection request and if one is not available
60
70
exits with -EGAIN error status immediately.
61
-
- RIO_CM_CHAN_CONNECT : Sends a connection request to a remote peer/channel.
62
-
- RIO_CM_CHAN_SEND : Sends a data message through the specified channel.
71
+
- RIO_CM_CHAN_CONNECT:
72
+
Sends a connection request to a remote peer/channel.
73
+
- RIO_CM_CHAN_SEND:
74
+
Sends a data message through the specified channel.
63
75
The handler for this request assumes that message buffer specified by
64
76
a caller includes the reserved space for a packet header required by
65
77
this driver.
66
-
- RIO_CM_CHAN_RECEIVE : Receives a data message through a connected channel.
78
+
- RIO_CM_CHAN_RECEIVE:
79
+
Receives a data message through a connected channel.
67
80
If the channel does not have an incoming message ready to return this ioctl
68
81
handler will wait for new message until timeout specified by a caller
69
82
expires. If timeout value is set to 0, ioctl handler uses a default value
70
83
defined by MAX_SCHEDULE_TIMEOUT.
71
-
- RIO_CM_CHAN_CLOSE : Closes a specified channel and frees associated buffers.
84
+
- RIO_CM_CHAN_CLOSE:
85
+
Closes a specified channel and frees associated buffers.
72
86
If the specified channel is in the CONNECTED state, sends close notification
73
87
to the remote peer.
74
88
75
89
The ioctl command codes and corresponding data structures intended for use by
76
90
user-space applications are defined in 'include/uapi/linux/rio_cm_cdev.h'.
77
91
78
-
II. Hardware Compatibility
92
+
2. Hardware Compatibility
93
+
=========================
79
94
80
95
This device driver uses standard interfaces defined by kernel RapidIO subsystem
81
96
and therefore it can be used with any mport device driver registered by RapidIO
82
97
subsystem with limitations set by available mport HW implementation of messaging
83
98
mailboxes.
84
99
85
-
III. Module parameters
100
+
3. Module parameters
101
+
====================
86
102
87
-
- 'dbg_level' - This parameter allows to control amount of debug information
103
+
- 'dbg_level'
104
+
- This parameter allows to control amount of debug information
88
105
generated by this device driver. This parameter is formed by set of
89
106
bit masks that correspond to the specific functional block.
90
107
For mask definitions see 'drivers/rapidio/devices/rio_cm.c'
91
108
This parameter can be changed dynamically.
92
109
Use CONFIG_RAPIDIO_DEBUG=y to enable debug output at the top level.
93
110
94
-
- 'cmbox' - Number of RapidIO mailbox to use (default value is 1).
111
+
- 'cmbox'
112
+
- Number of RapidIO mailbox to use (default value is 1).
95
113
This parameter allows to set messaging mailbox number that will be used
96
114
within entire RapidIO network. It can be used when default mailbox is
97
115
used by other device drivers or is not supported by some nodes in the
98
116
RapidIO network.
99
117
100
-
- 'chstart' - Start channel number for dynamic assignment. Default value - 256.
118
+
- 'chstart'
119
+
- Start channel number for dynamic assignment. Default value - 256.
101
120
Allows to exclude channel numbers below this parameter from dynamic
102
121
allocation to avoid conflicts with software components that use
103
122
reserved predefined channel numbers.
104
123
105
-
IV. Known problems
124
+
4. Known problems
125
+
=================
106
126
107
127
None.
108
128
109
-
V. User-space Applications and API Library
129
+
5. User-space Applications and API Library
130
+
==========================================
110
131
111
132
Messaging API library and applications that use this device driver are available
112
133
from RapidIO.org.
113
134
114
-
VI. TODO List
135
+
6. TODO List
136
+
============
115
137
116
138
- Add support for system notification messages (reserved channel 0).
+4
Documentation/rapidio/sysfs.txt
Documentation/rapidio/sysfs.rst
+4
Documentation/rapidio/sysfs.txt
Documentation/rapidio/sysfs.rst
+30
-15
Documentation/rapidio/tsi721.txt
Documentation/rapidio/tsi721.rst
+30
-15
Documentation/rapidio/tsi721.txt
Documentation/rapidio/tsi721.rst
···
1
+
=========================================================================
1
2
RapidIO subsystem mport driver for IDT Tsi721 PCI Express-to-SRIO bridge.
2
3
=========================================================================
3
4
4
-
I. Overview
5
+
1. Overview
6
+
===========
5
7
6
8
This driver implements all currently defined RapidIO mport callback functions.
7
9
It supports maintenance read and write operations, inbound and outbound RapidIO
···
19
17
fully compatible with RIONET driver (Ethernet over RapidIO messaging services).
20
18
21
19
1. Module parameters:
22
-
- 'dbg_level' - This parameter allows to control amount of debug information
20
+
21
+
- 'dbg_level'
22
+
- This parameter allows to control amount of debug information
23
23
generated by this device driver. This parameter is formed by set of
24
24
This parameter can be changed bit masks that correspond to the specific
25
25
functional block.
···
29
25
This parameter can be changed dynamically.
30
26
Use CONFIG_RAPIDIO_DEBUG=y to enable debug output at the top level.
31
27
32
-
- 'dma_desc_per_channel' - This parameter defines number of hardware buffer
28
+
- 'dma_desc_per_channel'
29
+
- This parameter defines number of hardware buffer
33
30
descriptors allocated for each registered Tsi721 DMA channel.
34
31
Its default value is 128.
35
32
36
-
- 'dma_txqueue_sz' - DMA transactions queue size. Defines number of pending
33
+
- 'dma_txqueue_sz'
34
+
- DMA transactions queue size. Defines number of pending
37
35
transaction requests that can be accepted by each DMA channel.
38
36
Default value is 16.
39
37
40
-
- 'dma_sel' - DMA channel selection mask. Bitmask that defines which hardware
38
+
- 'dma_sel'
39
+
- DMA channel selection mask. Bitmask that defines which hardware
41
40
DMA channels (0 ... 6) will be registered with DmaEngine core.
42
41
If bit is set to 1, the corresponding DMA channel will be registered.
43
42
DMA channels not selected by this mask will not be used by this device
44
43
driver. Default value is 0x7f (use all channels).
45
44
46
-
- 'pcie_mrrs' - override value for PCIe Maximum Read Request Size (MRRS).
45
+
- 'pcie_mrrs'
46
+
- override value for PCIe Maximum Read Request Size (MRRS).
47
47
This parameter gives an ability to override MRRS value set during PCIe
48
48
configuration process. Tsi721 supports read request sizes up to 4096B.
49
49
Value for this parameter must be set as defined by PCIe specification:
50
50
0 = 128B, 1 = 256B, 2 = 512B, 3 = 1024B, 4 = 2048B and 5 = 4096B.
51
51
Default value is '-1' (= keep platform setting).
52
52
53
-
- 'mbox_sel' - RIO messaging MBOX selection mask. This is a bitmask that defines
53
+
- 'mbox_sel'
54
+
- RIO messaging MBOX selection mask. This is a bitmask that defines
54
55
messaging MBOXes are managed by this device driver. Mask bits 0 - 3
55
56
correspond to MBOX0 - MBOX3. MBOX is under driver's control if the
56
57
corresponding bit is set to '1'. Default value is 0x0f (= all).
57
58
58
-
II. Known problems
59
+
2. Known problems
60
+
=================
59
61
60
62
None.
61
63
62
-
III. DMA Engine Support
64
+
3. DMA Engine Support
65
+
=====================
63
66
64
67
Tsi721 mport driver supports DMA data transfers between local system memory and
65
68
remote RapidIO devices. This functionality is implemented according to SLAVE
···
79
68
80
69
If Tsi721 mport driver have been built with RAPIDIO_DMA_ENGINE support included,
81
70
this driver will accept DMA-specific module parameter:
82
-
"dma_desc_per_channel" - defines number of hardware buffer descriptors used by
71
+
72
+
"dma_desc_per_channel"
73
+
- defines number of hardware buffer descriptors used by
83
74
each BDMA channel of Tsi721 (by default - 128).
84
75
85
-
IV. Version History
76
+
4. Version History
86
77
87
-
1.1.0 - DMA operations re-worked to support data scatter/gather lists larger
78
+
===== ====================================================================
79
+
1.1.0 DMA operations re-worked to support data scatter/gather lists larger
88
80
than hardware buffer descriptors ring.
89
-
1.0.0 - Initial driver release.
81
+
1.0.0 Initial driver release.
82
+
===== ====================================================================
90
83
91
-
V. License
92
-
-----------------------------------------------
84
+
5. License
85
+
===========
93
86
94
87
Copyright(c) 2011 Integrated Device Technology, Inc. All rights reserved.
95
88
+1
-1
drivers/rapidio/Kconfig
+1
-1
drivers/rapidio/Kconfig
···
86
86
This option includes RapidIO channelized messaging driver which
87
87
provides socket-like interface to allow sharing of single RapidIO
88
88
messaging mailbox between multiple user-space applications.
89
-
See "Documentation/rapidio/rio_cm.txt" for driver description.
89
+
See "Documentation/rapidio/rio_cm.rst" for driver description.
90
90
91
91
config RAPIDIO_MPORT_CDEV
92
92
tristate "RapidIO /dev mport device driver"