IDT Tsi721 PCI Express-to-SRIO bridge mport driver

Tsi721 mport driver 개요

이 문서는 IDT Tsi721 PCI Express-to-SRIO bridge용 RapidIO subsystem mport driver를 설명합니다. Driver는 현재 정의된 RapidIO mport callback을 모두 구현합니다.

지원 기능에는 maintenance read/write, inbound·outbound RapidIO doorbell, inbound maintenance port-write와 RapidIO messaging이 포함됩니다.

SRIO maintenance transaction을 생성할 때 Tsi721 DMA channel 하나를 사용합니다. 이 방식은 outbound window translation을 바꾸지 않고 더 넓은 hopcount와 destination ID 범위에 접근하게 합니다.

RapidIO messaging은 mailbox마다 전용 messaging channel을 사용합니다. Inbound message는 destination ID matching으로 해당 message queue에 전달합니다. Messaging callback은 Ethernet-over-RapidIO messaging service를 제공하는 RIONET driver와 완전히 호환됩니다.

=========================================================================
RapidIO subsystem mport driver for IDT Tsi721 PCI Express-to-SRIO bridge.
=========================================================================

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

This driver implements all currently defined RapidIO mport callback functions.
It supports maintenance read and write operations, inbound and outbound RapidIO
doorbells, inbound maintenance port-writes and RapidIO messaging.

To generate SRIO maintenance transactions this driver uses one of Tsi721 DMA
channels. This mechanism provides access to larger range of hop counts and
destination IDs without need for changes in outbound window translation.

RapidIO messaging support uses dedicated messaging channels for each mailbox.
For inbound messages this driver uses destination ID matching to forward messages
into the corresponding message queue. Messaging callbacks are implemented to be

Module parameter

`dbg_level`은 기능 block별 bit mask로 debug information의 양을 제어합니다. Mask 정의는 `drivers/rapidio/devices/tsi721.h`에 있고 runtime에 동적으로 변경할 수 있습니다. 최상위 debug output은 `CONFIG_RAPIDIO_DEBUG=y`로 활성화합니다.

`dma_desc_per_channel`은 등록된 각 Tsi721 DMA channel에 할당할 hardware buffer descriptor 수이며 기본값은 128입니다. `dma_txqueue_sz`는 각 DMA channel이 받아들일 수 있는 pending transaction request 수이고 기본값은 16입니다.

`dma_sel`은 DmaEngine core에 등록할 hardware DMA channel 0부터 6까지의 selection bitmask입니다. Bit가 1인 channel만 등록하며 선택되지 않은 channel은 driver가 사용하지 않습니다. 기본값 `0x7f`는 일곱 channel 전체를 선택합니다.

`pcie_mrrs`는 PCIe configuration에서 설정한 Maximum Read Request Size(MRRS)를 override합니다. Tsi721은 최대 4096 B read request를 지원합니다. PCIe specification encoding은 0=128 B, 1=256 B, 2=512 B, 3=1024 B, 4=2048 B, 5=4096 B이며 기본값 `-1`은 platform 설정을 유지합니다.

`mbox_sel`은 driver가 관리할 RapidIO messaging MBOX selection mask입니다. Bit 0부터 3은 MBOX0부터 MBOX3에 대응하고 bit가 1인 mailbox를 제어합니다. 기본값 `0x0f`는 모두 선택합니다.

fully compatible with RIONET driver (Ethernet over RapidIO messaging services).

1. 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
        This parameter can be changed bit masks that correspond to the specific
        functional block.
        For mask definitions see 'drivers/rapidio/devices/tsi721.h'
        This parameter can be changed dynamically.
        Use CONFIG_RAPIDIO_DEBUG=y to enable debug output at the top level.

- 'dma_desc_per_channel'
      - This parameter defines number of hardware buffer
        descriptors allocated for each registered Tsi721 DMA channel.
        Its default value is 128.

- 'dma_txqueue_sz'
      - DMA transactions queue size. Defines number of pending
        transaction requests that can be accepted by each DMA channel.
        Default value is 16.

- 'dma_sel'
      - DMA channel selection mask. Bitmask that defines which hardware
        DMA channels (0 ... 6) will be registered with DmaEngine core.
        If bit is set to 1, the corresponding DMA channel will be registered.
        DMA channels not selected by this mask will not be used by this device
        driver. Default value is 0x7f (use all channels).

