RapidIO subsystem mport character device driver (rio_mport_cdev.c)

MPORT character device 개요

RapidIO subsystem mport character device driver인 `rio_mport_cdev.c`는 RapidIO.org Software Task Group(STG)에서 Texas Instruments, Freescale, Prodrive Technologies, Nokia Networks, BAE, IDT가 협력한 결과입니다. 다른 RapidIO.org 회원도 의견을 제공했습니다.

목표는 여러 형태의 RapidIO 구현이 상호 운용될 수 있도록 RapidIO device capability를 application에 직접 노출하는 character-mode driver interface를 만드는 것이었습니다.

`MPORT_CDEV` driver는 userspace application에 기본 RapidIO subsystem operation을 제공하며 대부분의 operation은 `ioctl` system call로 수행합니다.

Driver가 load되면 등록된 각 local RapidIO mport device에 대해 `/dev/rio_mportX` filesystem node를 만듭니다. 이름의 `X`는 각 local mport에 배정된 unique port ID와 일치합니다.

==================================================================
RapidIO subsystem mport character device driver (rio_mport_cdev.c)
==================================================================

1. Overview
===========

This device driver is the result of collaboration within the RapidIO.org
Software Task Group (STG) between Texas Instruments, Freescale,
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 the capabilities of RapidIO
devices directly to applications, in a manner that allows the numerous and
varied RapidIO implementations to interoperate.

This driver (MPORT_CDEV) provides access to basic RapidIO subsystem operations
for user-space applications. Most of RapidIO operations are supported through
'ioctl' system calls.

When loaded this device driver creates filesystem nodes named rio_mportX in /dev
directory for each registered RapidIO mport device. 'X' in the node name matches
to unique port ID assigned to each local mport device.

지원 RapidIO ioctl operation

Local mport configuration register는 `RIO_MPORT_MAINT_READ_LOCAL`과 `RIO_MPORT_MAINT_WRITE_LOCAL`로 읽고 씁니다. Remote RapidIO device의 configuration register는 RapidIO specification의 Maintenance read/write에 해당하는 `RIO_MPORT_MAINT_READ_REMOTE`과 `RIO_MPORT_MAINT_WRITE_REMOTE`을 사용합니다.

Mport의 Destination ID는 `RIO_MPORT_MAINT_HDID_SET`, Component Tag는 `RIO_MPORT_MAINT_COMPTAG_SET`으로 설정합니다. Logical mport index는 `RIO_MPORT_MAINT_PORT_IDX_GET`, capability와 link configuration은 `RIO_MPORT_GET_PROPERTIES`로 조회합니다.

Doorbell event userspace reporting은 `RIO_ENABLE_DOORBELL_RANGE`와 `RIO_DISABLE_DOORBELL_RANGE`, port-write event reporting은 `RIO_ENABLE_PORTWRITE_RANGE`와 `RIO_DISABLE_PORTWRITE_RANGE`로 제어합니다. Doorbell, port-write 또는 둘 다 받을지는 `RIO_SET_EVENT_MASK`와 `RIO_GET_EVENT_MASK`로 설정하고 조회합니다.

Outbound request window는 size, RapidIO destination ID, hopcount, request type을 지정해 `RIO_MAP_OUTBOUND`으로 mapping하고 `RIO_UNMAP_OUTBOUND`으로 해제합니다. Inbound request window는 size, RapidIO base address, local memory base address를 지정해 `RIO_MAP_INBOUND`과 `RIO_UNMAP_INBOUND`으로 관리합니다.

Remote RapidIO device와 DMA transfer할 contiguous DMA-coherent buffer는 `RIO_ALLOC_DMA`와 `RIO_FREE_DMA`로 할당하고 해제합니다. `RIO_TRANSFER`는 blocking, asynchronous, posted, 즉 fire-and-forget mode를 지원합니다. Asynchronous transfer 완료는 `RIO_WAIT_FOR_ASYNC`으로 확인하거나 기다립니다.

`RIO_DEV_ADD`와 `RIO_DEV_DEL`은 RapidIO subsystem의 device object를 관리합니다. 이 기능을 사용하면 kernel subsystem의 나머지 기능을 활용하면서 fabric enumeration algorithm을 userspace application으로 구현할 수 있습니다.

Using available set of ioctl commands user-space applications can perform
following RapidIO bus and subsystem operations:

- Reads and writes from/to configuration registers of mport devices
  (RIO_MPORT_MAINT_READ_LOCAL/RIO_MPORT_MAINT_WRITE_LOCAL)
- Reads and writes from/to configuration registers of remote RapidIO devices.
  This operations are defined as RapidIO Maintenance reads/writes in RIO spec.
  (RIO_MPORT_MAINT_READ_REMOTE/RIO_MPORT_MAINT_WRITE_REMOTE)
- Set RapidIO Destination ID for mport devices (RIO_MPORT_MAINT_HDID_SET)
- Set RapidIO Component Tag for mport devices (RIO_MPORT_MAINT_COMPTAG_SET)
- Query logical index of mport devices (RIO_MPORT_MAINT_PORT_IDX_GET)
- Query capabilities and RapidIO link configuration of mport devices
  (RIO_MPORT_GET_PROPERTIES)
