Documentation/hayes-esp.txt

   1 HAYES ESP DRIVER VERSION 2.0
   2
   3 A big thanks to the people at Hayes, especially Alan Adamson.  Their support
   4 has enabled me to provide enhancements to the driver.
   5
   6 Please report your experiences with this driver to me (arobinso@nyx.net).  I
   7 am looking for both positive and negative feedback.
   8
   9 *** IMPORTANT CHANGES FOR 2.0 ***
  10 Support for PIO mode.  Five situations will cause PIO mode to be used:
  11 1) A multiport card is detected.  PIO mode will always be used.  (8 port cards
  12 do not support DMA).
  13 2) The DMA channel is set to an invalid value (anything other than 1 or 3).
  14 3) The DMA buffer/channel could not be allocated.  The port will revert to PIO
  15 mode until it is reopened.
  16 4) Less than 33 bytes need to be transferred to/from the FIFOs.  PIO mode will
  17 be used for that transfer only.
  18 5) A port needs to do a DMA transfer and another port is already using the
  19 DMA channel.  PIO mode will be used for that transfer only.
  20
  21 A patch for setserial (2.12) is included to allow the ESP enhanced mode
  22 configuration to be viewed and changed.
  23 ***
  24
  25 This package contains the files needed to compile a module to support the Hayes
  26 ESP card.  The drivers are basically a modified version of the serial drivers.
  27
  28 Features:
  29
  30 - Uses the enhanced mode of the ESP card, allowing a wider range of
  31   interrupts and features than compatibilty mode
  32 - Uses DMA and 16 bit PIO mode to transfer data to and from the ESP's FIFOs,
  33   reducing CPU load
  34 - Supports primary and secondary ports
  35
  36 To compile/install:
  37
  38 Examine the first section of esp.h to verify that the definitions are
  39 acceptable.  If they are not, change them.
  40 DMA_CHANNEL must be either 1 or 3.
  41 ESP_BH should be set to a value not in use by the system.  If the system
  42 is not configured with RISCOM8 support, the default should be fine.
  43
  44 Examine the Makefile, and make any appropriate changes.
  45
  46 Type 'make' to compile the module.  The module will be called 'esp.o'.  Typing
  47 'make install' will install the module in /lib/modules/misc.  The module can
  48 be inserted and removed as usual (insmod, rmmod, etc.).  The IRQs to use can
  49 be specified by using the irq= option.  The format is:
  50
  51 irq=[0x100],[0x140],[0x180],[0x200],[0x240],[0x280],[0x300],[0x380]
  52
  53 The address in brackets is the base address of the card.  The IRQ of
  54 nonexistent cards can be set to 0.  If an IRQ of a card that does exist is set
  55 to 0, the driver will attempt to guess at the correct IRQ.  For example, to set
  56 the IRQ of the card at address 0x300 to 12, the insmod command would be:
  57
  58 insmod esp irq=0,0,0,0,0,0,12,0
  59
  60 The custom divisor can be set by using the divisor= option.  The format is the
  61 same as for the irq= option.  Each divisor value is a series of hex digits,
  62 with each digit representing the divisor to use for a corresponding port.  The
  63 divisor value is constructed RIGHT TO LEFT.  Specifying a nonzero divisor value
  64 will automatically set the spd_cust flag.  To calculate the divisor to use for
  65 a certain baud rate, divide the port's base baud (generally 921600) by the
  66 desired rate.  For example, to set the divisor of the primary port at 0x300 to
  67 4 and the divisor of the secondary port at 0x308 to 8, the insmod command would
  68 be:
  69
  70 insmod esp divisor=0,0,0,0,0,0,0x84,0
  71
  72 The dma= option can be used to set the DMA channel.  The channel can be either
  73 1 or 3.  Specifying any other value will force the driver to use PIO mode.
  74 For example, to set the dma channel to 3, the insmod command would be:
  75
  76 insmod esp dma=3
  77
  78 The rx_trigger= and tx_trigger= options can be used to set the FIFO trigger
  79 levels.  They specifie when the ESP card should send an interrupt.  Larger
  80 values will decrease the number of interrupts; however, a value too high may
  81 result in data loss.  Valid values are 1 through 1023, with 768 being the
  82 default.  For example, to set the receive trigger level to 512 bytes and the
  83 transmit trigger level to 700 bytes, the insmod command would be:
  84
  85 insmod esp rx_trigger=512 tx_trigger=700
  86
  87 The flow_off= and flow_on= options can be used to set the hardware flow off/
  88 flow on levels.  The flow on level must be lower than the flow off level, and
  89 the flow off level should be higher than rx_trigger.  Valid values are 1
  90 through 1023, with 1016 being the default flow off level and 944 being the
  91 default flow on level.  For example, to set the flow off level to 1000 bytes
  92 and the flow on level to 935 bytes, the insmod command would be:
  93
  94 insmod esp flow_off=1000 flow_on=935
  95
  96 The rx_timeout= option can be used to set the receive timeout value.  This
  97 value indicates how long after receiving the last character that the ESP card
  98 should wait before signalling an interrupt.  Valid values are 0 though 255,
  99 with 128 being the default.  A value too high will increase latency, and a
 100 value too low will cause unnecessary interrupts.  For example, to set the
 101 receive timeout to 255, the insmod command would be:
 102
 103 insmod esp rx_timeout=255
 104
 105 Multiple options can be listed on the insmod command line by separating each
 106 option with a space.  For example:
 107
 108 insmod esp dma=3 trigger=512
 109
 110 The esp module can be automatically loaded when needed.  To cause this to
 111 happen, add the following lines to /etc/conf.modules (replacing the last line
 112 with options for your configuration):
 113
 114 alias char-major-57 esp
 115 alias char-major-58 esp
 116 options esp irq=0,0,0,0,0,0,3,0 divisor=0,0,0,0,0,0,0x4,0
 117
 118 You may also need to run 'depmod -a'.
 119
 120 Devices must be created manually.  To create the devices, note the output from
 121 the module after it is inserted.  The output will appear in the location where
 122 kernel messages usually appear (usually /var/adm/messages).  Create two devices
 123 for each 'tty' mentioned, one with major of 57 and the other with major of 58.
 124 The minor number should be the same as the tty number reported.  The commands
 125 would be (replace ? with the tty number):
 126
 127 mknod /dev/ttyP? c 57 ?
 128 mknod /dev/cup? c 58 ?
 129
 130 For example, if the following line appears:
 131
 132 Oct 24 18:17:23 techno kernel: ttyP8 at 0x0140 (irq = 3) is an ESP primary port
 133
 134 ...two devices should be created:
 135
 136 mknod /dev/ttyP8 c 57 8
 137 mknod /dev/cup8 c 58 8
 138
 139 You may need to set the permissions on the devices:
 140
 141 chmod 666 /dev/ttyP*
 142 chmod 666 /dev/cup*
 143
 144 The ESP module and the serial module should not conflict (they can be used at
 145 the same time).  After the ESP module has been loaded the ports on the ESP card
 146 will no longer be accessable by the serial driver.
 147
 148 If I/O errors are experienced when accessing the port, check for IRQ and DMA
 149 conflicts ('cat /proc/interrupts' and 'cat /proc/dma' for a list of IRQs and
 150 DMAs currently in use).
 151
 152 Enjoy!
 153 Andrew J. Robinson <arobinso@nyx.net>