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