요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
==========================================================================
RapidIO subsystem Channelized Messaging character device driver (rio_cm.c)
==========================================================================
1. Overview
===========
This device driver is the result of collaboration within the RapidIO.org
Software Task Group (STG) between Texas Instruments, Prodrive Technologies,
Nokia Networks, BAE and IDT. Additional input was received from other members
of RapidIO.org.
The objective was to create a character mode driver interface which exposes
messaging capabilities of RapidIO endpoint devices (mports) directly
to applications, in a manner that allows the numerous and varied RapidIO
implementations to interoperate.
This driver (RIO_CM) provides to user-space applications shared access to
RapidIO mailbox messaging resources.
RapidIO specification (Part 2) defines that endpoint devices may have up to four
messaging mailboxes in case of multi-packet message (up to 4KB) and
up to 64 mailboxes if single-packet messages (up to 256 B) are used. In addition
to protocol definition limitations, a particular hardware implementation can
have reduced number of messaging mailboxes. RapidIO aware applications must
therefore share the messaging resources of a RapidIO endpoint.
Main purpose of this device driver is to provide RapidIO mailbox messaging
capability to large number of user-space processes by introducing socket-like
operations using a single messaging mailbox. This allows applications to
use the limited RapidIO messaging hardware resources efficiently.
Most of device driver's operations are supported through 'ioctl' system calls.
When loaded this device driver creates a single file system node named rio_cm
in /dev directory common for all registered RapidIO mport devices.
Following ioctl commands are available to user-space applications:
- RIO_CM_MPORT_GET_LIST:
Returns to caller list of local mport devices that
support messaging operations (number of entries up to RIO_MAX_MPORTS).
Each list entry is combination of mport's index in the system and RapidIO
destination ID assigned to the port.
- RIO_CM_EP_GET_LIST_SIZE:
Returns number of messaging capable remote endpoints
in a RapidIO network associated with the specified mport device.
- RIO_CM_EP_GET_LIST:
Returns list of RapidIO destination IDs for messaging
capable remote endpoints (peers) available in a RapidIO network associated
with the specified mport device.
- RIO_CM_CHAN_CREATE:
Creates RapidIO message exchange channel data structure
with channel ID assigned automatically or as requested by a caller.
- RIO_CM_CHAN_BIND:
Binds the specified channel data structure to the specified
mport device.
- RIO_CM_CHAN_LISTEN:
Enables listening for connection requests on the specified
channel.
- RIO_CM_CHAN_ACCEPT:
Accepts a connection request from peer on the specified
channel. If wait timeout for this request is specified by a caller it is
a blocking call. If timeout set to 0 this is non-blocking call - ioctl
handler checks for a pending connection request and if one is not available
exits with -EGAIN error status immediately.
- RIO_CM_CHAN_CONNECT:
Sends a connection request to a remote peer/channel.
- RIO_CM_CHAN_SEND:
Sends a data message through the specified channel.
The handler for this request assumes that message buffer specified by
a caller includes the reserved space for a packet header required by
this driver.
- RIO_CM_CHAN_RECEIVE:
Receives a data message through a connected channel.
If the channel does not have an incoming message ready to return this ioctl
handler will wait for new message until timeout specified by a caller
expires. If timeout value is set to 0, ioctl handler uses a default value
defined by MAX_SCHEDULE_TIMEOUT.
- RIO_CM_CHAN_CLOSE:
Closes a specified channel and frees associated buffers.
If the specified channel is in the CONNECTED state, sends close notification
to the remote peer.
The ioctl command codes and corresponding data structures intended for use by
user-space applications are defined in 'include/uapi/linux/rio_cm_cdev.h'.
2. Hardware Compatibility
=========================
This device driver uses standard interfaces defined by kernel RapidIO subsystem
and therefore it can be used with any mport device driver registered by RapidIO
subsystem with limitations set by available mport HW implementation of messaging
mailboxes.
3. Module parameters
====================
- 'dbg_level'
- This parameter allows to control amount of debug information
generated by this device driver. This parameter is formed by set of
bit masks that correspond to the specific functional block.
For mask definitions see 'drivers/rapidio/devices/rio_cm.c'
This parameter can be changed dynamically.
Use CONFIG_RAPIDIO_DEBUG=y to enable debug output at the top level.
- 'cmbox'
- Number of RapidIO mailbox to use (default value is 1).
This parameter allows to set messaging mailbox number that will be used
within entire RapidIO network. It can be used when default mailbox is
used by other device drivers or is not supported by some nodes in the
RapidIO network.
- 'chstart'
- Start channel number for dynamic assignment. Default value - 256.
Allows to exclude channel numbers below this parameter from dynamic
allocation to avoid conflicts with software components that use
reserved predefined channel numbers.
4. Known problems
=================
None.
5. User-space Applications and API Library
==========================================
Messaging API library and applications that use this device driver are available
from RapidIO.org.
6. TODO List
============
- Add support for system notification messages (reserved channel 0).
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
RIO_CM driver 목적과 협력 배경
1-18RapidIO subsystem Channelized Messaging character device driver인 `rio_cm.c`는 RapidIO.org Software Task Group(STG)에서 Texas Instruments, Prodrive Technologies, Nokia Networks, BAE, IDT가 협력한 결과입니다. 다른 RapidIO.org 회원도 의견을 제공했습니다.
목표는 다양한 RapidIO 구현이 상호 운용될 수 있도록 RapidIO endpoint device, 즉 mport의 messaging capability를 application에 직접 노출하는 character-mode driver interface를 만드는 것이었습니다.
==========================================================================
RapidIO subsystem Channelized Messaging character device driver (rio_cm.c)
==========================================================================
1. Overview
===========
This device driver is the result of collaboration within the RapidIO.org
Software Task Group (STG) between Texas Instruments, Prodrive Technologies,
Nokia Networks, BAE and IDT. Additional input was received from other members
of RapidIO.org.
The objective was to create a character mode driver interface which exposes
messaging capabilities of RapidIO endpoint devices (mports) directly
to applications, in a manner that allows the numerous and varied RapidIO
implementations to interoperate.
Mailbox resource 공유와 `/dev/rio_cm`
19-38`RIO_CM`은 userspace application이 RapidIO mailbox messaging resource를 공유해서 접근하도록 합니다.
RapidIO specification Part 2에 따르면 endpoint는 최대 4 KB multi-packet message를 사용할 때 mailbox를 최대 4개, 최대 256 B single-packet message를 사용할 때 최대 64개 가질 수 있습니다. 실제 hardware는 이보다 적은 mailbox만 구현할 수 있으므로 RapidIO-aware application은 endpoint의 messaging resource를 공유해야 합니다.
Driver는 하나의 messaging mailbox 위에 socket과 유사한 operation을 도입해 많은 userspace process에 mailbox messaging을 제공합니다. 제한된 RapidIO messaging hardware resource를 효율적으로 사용하는 것이 핵심 목적입니다.
대부분의 operation은 `ioctl` system call로 제공됩니다. Driver를 load하면 등록된 모든 RapidIO mport가 공통으로 사용하는 단일 filesystem node `/dev/rio_cm`을 만듭니다.
Socket-like channel이 제한된 hardware mailbox 하나를 여러 process가 공유하게 합니다.
This driver (RIO_CM) provides to user-space applications shared access to
RapidIO mailbox messaging resources.
RapidIO specification (Part 2) defines that endpoint devices may have up to four
messaging mailboxes in case of multi-packet message (up to 4KB) and
up to 64 mailboxes if single-packet messages (up to 256 B) are used. In addition
to protocol definition limitations, a particular hardware implementation can
have reduced number of messaging mailboxes. RapidIO aware applications must
therefore share the messaging resources of a RapidIO endpoint.
Main purpose of this device driver is to provide RapidIO mailbox messaging
capability to large number of user-space processes by introducing socket-like
operations using a single messaging mailbox. This allows applications to
use the limited RapidIO messaging hardware resources efficiently.
Most of device driver's operations are supported through 'ioctl' system calls.
When loaded this device driver creates a single file system node named rio_cm
in /dev directory common for all registered RapidIO mport devices.
Mport·peer 조회와 channel 준비
39-61`RIO_CM_MPORT_GET_LIST`는 messaging operation을 지원하는 local mport list를 반환하며 entry 수는 `RIO_MAX_MPORTS`까지입니다. 각 entry는 system의 mport index와 해당 port의 RapidIO destination ID 조합입니다.
`RIO_CM_EP_GET_LIST_SIZE`는 지정 mport와 연결된 RapidIO network에서 messaging-capable remote endpoint 수를 반환합니다. `RIO_CM_EP_GET_LIST`는 그 remote peer들의 RapidIO destination ID list를 반환합니다.
`RIO_CM_CHAN_CREATE`는 caller가 요청한 ID 또는 자동 배정 ID로 message-exchange channel data structure를 만듭니다. `RIO_CM_CHAN_BIND`는 channel을 지정 mport에 bind하고 `RIO_CM_CHAN_LISTEN`은 그 channel에서 connection request 수신을 시작합니다.
Following ioctl commands are available to user-space applications:
- RIO_CM_MPORT_GET_LIST:
Returns to caller list of local mport devices that
support messaging operations (number of entries up to RIO_MAX_MPORTS).
Each list entry is combination of mport's index in the system and RapidIO
destination ID assigned to the port.
- RIO_CM_EP_GET_LIST_SIZE:
Returns number of messaging capable remote endpoints
in a RapidIO network associated with the specified mport device.
- RIO_CM_EP_GET_LIST:
Returns list of RapidIO destination IDs for messaging
capable remote endpoints (peers) available in a RapidIO network associated
with the specified mport device.
- RIO_CM_CHAN_CREATE:
Creates RapidIO message exchange channel data structure
with channel ID assigned automatically or as requested by a caller.
- RIO_CM_CHAN_BIND:
Binds the specified channel data structure to the specified
mport device.
- RIO_CM_CHAN_LISTEN:
Enables listening for connection requests on the specified
channel.Connection과 message data path
62-88`RIO_CM_CHAN_ACCEPT`는 지정 channel에서 peer connection request를 accept합니다. Caller가 wait timeout을 지정하면 blocking call입니다. Timeout이 0이면 pending request만 확인하는 non-blocking call이며 요청이 없을 때 즉시 `-EGAIN`으로 종료합니다.
`RIO_CM_CHAN_CONNECT`는 remote peer와 channel에 connection request를 보냅니다. `RIO_CM_CHAN_SEND`는 지정 channel로 data message를 보내며 caller의 message buffer에 driver가 요구하는 packet header 예약 공간이 포함되어 있다고 가정합니다.
`RIO_CM_CHAN_RECEIVE`는 connected channel에서 data message를 받습니다. 준비된 incoming message가 없으면 caller timeout까지 기다립니다. Timeout이 0이면 `MAX_SCHEDULE_TIMEOUT`으로 정의된 기본값을 사용합니다.
`RIO_CM_CHAN_CLOSE`는 channel을 닫고 관련 buffer를 해제합니다. Channel state가 `CONNECTED`이면 remote peer에 close notification도 보냅니다.
Userspace가 사용하는 ioctl command code와 대응 data structure는 `include/uapi/linux/rio_cm_cdev.h`에 정의되어 있습니다.
- RIO_CM_CHAN_ACCEPT:
Accepts a connection request from peer on the specified
channel. If wait timeout for this request is specified by a caller it is
a blocking call. If timeout set to 0 this is non-blocking call - ioctl
handler checks for a pending connection request and if one is not available
exits with -EGAIN error status immediately.
- RIO_CM_CHAN_CONNECT:
Sends a connection request to a remote peer/channel.
- RIO_CM_CHAN_SEND:
Sends a data message through the specified channel.
The handler for this request assumes that message buffer specified by
a caller includes the reserved space for a packet header required by
this driver.
- RIO_CM_CHAN_RECEIVE:
Receives a data message through a connected channel.
If the channel does not have an incoming message ready to return this ioctl
handler will wait for new message until timeout specified by a caller
expires. If timeout value is set to 0, ioctl handler uses a default value
defined by MAX_SCHEDULE_TIMEOUT.
- RIO_CM_CHAN_CLOSE:
Closes a specified channel and frees associated buffers.
If the specified channel is in the CONNECTED state, sends close notification
to the remote peer.
The ioctl command codes and corresponding data structures intended for use by
user-space applications are defined in 'include/uapi/linux/rio_cm_cdev.h'.
Hardware compatibility
89-96이 driver는 kernel RapidIO subsystem의 standard interface를 사용하므로 subsystem에 등록된 어떤 mport device driver와도 사용할 수 있습니다.
실제 기능은 mport hardware가 구현한 messaging mailbox capability에 의해 제한됩니다.
2. Hardware Compatibility
=========================
This device driver uses standard interfaces defined by kernel RapidIO subsystem
and therefore it can be used with any mport device driver registered by RapidIO
subsystem with limitations set by available mport HW implementation of messaging
mailboxes.
Module parameter
97-120`dbg_level`은 driver가 생성하는 debug information의 양을 기능 block별 bit mask로 제어합니다. Mask 정의는 `drivers/rapidio/devices/rio_cm.c`에 있으며 runtime에 동적으로 변경할 수 있습니다. 최상위 debug output은 `CONFIG_RAPIDIO_DEBUG=y`로 활성화합니다.
`cmbox`는 사용할 RapidIO mailbox 번호이며 기본값은 1입니다. Network 전체가 사용할 messaging mailbox를 지정합니다. 기본 mailbox를 다른 driver가 사용 중이거나 network의 일부 node가 지원하지 않을 때 다른 번호를 선택할 수 있습니다.
`chstart`는 dynamic assignment를 시작할 channel 번호이며 기본값은 256입니다. 이 값보다 작은 channel 번호를 dynamic allocation에서 제외해 reserved predefined channel을 사용하는 software component와의 충돌을 피합니다.
3. Module parameters
====================
- 'dbg_level'
- This parameter allows to control amount of debug information
generated by this device driver. This parameter is formed by set of
bit masks that correspond to the specific functional block.
For mask definitions see 'drivers/rapidio/devices/rio_cm.c'
This parameter can be changed dynamically.
Use CONFIG_RAPIDIO_DEBUG=y to enable debug output at the top level.
- 'cmbox'
- Number of RapidIO mailbox to use (default value is 1).
This parameter allows to set messaging mailbox number that will be used
within entire RapidIO network. It can be used when default mailbox is
used by other device drivers or is not supported by some nodes in the
RapidIO network.
- 'chstart'
- Start channel number for dynamic assignment. Default value - 256.
Allows to exclude channel numbers below this parameter from dynamic
allocation to avoid conflicts with software components that use
reserved predefined channel numbers.
Known problems
121-125문서화된 known problem은 없습니다.
4. Known problems
=================
None.
Userspace library와 application
126-131이 device driver를 사용하는 Messaging API library와 application은 RapidIO.org에서 제공합니다.
5. User-space Applications and API Library
==========================================
Messaging API library and applications that use this device driver are available
from RapidIO.org.
향후 작업
132-135향후 작업은 reserved channel 0을 사용하는 system notification message 지원을 추가하는 것입니다.
6. TODO List
============
- Add support for system notification messages (reserved channel 0).
요약과 해설
rio_cm.rst:1-135`RIO_CM`은 제한된 RapidIO messaging mailbox 하나를 socket-like channel로 multiplex해 여러 process에 공유합니다. Mport와 peer 탐색, channel 생성·bind·listen·accept·connect, message 송수신과 close를 ioctl로 제공하며 timeout 0의 의미는 accept와 receive에서 다릅니다.