Documentation/scsi/53c700.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 =======================
   4 The 53c700 Driver Notes
   5 =======================
   6
   7 General Description
   8 ===================
   9
  10 This driver supports the 53c700 and 53c700-66 chips.  It also supports
  11 the 53c710 but only in 53c700 emulation mode.  It is full featured and
  12 does sync (-66 and 710 only), disconnects and tag command queueing.
  13
  14 Since the 53c700 must be interfaced to a bus, you need to wrapper the
  15 card detector around this driver.  For an example, see the
  16 NCR_D700.[ch] or lasi700.[ch] files.
  17
  18 The comments in the 53c700.[ch] files tell you which parts you need to
  19 fill in to get the driver working.
  20
  21
  22 Compile Time Flags
  23 ==================
  24
  25 A compile time flag is::
  26
  27         CONFIG_53C700_LE_ON_BE
  28
  29 define if the chipset must be supported in little endian mode on a big
  30 endian architecture (used for the 700 on parisc).
  31
  32
  33 Using the Chip Core Driver
  34 ==========================
  35
  36 In order to plumb the 53c700 chip core driver into a working SCSI
  37 driver, you need to know three things about the way the chip is wired
  38 into your system (or expansion card).
  39
  40 1. The clock speed of the SCSI core
  41 2. The interrupt line used
  42 3. The memory (or io space) location of the 53c700 registers.
  43
  44 Optionally, you may also need to know other things, like how to read
  45 the SCSI Id from the card bios or whether the chip is wired for
  46 differential operation.
  47
  48 Usually you can find items 2. and 3. from general spec. documents or
  49 even by examining the configuration of a working driver under another
  50 operating system.
  51
  52 The clock speed is usually buried deep in the technical literature.
  53 It is required because it is used to set up both the synchronous and
  54 asynchronous dividers for the chip.  As a general rule of thumb,
  55 manufacturers set the clock speed at the lowest possible setting
  56 consistent with the best operation of the chip (although some choose
  57 to drive it off the CPU or bus clock rather than going to the expense
  58 of an extra clock chip).  The best operation clock speeds are:
  59
  60 =========  =====
  61 53c700     25MHz
  62 53c700-66  50MHz
  63 53c710     40Mhz
  64 =========  =====
  65
  66 Writing Your Glue Driver
  67 ========================
  68
  69 This will be a standard SCSI driver (I don't know of a good document
  70 describing this, just copy from some other driver) with at least a
  71 detect and release entry.
  72
  73 In the detect routine, you need to allocate a struct
  74 NCR_700_Host_Parameters sized memory area and clear it (so that the
  75 default values for everything are 0).  Then you must fill in the
  76 parameters that matter to you (see below), plumb the NCR_700_intr
  77 routine into the interrupt line and call NCR_700_detect with the host
  78 template and the new parameters as arguments.  You should also call
  79 the relevant request_*_region function and place the register base
  80 address into the 'base' pointer of the host parameters.
  81
  82 In the release routine, you must free the NCR_700_Host_Parameters that
  83 you allocated, call the corresponding release_*_region and free the
  84 interrupt.
  85
  86 Handling Interrupts
  87 -------------------
  88
  89 In general, you should just plumb the card's interrupt line in with
  90
  91 request_irq(irq, NCR_700_intr, <irq flags>, <driver name>, host);
  92
  93 where host is the return from the relevant NCR_700_detect() routine.
  94
  95 You may also write your own interrupt handling routine which calls
  96 NCR_700_intr() directly.  However, you should only really do this if
  97 you have a card with more than one chip on it and you can read a
  98 register to tell which set of chips wants the interrupt.
  99
 100 Settable NCR_700_Host_Parameters
 101 --------------------------------
 102
 103 The following are a list of the user settable parameters:
 104
 105 clock: (MANDATORY)
 106   Set to the clock speed of the chip in MHz.
 107
 108 base: (MANDATORY)
 109   Set to the base of the io or mem region for the register set. On 64
 110   bit architectures this is only 32 bits wide, so the registers must be
 111   mapped into the low 32 bits of memory.
 112
 113 pci_dev: (OPTIONAL)
 114   Set to the PCI board device.  Leave NULL for a non-pci board.  This is
 115   used for the pci_alloc_consistent() and pci_map_*() functions.
 116
 117 dmode_extra: (OPTIONAL, 53c710 only)
 118   Extra flags for the DMODE register.  These are used to control bus
 119   output pins on the 710.  The settings should be a combination of
 120   DMODE_FC1 and DMODE_FC2.  What these pins actually do is entirely up
 121   to the board designer.  Usually it is safe to ignore this setting.
 122
 123 differential: (OPTIONAL)
 124   Set to 1 if the chip drives a differential bus.
 125
 126 force_le_on_be: (OPTIONAL, only if CONFIG_53C700_LE_ON_BE is set)
 127   Set to 1 if the chip is operating in little endian mode on a big
 128   endian architecture.
 129
 130 chip710: (OPTIONAL)
 131   Set to 1 if the chip is a 53c710.
 132
 133 burst_disable: (OPTIONAL, 53c710 only)
 134   Disable 8 byte bursting for DMA transfers.