- Enable/Disable reporting of RapidIO doorbell events to user-space applications
  (RIO_ENABLE_DOORBELL_RANGE/RIO_DISABLE_DOORBELL_RANGE)
- Enable/Disable reporting of RIO port-write events to user-space applications
  (RIO_ENABLE_PORTWRITE_RANGE/RIO_DISABLE_PORTWRITE_RANGE)
- Query/Control type of events reported through this driver: doorbells,
  port-writes or both (RIO_SET_EVENT_MASK/RIO_GET_EVENT_MASK)
- Configure/Map mport's outbound requests window(s) for specific size,
  RapidIO destination ID, hopcount and request type
  (RIO_MAP_OUTBOUND/RIO_UNMAP_OUTBOUND)
- Configure/Map mport's inbound requests window(s) for specific size,
  RapidIO base address and local memory base address
  (RIO_MAP_INBOUND/RIO_UNMAP_INBOUND)
- Allocate/Free contiguous DMA coherent memory buffer for DMA data transfers
  to/from remote RapidIO devices (RIO_ALLOC_DMA/RIO_FREE_DMA)
- Initiate DMA data transfers to/from remote RapidIO devices (RIO_TRANSFER).
  Supports blocking, asynchronous and posted (a.k.a 'fire-and-forget') data
  transfer modes.
- Check/Wait for completion of asynchronous DMA data transfer
  (RIO_WAIT_FOR_ASYNC)
- Manage device objects supported by RapidIO subsystem (RIO_DEV_ADD/RIO_DEV_DEL).
  This allows implementation of various RapidIO fabric enumeration algorithms
  as user-space applications while using remaining functionality provided by
  kernel RapidIO subsystem.

Hardware compatibility와 DMA 제한

이 driver는 kernel RapidIO subsystem의 standard interface를 사용하므로 등록된 어떤 mport driver와도 사용할 수 있습니다. 실제 기능 범위는 해당 mport implementation이 제공하는 capability에 의해 제한됩니다.

가장 흔한 제한은 mport device별 RapidIO-specific DMA engine framework의 존재 여부입니다. Driver를 사용할 계획이라면 platform에서 제공하는 기능을 먼저 확인해야 합니다.

IDT Tsi721 PCIe-to-RapidIO bridge와 그 mport driver는 이 driver와 완전히 호환됩니다. Freescale SoC의 `fsl_rio` mport driver는 RapidIO-specific DMA engine을 구현하지 않으므로 `mport_cdev`의 DMA data transfer를 사용할 수 없습니다.

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 implementation.

At this moment the most common limitation is availability of RapidIO-specific
DMA engine framework for specific mport device. Users should verify available
functionality of their platform when planning to use this driver:

- IDT Tsi721 PCIe-to-RapidIO bridge device and its mport device driver are fully
  compatible with this driver.
- Freescale SoCs 'fsl_rio' mport driver does not have implementation for RapidIO
  specific DMA engine support and therefore DMA data transfers mport_cdev driver
  are not available.

Module parameter

`dma_timeout`은 DMA transfer completion timeout을 millisecond 단위로 지정하며 기본값은 3000입니다. SYNC mode DMA request와 `RIO_WAIT_FOR_ASYNC` ioctl request가 완료되기를 기다리는 최대 시간을 설정합니다.

`dbg_level`은 driver가 생성하는 debug information의 양을 제어합니다. 기능 block별 bit mask 집합으로 구성되며 mask 정의는 `drivers/rapidio/devices/rio_mport_cdev.c`에 있습니다.

`dbg_level`은 runtime에 동적으로 바꿀 수 있습니다. 최상위 debug output을 활성화하려면 `CONFIG_RAPIDIO_DEBUG=y`를 사용합니다.

3. Module parameters
====================

- 'dma_timeout'
      - DMA transfer completion timeout (in msec, default value 3000).
        This parameter set a maximum completion wait time for SYNC mode DMA
        transfer requests and for RIO_WAIT_FOR_ASYNC ioctl requests.

- '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 blocks.
        For mask definitions see 'drivers/rapidio/devices/rio_mport_cdev.c'
        This parameter can be changed dynamically.
        Use CONFIG_RAPIDIO_DEBUG=y to enable debug output at the top level.

Known problems

문서화된 known problem은 없습니다.

4. Known problems
=================

  None.

Userspace application과 API

이 device driver를 사용하는 API library와 application은 RapidIO.org에서 제공합니다.

5. User-space Applications and API
==================================

API library and applications that use this device driver are available from
RapidIO.org.

향후 작업

향후 작업에는 raw RapidIO messaging packet의 송수신 지원이 포함됩니다.

RapidIO-specific DMA를 사용할 수 없을 때 대안이 되도록 memory-mapped DMA data transfer도 추가할 예정입니다.

6. TODO List
============

- Add support for sending/receiving "raw" RapidIO messaging packets.
- Add memory mapped DMA data transfers as an option when RapidIO-specific DMA
  is not available.