usr.sbin/stallion/bootcode/stl.4

   1 .\" Copyright (c) 1996-1998 Greg Ungerer (gerg@stallion.oz.au).
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by Greg Ungerer.
  15 .\" 4. Neither the name of the author nor the names of any co-contributors
  16 .\"    may be used to endorse or promote products derived from this software
  17 .\"    without specific prior written permission.
  18 .\"
  19 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  20 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  21 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  22 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  23 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  24 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  25 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  26 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  27 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  28 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  29 .\" SUCH DAMAGE.
  30 .\"
  31 .\" $FreeBSD: src/usr.sbin/stallion/bootcode/stl.4,v 1.8.2.5 2001/12/14 16:41:52 ru Exp $
  32 .\" $DragonFly: src/usr.sbin/stallion/bootcode/stl.4,v 1.9 2007/11/21 19:12:41 swildner Exp $
  33 .\"
  34 .Dd January 8, 1998
  35 .Os
  36 .Dt STL 4 i386
  37 .Sh NAME
  38 .Nm stl ,
  39 .Nm stli
  40 .Nd "drivers for Stallion Technologies multiport serial controllers"
  41 .Sh SYNOPSIS
  42 .Cd "device stl"
  43 .Cd "device stl0 at isa? port <addr> irq <irq>"
  44 .Cd "device stli0 at isa? port <io-addr> iomem <mem-addr> iosiz <size> flags <type> "
  45 .Cd "device stli0 at eisa? port <io-addr> iomem <mem-addr> iosiz <size> flags <type> "
  46 .Sh DESCRIPTION
  47 This is a kernel driver for Stallion Technologies multiport serial boards.
  48 There are two drivers, each supporting a different class of boards.
  49 The
  50 .Nm
  51 driver supports the EasyIO,
  52 EasyConnection 8/32 and
  53 EasyConnection 8/64-PCI boards,
  54 while the
  55 .Nm stli
  56 driver supports all other types, including
  57 ONboard, Brumby and EasyConnection 8/64 (ISA and EISA).
  58 .Sh CONFIGURATION
  59 Each non-PCI board installed in the system needs a configuration entry in the
  60 kernel configuration file.
  61 Slightly different options and parameters are required for each of the
  62 different board types.
  63 Depending on the type of board one of the
  64 .Nm
  65 or
  66 .Nm stli
  67 drivers will be used.  The
  68 .Nm
  69 and
  70 .Nm stli
  71 drivers can support up to 8 boards.
  72 .Pp
  73 Configuration of the hardware - DIP switches, jumpers, etc - varies
  74 from board to board.
  75 Consult documentation supplied with the board for hardware
  76 configuration details.
  77 Alternatively the board documentation is available on Stallion
  78 Technologies WWW site at
  79 .Pa http://www.stallion.com .
  80 .Pp
  81 The EasyIO, EasyConnection 8/32 and EasyConnection 8/64-PCI
  82 families of boards use the
  83 .Nm
  84 driver.
  85 ISA board configuration entries for the
  86 .Nm
  87 driver take the general form of:
  88 .Pp
  89 .Cd "device stlX at isa? port <io-addr> irq <irq>"
  90 .Pp
  91 .Ar X
  92 is the unit number assigned to the board.
  93 Any unique value between 0 and 7 is valid.
  94 .Pp
  95 The I/O address used by the board is specified by
  96 .Ar <io-addr> .
  97 Each of the EasyIO and EasyConnection 8/32-AT boards can use
  98 an I/O address in the range from 0 to 0x400.
  99 .Pp
 100 All EasyIO and EasyConnection 8/32 boards require an interrupt,
 101 and this interrupt is specified by
 102 .Ar <irq> .
 103 Legal IRQ values for the ISA boards are 3, 4, 5, 7, 10, 11, 12 and 15.
 104 Interrupts are software programmed on all boards except the EasyIO-8M.
 105 .Pp
 106 The EasyConnection 8/32-AT board uses a secondary I/O address region,
 107 and this is fixed at address 0x280 in the driver code.
 108 All EasyConnection 8/32-AT boards may share the same secondary address
 109 region.
 110 .Pp
 111 All EasyIO and EasyConnection PCI boards are detected
 112 automatically by the drivers on boot up.
 113 No configuration information is required in advance for these
 114 board types.
 115 During boot up the
 116 .Nm
 117 driver will issue messages to indicate that a Stallion
 118 PCI board was found, and some information about it.
 119 If no ISA card is being configured, an entry like
 120 .Pp
 121 .Cd "device stl"
 122 .Pp
 123 will include the driver for PCI cards only.
 124 .Pp
 125 Following are some examples of configuration entries for each of the ISA
 126 boards supported by the
 127 .Nm
 128 driver.
 129 Each example also describes some important details about each of the
 130 board types.
 131 .Pp
 132 Each EasyIO board requires 8 bytes of I/O address space and 1 IRQ line.
 133 A configuration entry for an EasyIO board would look like:
 134 .Pp
 135 .Cd "device stl0 at isa? port 0x2a8 irq 15"
 136 .Pp
 137 This entry specifies an EasyIO board at I/O address 0x2a8 using IRQ 15.
 138 The I/O and IRQ values can be modified as required.
 139 .Pp
 140 Each EasyConnection 8/32-AT board requires 2 sets of I/O addresses
 141 and 1 IRQ line.
 142 The primary I/O address range is 2 bytes in size, and must be unique
 143 to each EasyConnection 8/32-AT board in the system.
 144 The secondary I/O address range is 32 bytes in size, but can be shared
 145 by multiple EasyConnection 8/32-AT boards.
 146 This secondary I/O address is set at 0x280 in the driver code.
 147 A configuration entry would look like:
 148 .Pp
 149 .Cd "device stl0 at isa? port 0x2a0 irq 10"
 150 .Pp
 151 This specifies an EasyConnection 8/32-AT with primary I/O address 0x2a0,
 152 secondary I/O address of 0x280 and IRQ 10.
 153 .Pp
 154 The ONboard, Brumby and EasyConnection 8/64
 155 families of boards use the
 156 .Nm stli
 157 driver.  The
 158 .Nm stli
 159 driver supports the ISA and EISA members of these families.
 160 .Pp
 161 ISA board configuration entries for the
 162 .Nm stli
 163 driver take the general form of:
 164 .Pp
 165 .Cd "device stliX at isa? port <io-addr> iomem <mem-addr> iosiz <size> flags <type>"
 166 .Pp
 167 .Ar X
 168 is the unit number assigned to the board.
 169 Any unique value between 0 and 7 is valid.
 170 .Pp
 171 The I/O address used by the board is specified by
 172 .Ar <io-addr> .
 173 Each of the different supported board types has restrictions on valid
 174 I/O addresses and also the amount of I/O space required varies between
 175 the boards.
 176 .Pp
 177 All boards using the
 178 .Nm stli
 179 driver require a shared memory region to operate.
 180 Depending on the board type the region required varies in size
 181 from 4 kbytes to 64 kbytes.  The size of the board region is specified
 182 by field
 183 .Ar <size>
 184 of the configuration entry, and the address of the region is specified by
 185 .Ar <mem-addr> .
 186 .Pp
 187 The flags field specifies the particular board type that this entry
 188 applies to.
 189 Not all board types are distinguishable by the driver at runtime,
 190 so this field is required by the driver.
 191 Valid board types are:
 192 .Bd -literal -offset indent
 193 BOARD NAME                      TYPE    I/O SIZE
 194
 195 Brumby                            2     0x4000
 196 ONboard                           4     0x10000
 197 ONboard/E                         7     0x10000
 198 EasyConnection 8/64-AT           23     0x1000
 199 EasyConnection 8/64-EISA         24     0x10000
 200 .Ed
 201 .Pp
 202 Following are some examples of configuration entries for each of the
 203 boards supported by the
 204 .Nm stli
 205 driver. Each example also describes some important details about
 206 each of the board types.
 207 .Pp
 208 The EasyConnection 8/64-AT board requires 4 bytes of I/O address space and
 209 4 kbytes of memory space.
 210 A configuration entry would look like:
 211 .Pp
 212 .Cd "device stli0 at isa? port 0x2a0 iomem 0xcc000 iosiz 0x1000 flags 23"
 213 .Pp
 214 The flags field of this entry specifies that this is an
 215 EasyConnection 8/64-AT board.
 216 It is set to I/O address 0x2a0 and memory address 0xcc000.
 217 The
 218 .Ar iosiz
 219 parameter specifies a memory region size
 220 of 4 kbytes.
 221 .Pp
 222 The EasyConnection 8/64-EISA board requires a 64 kbyte region of
 223 memory space.
 224 This region can be anywhere in the 32 bit memory address space.
 225 A configuration entry would be like:
 226 .Pp
 227 .Cd "device stli0 at eisa? port 0x2000 iomem 0x80000000 iosiz 0x10000 flags 24"
 228 .Pp
 229 The flags field is used to specify that this is an EasyConnection 8/64-EISA
 230 board.
 231 The I/O (port) address resource is derived from the EISA slot that
 232 the board is in.
 233 Each EISA slot is allocated a section of the I/O address space by the
 234 hardware of the system.
 235 That address being 0xX000 where X is the slot number.
 236 The example board is at memory address 0x80000000 which is 2 Gbyte.
 237 The
 238 .Ar iosiz
 239 parameter specifies the size of the memory region,
 240 in this case 64 kbytes.
 241 .Pp
 242 Each ONboard ISA board requires 16 bytes of I/O space and a 64 kbyte
 243 section of memory address space.
 244 Valid ONboard I/O addresses are in the range 0x200 to 0x300.
 245 A configuration entry for an ONboard ISA would look like:
 246 .Pp
 247 .Cd "device stli0 at isa? port 0x240 iomem 0xd0000 iosiz 0x10000 flags 4"
 248 .Pp
 249 This entry specifies an ONboard ISA by setting flags to 4.
 250 It uses I/O address 0x240 and a memory region of 64 kbytes at memory
 251 address 0xd0000.
 252 .Pp
 253 Each ONboard/E board requires a 64 kbyte memory region, and this
 254 can be anywhere in the 32 bit address space (that is from 0 to 4 Gbyte).
 255 A configuration entry would look like:
 256 .Pp
 257 .Cd "device stli0 at eisa? port 0x3000 iomem 0xc0000000 iosiz 0x10000 flags 7"
 258 .Pp
 259 The specifies an ONboard/E in slot 3 using a shared memory address
 260 of 0xc0000000 (3 Gbyte).
 261 .Pp
 262 Each Brumby board requires 16 bytes of I/O address space and a 4 kbyte
 263 region of shared memory space.
 264 The valid Brumby I/O addresses are in the range 0x300 to 0x400.
 265 The shared memory region of the Brumby must be in the 0xc0000 to
 266 0xdc000 region of the memory address space.
 267 A configuration entry for a Brumby would be like:
 268 .Pp
 269 .Cd "device stli0 at isa? port 0x360 iomem 0xc8000 iosiz 0x4000 flags 2"
 270 .Pp
 271 This specifies a Brumby board at I/O address 0x360 using a shared memory
 272 region at address 0xc8000.
 273 .Sh NOTES
 274 When building the device nodes for the ports be sure to use the correct
 275 driver name,
 276 .Nm
 277 or
 278 .Nm stli .
 279 Each driver has a separate major number allocated,
 280 so even though the port device names are the same for each driver,
 281 the major number of the device node is different.
 282 Use the
 283 .Xr MAKEDEV 8
 284 script to create the devices.
 285 Use the ttyE and cue tag for the
 286 .Nm
 287 driver, and
 288 the ttyEi and cuei tags for the
 289 .Nm stli
 290 driver.
 291 .Pp
 292 The intelligent board types (ONboard, Brumby and
 293 EasyConnection 8/64 (ISA and EISA))
 294 require a firmware download before the ports will be operational.
 295 This is achieved by using the
 296 .Nm stlload
 297 command.
 298 See its manual page for details on usage.
 299 .Sh FILES
 300 .Bl -tag -width "/dev/staliomem?" -compact
 301 .It Pa /dev/ttyE?
 302 stl standard callin devices
 303 .It Pa /dev/ttyiE?
 304 stl initial-state callin devices
 305 .It Pa /dev/ttylE?
 306 stl lock-state callin devices
 307 .It Pa /dev/cuaE?
 308 stl standard callout devices
 309 .It Pa /dev/cuaiE?
 310 stl initial-state callout devices
 311 .It Pa /dev/cualE?
 312 stl lock-state callout devices
 313 .It Pa /dev/ttyF?
 314 stli standard callin devices
 315 .It Pa /dev/ttyiF?
 316 stli initial-state callin devices
 317 .It Pa /dev/ttylF?
 318 stli lock-state callin devices
 319 .It Pa /dev/cuaF?
 320 stli standard callout devices
 321 .It Pa /dev/cuaiF?
 322 stli initial-state callout devices
 323 .It Pa /dev/cualF?
 324 stli lock-state callout devices
 325 .It Pa /dev/staliomem?
 326 board control device
 327 .El
 328 .Pp
 329 Note that the port numbers start at 0 for port 0 of board 0.
 330 Each board has 64 port slots allocated for it.
 331 So the second boards ports start at 64 and go through 127.
 332 Use the
 333 .Xr MAKEDEV 8
 334 script to create the devices.
 335 Use the
 336 .Ar ttyEx
 337 and
 338 .Ar cuaEx
 339 tag for the
 340 .Nm
 341 driver, and
 342 the
 343 .Ar ttyFx
 344 and
 345 .Ar cuaFx
 346 tags for the
 347 .Nm stli
 348 driver, where
 349 .Ar x
 350 is the board number.
 351 By default,
 352 .Xr MAKEDEV 8
 353 only creates 8 devices per board (to keep the directory size
 354 reasonable).
 355 To create the remaining devices for EasyConnection 8/32 and
 356 EasyConnection 8/64 cards, see the comments in the
 357 .Xr MAKEDEV 8
 358 script.
 359 .Sh SEE ALSO
 360 .Xr stty 1 ,
 361 .Xr termios 4 ,
 362 .Xr tty 4 ,
 363 .Xr comcontrol 8 ,
 364 .Xr MAKEDEV 8 ,
 365 .Xr stlload 8 ,
 366 .Xr stlstats 8 ,
 367 .Xr stlstty 8
 368 .Sh HISTORY
 369 This driver was originally developed by Greg Ungerer (gerg@stallion.com).
 370 .Sh BUGS
 371 The /dev/staliomem? device name is shared between both the
 372 .Nm
 373 and
 374 .Nm stli
 375 drivers.  This may cause confusion if both drivers are present in the
 376 system at the same time.
 377 .Pp
 378 Device names use integer suffixes, rather than the 0-9 a-z sequence
 379 that other drivers use.
 380 .Pp
 381 There will be many unused ttyE device names in a system with more than
 382 one card.