- 'pcie_mrrs'
      - override value for PCIe Maximum Read Request Size (MRRS).
        This parameter gives an ability to override MRRS value set during PCIe
        configuration process. Tsi721 supports read request sizes up to 4096B.
        Value for this parameter must be set as defined by PCIe specification:
        0 = 128B, 1 = 256B, 2 = 512B, 3 = 1024B, 4 = 2048B and 5 = 4096B.
        Default value is '-1' (= keep platform setting).

- 'mbox_sel'
      - RIO messaging MBOX selection mask. This is a bitmask that defines
        messaging MBOXes are managed by this device driver. Mask bits 0 - 3
        correspond to MBOX0 - MBOX3. MBOX is under driver's control if the
        corresponding bit is set to '1'. Default value is 0x0f (= all).

Known problems

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

2. Known problems
=================

  None.

DMA Engine support

Tsi721 mport driver는 local system memory와 remote RapidIO device 사이의 DMA data transfer를 지원합니다. Common Linux kernel DMA Engine framework가 정의한 SLAVE mode API에 따라 구현됩니다.

System 요구에 따라 `CONFIG_RAPIDIO_DMA_ENGINE` option으로 RapidIO DMA operation을 포함하거나 제외할 수 있습니다. Tsi721 mport driver는 사용 가능한 BDMA channel 8개 중 7개를 data transfer에 사용하고, 나머지 하나는 maintenance read/write request 생성용으로 예약합니다.

Driver가 `RAPIDIO_DMA_ENGINE` support를 포함해 build되면 DMA-specific `dma_desc_per_channel` module parameter를 받습니다. 각 Tsi721 BDMA channel이 사용하는 hardware buffer descriptor 수를 지정하며 기본값은 128입니다.

3. DMA Engine Support
=====================

Tsi721 mport driver supports DMA data transfers between local system memory and
remote RapidIO devices. This functionality is implemented according to SLAVE
mode API defined by common Linux kernel DMA Engine framework.

Depending on system requirements RapidIO DMA operations can be included/excluded
by setting CONFIG_RAPIDIO_DMA_ENGINE option. Tsi721 miniport driver uses seven
out of eight available BDMA channels to support DMA data transfers.
One BDMA channel is reserved for generation of maintenance read/write requests.

If Tsi721 mport driver have been built with RAPIDIO_DMA_ENGINE support included,
this driver will accept DMA-specific module parameter:

  "dma_desc_per_channel"
                         - defines number of hardware buffer descriptors used by
                           each BDMA channel of Tsi721 (by default - 128).

Version history

Version 1.1.0에서는 hardware buffer descriptor ring보다 큰 data scatter/gather list를 지원하도록 DMA operation을 재작업했습니다. Version 1.0.0은 최초 driver release입니다.

4. Version History

  =====   ====================================================================
  1.1.0   DMA operations re-worked to support data scatter/gather lists larger
          than hardware buffer descriptors ring.
  1.0.0   Initial driver release.
  =====   ====================================================================

License와 warranty

Copyright는 2011 Integrated Device Technology, Inc.에 있습니다.

이 program은 Free Software Foundation이 발행한 GNU General Public License version 2 또는 선택에 따라 이후 version의 조건으로 재배포하거나 수정할 수 있는 free software입니다.

Program은 유용하기를 바라며 배포되지만 merchantability나 특정 목적 적합성에 대한 implied warranty를 포함해 어떠한 warranty도 없습니다. 자세한 내용은 GNU General Public License를 참조합니다.

License 사본을 받지 못했다면 Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA로 문의합니다.

5.  License
===========

  Copyright(c) 2011 Integrated Device Technology, Inc. All rights reserved.

  This program is free software; you can redistribute it and/or modify it
  under the terms of the GNU General Public License as published by the Free
  Software Foundation; either version 2 of the License, or (at your option)
  any later version.

  This program is distributed in the hope that it will be useful, but WITHOUT
  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
  more details.

  You should have received a copy of the GNU General Public License along with
  this program; if not, write to the Free Software Foundation, Inc.,
  59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.