Documentation/driver-api/rapidio/tsi721.rst

   1 =========================================================================
   2 RapidIO subsystem mport driver for IDT Tsi721 PCI Express-to-SRIO bridge.
   3 =========================================================================
   4
   5 1. Overview
   6 ===========
   7
   8 This driver implements all currently defined RapidIO mport callback functions.
   9 It supports maintenance read and write operations, inbound and outbound RapidIO
  10 doorbells, inbound maintenance port-writes and RapidIO messaging.
  11
  12 To generate SRIO maintenance transactions this driver uses one of Tsi721 DMA
  13 channels. This mechanism provides access to larger range of hop counts and
  14 destination IDs without need for changes in outbound window translation.
  15
  16 RapidIO messaging support uses dedicated messaging channels for each mailbox.
  17 For inbound messages this driver uses destination ID matching to forward messages
  18 into the corresponding message queue. Messaging callbacks are implemented to be
  19 fully compatible with RIONET driver (Ethernet over RapidIO messaging services).
  20
  21 1. Module parameters:
  22
  23 - 'dbg_level'
  24       - This parameter allows to control amount of debug information
  25         generated by this device driver. This parameter is formed by set of
  26         This parameter can be changed bit masks that correspond to the specific
  27         functional block.
  28         For mask definitions see 'drivers/rapidio/devices/tsi721.h'
  29         This parameter can be changed dynamically.
  30         Use CONFIG_RAPIDIO_DEBUG=y to enable debug output at the top level.
  31
  32 - 'dma_desc_per_channel'
  33       - This parameter defines number of hardware buffer
  34         descriptors allocated for each registered Tsi721 DMA channel.
  35         Its default value is 128.
  36
  37 - 'dma_txqueue_sz'
  38       - DMA transactions queue size. Defines number of pending
  39         transaction requests that can be accepted by each DMA channel.
  40         Default value is 16.
  41
  42 - 'dma_sel'
  43       - DMA channel selection mask. Bitmask that defines which hardware
  44         DMA channels (0 ... 6) will be registered with DmaEngine core.
  45         If bit is set to 1, the corresponding DMA channel will be registered.
  46         DMA channels not selected by this mask will not be used by this device
  47         driver. Default value is 0x7f (use all channels).
  48
  49 - 'pcie_mrrs'
  50       - override value for PCIe Maximum Read Request Size (MRRS).
  51         This parameter gives an ability to override MRRS value set during PCIe
  52         configuration process. Tsi721 supports read request sizes up to 4096B.
  53         Value for this parameter must be set as defined by PCIe specification:
  54         0 = 128B, 1 = 256B, 2 = 512B, 3 = 1024B, 4 = 2048B and 5 = 4096B.
  55         Default value is '-1' (= keep platform setting).
  56
  57 - 'mbox_sel'
  58       - RIO messaging MBOX selection mask. This is a bitmask that defines
  59         messaging MBOXes are managed by this device driver. Mask bits 0 - 3
  60         correspond to MBOX0 - MBOX3. MBOX is under driver's control if the
  61         corresponding bit is set to '1'. Default value is 0x0f (= all).
  62
  63 2. Known problems
  64 =================
  65
  66   None.
  67
  68 3. DMA Engine Support
  69 =====================
  70
  71 Tsi721 mport driver supports DMA data transfers between local system memory and
  72 remote RapidIO devices. This functionality is implemented according to SLAVE
  73 mode API defined by common Linux kernel DMA Engine framework.
  74
  75 Depending on system requirements RapidIO DMA operations can be included/excluded
  76 by setting CONFIG_RAPIDIO_DMA_ENGINE option. Tsi721 miniport driver uses seven
  77 out of eight available BDMA channels to support DMA data transfers.
  78 One BDMA channel is reserved for generation of maintenance read/write requests.
  79
  80 If Tsi721 mport driver have been built with RAPIDIO_DMA_ENGINE support included,
  81 this driver will accept DMA-specific module parameter:
  82
  83   "dma_desc_per_channel"
  84                          - defines number of hardware buffer descriptors used by
  85                            each BDMA channel of Tsi721 (by default - 128).
  86
  87 4. Version History
  88
  89   =====   ====================================================================
  90   1.1.0   DMA operations re-worked to support data scatter/gather lists larger
  91           than hardware buffer descriptors ring.
  92   1.0.0   Initial driver release.
  93   =====   ====================================================================
  94
  95 5.  License
  96 ===========
  97
  98   Copyright(c) 2011 Integrated Device Technology, Inc. All rights reserved.
  99
 100   This program is free software; you can redistribute it and/or modify it
 101   under the terms of the GNU General Public License as published by the Free
 102   Software Foundation; either version 2 of the License, or (at your option)
 103   any later version.
 104
 105   This program is distributed in the hope that it will be useful, but WITHOUT
 106   ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 107   FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
 108   more details.
 109
 110   You should have received a copy of the GNU General Public License along with
 111   this program; if not, write to the Free Software Foundation, Inc.,
 112   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.