share/man/man4/man4.i386/ray.4

   1 .\"
   2 .\" Copyright (C) 2000
   3 .\" Dr. Duncan McLennan Barclay, dmlb@ragnet.demon.co.uk.
   4 .\"
   5 .\"  All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\" 3. 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 DUNCAN BARCLAY 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 DUNCAN BARCLAY 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$
  32 .\"
  33 .Dd July 16, 2005
  34 .Dt RAY 4 i386
  35 .Os
  36 .Sh NAME
  37 .Nm ray
  38 .Nd "Raytheon Raylink/Webgear Aviator PCCard driver"
  39 .Sh SYNOPSIS
  40 To compile this driver into the kernel,
  41 place the following line in your
  42 kernel configuration file:
  43 .Bd -ragged -offset indent
  44 .Cd "device ray"
  45 .Ed
  46 .Pp
  47 Alternatively, to load the driver as a
  48 module at boot time, place the following line in
  49 .Xr loader.conf 5 :
  50 .Bd -literal -offset indent
  51 if_ray_load="YES"
  52 .Ed
  53 .Sh DESCRIPTION
  54 The
  55 .Nm
  56 driver provides support for
  57 .Tn "Raytheon Raylink"
  58 adapters (commonly available as
  59 .Tn "Webgear Aviator" ,
  60 .Tn "Webgear Aviator Pro"
  61 and
  62 .Tn "Raylink PC Card"
  63 devices.)
  64 The core of the
  65 .Tn Raylink
  66 cards is a frequency hopping PHY with an
  67 .Tn IEEE
  68 802.11
  69 style MAC that interacts with the host using shared memory and mailboxes.
  70 .Pp
  71 The
  72 .Nm
  73 driver currently supports ad-hoc operation mode and the
  74 .Tn Aviator
  75 cards.
  76 Infrastructure mode, interworking with
  77 .Tn "Windows 2000" Ns / Ns Tn Linux Ns / Ns Nx ,
  78 .Tn "Raylink PC Cards"
  79 and
  80 .Tn "Aviator Pros"
  81 is rudimentary and in active development.
  82 The
  83 .Nm
  84 driver currently encapsulates all IP and ARP traffic as
  85 .Tn Ethernet
  86 2 frames within an
  87 .Tn IEEE
  88 802.11
  89 frame.
  90 Other translations will be forthcoming as needed.
  91 Transmit speed is
  92 selectable between 0.5Mbps, 1Mbp , 1.5Mbps or 2Mbps all with auto fallback.
  93 .Pp
  94 By default, the
  95 .Nm
  96 driver configures the card for ad-hoc operation.
  97 In this mode,
  98 stations can communicate amongst each other without the aid of an access
  99 point.
 100 To join a managed service set, the driver must be set for infrastructure mode
 101 using the
 102 .Xr raycontrol 8
 103 utility.
 104 .Pp
 105 There are two known firmware versions; version 4 and version 5.
 106 Version 4 firmware was shipped on the orignal
 107 .Tn "Webgear Aviators"
 108 Version 5 firmware is
 109 used as part of the
 110 .Tn "Windows 2000"
 111 upgrade from
 112 .Tn Webgear
 113 and on the
 114 .Tn "Aviator Pro" ,
 115 and
 116 .Tn "Raylink PC Cards"
 117 cards.
 118 Version 4 is not likely to be 100%
 119 .Tn IEEE
 120 802.11
 121 compliant - version 5 should be.
 122 .Pp
 123 For more information on configuring this device, see
 124 .Xr ifconfig 8
 125 and
 126 .Xr raycontrol 8 .
 127 .Sh DIAGNOSTICS
 128 The following messages occur when there are problems
 129 setting up the memory mapped buffers due to nits in
 130 .Xr pccardd 8 .
 131 .Bl -diag
 132 .It "ray?: pccardd did not map CM - giving up"
 133 See the
 134 .Sx BUGS
 135 section and contact the author for help enclosing a copy
 136 of the output from
 137 .Xr dmesg 8 .
 138 This message only occurs on 3.x systems.
 139 .It "ray?: fixing up CM ..."
 140 .It "ray?: fixing up AM ..."
 141 The driver is fixing up PCCard memory management after mis-configuration
 142 by
 143 .Xr pccardd 8 ,
 144 benign.
 145 .El
 146 .Pp
 147 .Bl -diag
 148 On 4.x and -current systems the following messages can occur when the
 149 memory mapped buffers are set up.
 150 .It "ray?: allocated common memory:"
 151 .It ".  start 0xd0000 count 0xc0000 flags 0x40"
 152 Benign.
 153 .It "ray?: allocated attribute memory:"
 154 .It ".  start 0xdc000 count 0x1000 flags 0x50"
 155 Benign.
 156 .It "ray?: allocated irq:"
 157 .It ".  start 0x9 count 0x1"
 158 Benign.
 159 .It "ray?: Cannot allocate attribute memory"
 160 .It "ray?: Cannot allocate common memory"
 161 .It "ray?: Cannot allocate irq"
 162 .It "ray?: Failed to setup irq"
 163 .It "ray?: CARD_SET_MEMORY_OFFSET returned 0x??"
 164 .It "ray?: CARD_SET_RES_FLAGS returned 0x??"
 165 See the
 166 .Sx BUGS
 167 section and contact the author for help enclosing a copy
 168 of the output from
 169 .Xr dmesg 8
 170 in your email.
 171 .El
 172 .Pp
 173 .Bl -diag
 174 If the kernel is booted with the verbose flag turned on then the
 175 extra information is printed when the driver is probed.
 176 These messages are also seen when the
 177 .Dv RAY_DBG_BOOTPARAM
 178 bit in the
 179 .Dv RAY_DEBUG
 180 option is turned on, as is the case for all existing
 181 versions of the driver.
 182 .It "ray?: memory start 0x???? count 0x???? flags 0x???? offset 0x????"
 183 Description of memory map settings on entry to the driver.
 184 .It "ray?: irq start 0x???? count 0x????"
 185 Description of irq settings on entry to the driver (only on 4.1 and
 186 above).
 187 .El
 188 .Pp
 189 On start-up the driver will report hardware failures thus:
 190 .Bl -diag
 191 .It "ray?: card failed self test: status 0x??<???>"
 192 The card failed to come ready after it was plugged in to the PCCard
 193 slot.
 194 The most common cause of this message is incorrect PCCard memory
 195 management (indicated by a status of 0xff or 0x55).
 196 Bent cards might say that the receiver calibration failed.
 197 If you are brave enough removing the
 198 base of the case can resurrect cards (no warranties etc.).
 199 .It "ray?: unsupported firmware version 0x??"
 200 Self explanatory.
 201 Contact the author for help enclosing a copy
 202 of the output from
 203 .Xr dmesg 8 .
 204 .El
 205 .Pp
 206 The following messages are enabled using the
 207 .Cm debug
 208 option of
 209 .Xr ifconfig 8 .
 210 .Bl -diag
 211 .It "ray?: cannot transmit - not running"
 212 A packet was ready for transmission but the NIC is not connected to a
 213 BSS.
 214 May occur when removing the PCCard.
 215 .It "ray?: cannot transmit - no network"
 216 The wireless NIC has roamed from an access point and not connected with a new
 217 one yet.
 218 .It "ray?: cannot transmit - ECF busy"
 219 The controller firmware was busy when a packet was about to be sent out.
 220 It will be retried automatically.
 221 .It "ray?: mbuf too long ??"
 222 Should never happen, and if it does represents something wrong in the
 223 generic Ethernet driver in the kernel.
 224 .It "ray?: could not pullup ether"
 225 Problem with re-aligning mbufs.
 226 Very unlikely to happen.
 227 .It "ray?: unknown framing type ??"
 228 An impossible error - mail the author.
 229 .It "ray?: could not translate packet"
 230 An error occurred when trying to re-frame a packet for transmission.
 231 .It "ray?: ECF busy, dropping packet"
 232 The NIC was busy just before a packet was to be transmitted.
 233 .It "ray?: tx completed but status is fail"
 234 Typically associated with transmissions to out of range NICs.
 235 .It "ray?: packet too big or too small"
 236 A received packet was impossibly small or too large to fit into an mbuf.
 237 .It "ray?: MGETHDR failed"
 238 The driver could not get a mbuf to store a received packet into.
 239 Try increasing
 240 .Dv MAXUSERS
 241 in your kernel configuration.
 242 .It "ray?: MCLGET failed"
 243 The driver could not get a mbuf to store a received packet into.
 244 Try increasing
 245 .Dv MAXUSERS
 246 in your kernel configuration.
 247 .It "ray?: bad length current 0x?? pktlen 0x??"
 248 The lengths of a fragmented packet were inconsistent.
 249 .It "ray?: bad rcs index 0x??"
 250 The index of the buffer used for part of a fragmented packet is
 251 outside of the usable range.
 252 .It "ray?: header not version 0 fc0 0x??"
 253 The received
 254 .Tn IEEE
 255 802.11
 256 packet had an unknown header type.
 257 Represents link corruption or non standard nodes in the network.
 258 .It "ray?: unknown packet fc0 0x??"
 259 The received
 260 .Tn IEEE
 261 802.11
 262 packet type is unknown.
 263 Represents link corruption or non standard nodes in the network.
 264 .It "ray?: reserved DATA packet subtype 0x??"
 265 The received
 266 .Tn IEEE
 267 802.11
 268 data packet has a reserved (i.e., not allowed) subtype.
 269 Represents link corruption or non standard nodes in the network.
 270 .It "ray?: MGT TODS/FROMDS wrong fc1 0x??"
 271 The received
 272 .Tn IEEE
 273 802.11
 274 management packet had a malformed header.
 275 Represents link corruption or non standard nodes in the network.
 276 .It "ray?: unexpected MGT packet subtype 0x??"
 277 The received
 278 .Tn IEEE
 279 802.11
 280 management packet was of a subtype that the NIC
 281 should have processed.
 282 Benign, but might represent buggy firmware.
 283 .It "ray?: reserved MGT packet subtype 0x??"
 284 The received
 285 .Tn IEEE
 286 802.11
 287 management packet has a reserved (i.e., not allowed)
 288 subtype.
 289 Represents link corruption or non standard nodes in the network.
 290 .It "ray?: open system authentication request"
 291 Self explanatory and for testing
 292 .Tn "Aviator Pro"
 293 interworking.
 294 .It "ray?: authentication failed with status ??"
 295 Self explanatory and currently represents a bug as the driver never
 296 requests authentication.
 297 .It "ray?: shared key authentication request"
 298 Self explanatory and for testing
 299 .Tn "Aviator Pro"
 300 interworking.
 301 .It "ray?: reserved authentication subtype 0x??"
 302 An authentication request has been received for a reserved (i.e., not allowed)
 303 subtype.
 304 Represents link corruption or non standard nodes in the network.
 305 .It "ray?: CTL TODS/FROMDS wrong fc1 0x??"
 306 The received
 307 .Tn IEEE
 308 802.11
 309 management packet had a malformed header.
 310 Represents link corruption or non standard nodes in the network.
 311 .It "ray?: unexpected CTL packet subtype 0x??"
 312 The received
 313 .Tn IEEE
 314 802.11
 315 control packet was of a subtype that the NIC
 316 should have processed.
 317 Benign, but might represent buggy firmware.
 318 .It "ray?: reserved CTL packet subtype 0x??"
 319 The received
 320 .Tn IEEE
 321 802.11
 322 control packet has a reserved (i.e., not allowed)
 323 subtype.
 324 Represents link corruption or non standard nodes in the network.
 325 .It "ray?: bad ccs index 0x??"
 326 The NIC has generated an interrupt with an incorrect control block.
 327 .It "ray?: unexpected UPDATE_APM"
 328 .It "ray?: unexpected TEST_MEM"
 329 .It "ray?: unexpected SHUTDOWN"
 330 .It "ray?: unexpected DUMP_MEM"
 331 .It "ray?: unexpected START_TIMER"
 332 The NIC has generated an interrupt signalling that
 333 the indicated command has completed.
 334 At present these commands are never
 335 issued by the driver, so they represent firmware/hardware/driver bugs.
 336 .It "ray?: unknown command 0x??"
 337 The NIC has generated an interrupt for an unknown command completion.
 338 Represents firmware/hardware/driver bugs.
 339 .It "ray?: unexpected JAPAN_CALL_SIGNAL"
 340 The NIC has generated an interrupt with a control block requesting
 341 processing of a packet that is only ever used in Japanese RCR
 342 certification tests.
 343 Represents firmware/hardware/driver bugs unless you
 344 are trying to certify the NICs in Japan (in which case you would have to
 345 of modified the driver and this manual is out of date).
 346 .It "ray?: spinning"
 347 The controller firmware was busy when a command was about to be issued.
 348 If the driver spins for too long then it will panic.
 349 See the
 350 .Sx BUGS
 351 section for details.
 352 .It "ray?: freeing free ccs 0x??"
 353 Benign warning that may occur when the NIC is ejected.
 354 .El
 355 .Sh SEE ALSO
 356 .Xr arp 4 ,
 357 .Xr netintro 4 ,
 358 .Xr ifconfig 8 ,
 359 .Xr pccardd 8 ,
 360 .Xr raycontrol 8
 361 .Sh HISTORY
 362 The
 363 .Nm
 364 device driver first appeared in
 365 .Fx 3.3 .
 366 .Sh AUTHORS
 367 .An -nosplit
 368 Early versions of this
 369 .Nm
 370 driver were a port of the
 371 .Nx
 372 driver by
 373 .An "Christian E. Hopps" .
 374 The driver
 375 was re-structured by
 376 .An Duncan Barclay Aq dmlb@FreeBSD.org ,
 377 so that
 378 .Xr dhclient 8
 379 would work.
 380 .Sh BUGS
 381 Infra-structure mode is not supported yet.
 382 The driver is likely to panic if it is set into this mode.
 383 Testers are encouraged to contact the
 384 author.
 385 .Pp
 386 Currently
 387 .Fx
 388 has a small problem managing and setting up the correct memory maps.
 389 However, this driver should reset the
 390 memory maps correctly - it works around
 391 .Xr pccardd 8
 392 (where it reads the CIS for common memory, sets it all up
 393 and then throws it all away assuming the card is an
 394 .Xr ed 4
 395 driver...).
 396 Note that this could be dangerous (because it does not interact with
 397 .Xr pccardd 8 )
 398 if you use other memory mapped cards at the same time or have
 399 SCSI cards with on-board BIOS.
 400 .Pp
 401 More encapsulations and translations could be supported, but they have
 402 little value unless someone can demonstrate that the
 403 .Nm
 404 cards will communicate with other manufacturers cards.
 405 Version 4 and
 406 firmware is not
 407 .Tn IEEE
 408 802.11
 409 compliant, but version 5 is.
 410 .Pp
 411 To communicate with
 412 .Tn Windows
 413 machines ensure that the
 414 .Tn Windows
 415 machine
 416 creates the BSS/IBSS.
 417 .Pp
 418 The driver currently panics on some errors that it should recover from.
 419 These will be removed RSN.