share/man/man9/usbdi.9

   1 .\"
   2 .\" Copyright (c) 2005 Ian Dowse <iedowse@FreeBSD.org>
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD: src/share/man/man9/usbdi.9,v 1.2 2006/12/14 14:33:13 mpp Exp $
  27 .Dd December 30, 2005
  28 .Os
  29 .Dt USBDI 9
  30 .Sh NAME
  31 .Nm usb_detach_wait ,
  32 .Nm usb_detach_wakeup ,
  33 .Nm usb_find_desc ,
  34 .Nm usbd_abort_default_pipe ,
  35 .Nm usbd_abort_pipe ,
  36 .Nm usbd_alloc_buffer ,
  37 .Nm usbd_alloc_xfer ,
  38 .Nm usbd_bulk_transfer ,
  39 .Nm usbd_clear_endpoint_stall ,
  40 .Nm usbd_clear_endpoint_stall_async ,
  41 .Nm usbd_clear_endpoint_toggle ,
  42 .Nm usbd_close_pipe ,
  43 .Nm usbd_device2interface_handle ,
  44 .Nm usbd_devinfo ,
  45 .Nm usbd_do_request ,
  46 .Nm usbd_do_request_async ,
  47 .Nm usbd_do_request_flags ,
  48 .Nm usbd_do_request_flags_pipe ,
  49 .Nm usbd_dopoll ,
  50 .Nm usbd_endpoint_count ,
  51 .Nm usbd_errstr ,
  52 .Nm usbd_fill_deviceinfo ,
  53 .Nm usbd_find_edesc ,
  54 .Nm usbd_find_idesc ,
  55 .Nm usbd_free_buffer ,
  56 .Nm usbd_free_xfer ,
  57 .Nm usbd_get_buffer ,
  58 .Nm usbd_get_config ,
  59 .Nm usbd_get_config_desc ,
  60 .Nm usbd_get_config_desc_full ,
  61 .Nm usbd_get_config_descriptor ,
  62 .Nm usbd_get_device_descriptor ,
  63 .Nm usbd_get_endpoint_descriptor ,
  64 .Nm usbd_get_interface_altindex ,
  65 .Nm usbd_get_interface_descriptor ,
  66 .Nm usbd_get_no_alts ,
  67 .Nm usbd_get_quirks ,
  68 .Nm usbd_get_speed ,
  69 .Nm usbd_get_string ,
  70 .Nm usbd_get_string_desc ,
  71 .Nm usbd_get_xfer_status ,
  72 .Nm usbd_interface2device_handle ,
  73 .Nm usbd_interface2endpoint_descriptor ,
  74 .Nm usbd_interface_count ,
  75 .Nm usbd_intr_transfer ,
  76 .Nm usbd_open_pipe ,
  77 .Nm usbd_open_pipe_intr ,
  78 .Nm usbd_pipe2device_handle ,
  79 .Nm usbd_ratecheck ,
  80 .Nm usbd_set_config_index ,
  81 .Nm usbd_set_config_no ,
  82 .Nm usbd_set_interface ,
  83 .Nm usbd_set_polling ,
  84 .Nm usbd_setup_default_xfer ,
  85 .Nm usbd_setup_isoc_xfer ,
  86 .Nm usbd_setup_xfer ,
  87 .Nm usbd_sync_transfer ,
  88 .Nm usbd_transfer
  89 .Nd Universal Serial Bus driver programming interface
  90 .Sh SYNOPSIS
  91 .In sys/bus.h
  92 .In sys/module.h
  93 .In bus/usb/usb.h
  94 .In bus/usb/usbdi.h
  95 .In bus/usb/usbdi_util.h
  96 .Pp
  97 .Ft void
  98 .Fn usb_detach_wait "device_t dv"
  99 .Ft void
 100 .Fn usb_detach_wakeup "device_t dv"
 101 .Ft "const usb_descriptor_t *"
 102 .Fn usb_find_desc "usbd_device_handle dev" "int type" "int subtype"
 103 .Ft usbd_status
 104 .Fn usbd_abort_default_pipe "usbd_device_handle dev"
 105 .Ft usbd_status
 106 .Fn usbd_abort_pipe "usbd_pipe_handle pipe"
 107 .Ft "void *"
 108 .Fn usbd_alloc_buffer "usbd_xfer_handle xfer" "u_int32_t size"
 109 .Ft usbd_xfer_handle
 110 .Fn usbd_alloc_xfer "usbd_device_handle dev"
 111 .Ft usbd_status
 112 .Fo usbd_bulk_transfer
 113 .Fa "usbd_xfer_handle xfer"
 114 .Fa "usbd_pipe_handle pipe"
 115 .Fa "u_int16_t flags"
 116 .Fa "u_int32_t timeout"
 117 .Fa "void *buf"
 118 .Fa "u_int32_t *size"
 119 .Fa "char *lbl"
 120 .Fc
 121 .Ft usbd_status
 122 .Fn usbd_clear_endpoint_stall "usbd_pipe_handle pipe"
 123 .Ft usbd_status
 124 .Fn usbd_clear_endpoint_stall_async "usbd_pipe_handle pipe"
 125 .Ft void
 126 .Fn usbd_clear_endpoint_toggle "usbd_pipe_handle pipe"
 127 .Ft usbd_status
 128 .Fn usbd_close_pipe "usbd_pipe_handle pipe"
 129 .Ft usbd_status
 130 .Fo usbd_device2interface_handle
 131 .Fa "usbd_device_handle dev"
 132 .Fa "u_int8_t ifaceno"
 133 .Fa "usbd_interface_handle *iface"
 134 .Fc
 135 .Ft void
 136 .Fn usbd_devinfo "usbd_device_handle dev" "int showclass" "char *cp"
 137 .Ft usbd_status
 138 .Fo usbd_do_request
 139 .Fa "usbd_device_handle dev"
 140 .Fa "usb_device_request_t *req"
 141 .Fa "void *data"
 142 .Fc
 143 .Ft usbd_status
 144 .Fo usbd_do_request_async
 145 .Fa "usbd_device_handle dev"
 146 .Fa "usb_device_request_t *req"
 147 .Fa "void *data"
 148 .Fc
 149 .Ft usbd_status
 150 .Fo usbd_do_request_flags
 151 .Fa "usbd_device_handle dev"
 152 .Fa "usb_device_request_t *req"
 153 .Fa "void *data"
 154 .Fa "u_int16_t flags"
 155 .Fa "int *actlen"
 156 .Fa "u_int32_t timo"
 157 .Fc
 158 .Ft usbd_status
 159 .Fo usbd_do_request_flags_pipe
 160 .Fa "usbd_device_handle dev"
 161 .Fa "usbd_pipe_handle pipe"
 162 .Fa "usb_device_request_t *req"
 163 .Fa "void *data"
 164 .Fa "u_int16_t flags"
 165 .Fa "int *actlen"
 166 .Fa "u_int32_t timeout"
 167 .Fc
 168 .Ft void
 169 .Fn usbd_dopoll "usbd_interface_handle iface"
 170 .Ft usbd_status
 171 .Fn usbd_endpoint_count "usbd_interface_handle iface" "u_int8_t *count"
 172 .Ft "const char *"
 173 .Fn usbd_errstr "usbd_status err"
 174 .Ft void
 175 .Fo usbd_fill_deviceinfo
 176 .Fa "usbd_device_handle dev"
 177 .Fa "struct usb_device_info *di"
 178 .Fa "int usedev"
 179 .Fc
 180 .Ft "usb_endpoint_descriptor_t *"
 181 .Fo usbd_find_edesc
 182 .Fa "usb_config_descriptor_t *cd"
 183 .Fa "int ifaceidx"
 184 .Fa "int altidx"
 185 .Fa "int endptidx"
 186 .Fc
 187 .Ft "usb_interface_descriptor_t *"
 188 .Fn usbd_find_idesc "usb_config_descriptor_t *cd" "int ifaceidx" "int altidx"
 189 .Ft void
 190 .Fn usbd_free_buffer "usbd_xfer_handle xfer"
 191 .Ft usbd_status
 192 .Fn usbd_free_xfer "usbd_xfer_handle xfer"
 193 .Ft "void *"
 194 .Fn usbd_get_buffer "usbd_xfer_handle xfer"
 195 .Ft usbd_status
 196 .Fn usbd_get_config "usbd_device_handle dev" "u_int8_t *conf"
 197 .Ft usbd_status
 198 .Fo usbd_get_config_desc
 199 .Fa "usbd_device_handle dev"
 200 .Fa "int confidx"
 201 .Fa "usb_config_descriptor_t *d"
 202 .Fc
 203 .Ft usbd_status
 204 .Fo usbd_get_config_desc_full
 205 .Fa "usbd_device_handle dev"
 206 .Fa "int conf"
 207 .Fa "void *d"
 208 .Fa "int size"
 209 .Fc
 210 .Ft "usb_config_descriptor_t *"
 211 .Fn usbd_get_config_descriptor "usbd_device_handle dev"
 212 .Ft "usb_device_descriptor_t *"
 213 .Fn usbd_get_device_descriptor "usbd_device_handle dev"
 214 .Ft "usb_endpoint_descriptor_t *"
 215 .Fo usbd_get_endpoint_descriptor
 216 .Fa "usbd_interface_handle iface"
 217 .Fa "u_int8_t address"
 218 .Fc
 219 .Ft int
 220 .Fn usbd_get_interface_altindex "usbd_interface_handle iface"
 221 .Ft "usb_interface_descriptor_t *"
 222 .Fn usbd_get_interface_descriptor "usbd_interface_handle iface"
 223 .Ft int
 224 .Fn usbd_get_no_alts "usb_config_descriptor_t *cdesc" "int ifaceno"
 225 .Ft "const struct usbd_quirks *"
 226 .Fn usbd_get_quirks "usbd_device_handle dev"
 227 .Ft int
 228 .Fn usbd_get_speed "usbd_device_handle dev"
 229 .Ft usbd_status
 230 .Fn usbd_get_string "usbd_device_handle dev" "int si" "char *buf"
 231 .Ft usbd_status
 232 .Fo usbd_get_string_desc
 233 .Fa "usbd_device_handle dev"
 234 .Fa "int sindex"
 235 .Fa "int langid"
 236 .Fa "usb_string_descriptor_t *sdesc"
 237 .Fa "int *sizep"
 238 .Fc
 239 .Ft void
 240 .Fo usbd_get_xfer_status
 241 .Fa "usbd_xfer_handle xfer"
 242 .Fa "usbd_private_handle *priv"
 243 .Fa "void **buffer"
 244 .Fa "u_int32_t *count"
 245 .Fa "usbd_status *status"
 246 .Fc
 247 .Ft void
 248 .Fo usbd_interface2device_handle
 249 .Fa "usbd_interface_handle iface"
 250 .Fa "usbd_device_handle *dev"
 251 .Fc
 252 .Ft "usb_endpoint_descriptor_t *"
 253 .Fo usbd_interface2endpoint_descriptor
 254 .Fa "usbd_interface_handle iface"
 255 .Fa "u_int8_t index"
 256 .Fc
 257 .Ft usbd_status
 258 .Fn usbd_interface_count "usbd_device_handle dev" "u_int8_t *count"
 259 .Ft usbd_status
 260 .Fo usbd_intr_transfer
 261 .Fa "usbd_xfer_handle xfer"
 262 .Fa "usbd_pipe_handle pipe"
 263 .Fa "u_int16_t flags"
 264 .Fa "u_int32_t timeout"
 265 .Fa "void *buf"
 266 .Fa "u_int32_t *size"
 267 .Fa "char *lbl"
 268 .Fc
 269 .Ft usbd_status
 270 .Fo usbd_open_pipe
 271 .Fa "usbd_interface_handle iface"
 272 .Fa "u_int8_t address"
 273 .Fa "u_int8_t flags"
 274 .Fa "usbd_pipe_handle *pipe"
 275 .Fc
 276 .Ft usbd_status
 277 .Fo usbd_open_pipe_intr
 278 .Fa "usbd_interface_handle iface"
 279 .Fa "u_int8_t address"
 280 .Fa "u_int8_t flags"
 281 .Fa "usbd_pipe_handle *pipe"
 282 .Fa "usbd_private_handle priv"
 283 .Fa "void *buffer"
 284 .Fa "u_int32_t len"
 285 .Fa "usbd_callback cb"
 286 .Fa "int ival"
 287 .Fc
 288 .Ft usbd_device_handle
 289 .Fn usbd_pipe2device_handle "usbd_pipe_handle pipe"
 290 .Ft int
 291 .Fn usbd_ratecheck "struct timeval *last"
 292 .Ft usbd_status
 293 .Fn usbd_set_config_index "usbd_device_handle dev" "int index" "int msg"
 294 .Ft usbd_status
 295 .Fn usbd_set_config_no "usbd_device_handle dev" "int no" "int msg"
 296 .Ft usbd_status
 297 .Fn usbd_set_interface "usbd_interface_handle iface" "int altidx"
 298 .Ft void
 299 .Fn usbd_set_polling "usbd_device_handle dev" "int on"
 300 .Ft void
 301 .Fo usbd_setup_default_xfer
 302 .Fa "usbd_xfer_handle xfer"
 303 .Fa "usbd_device_handle dev"
 304 .Fa "usbd_private_handle priv"
 305 .Fa "u_int32_t timeout"
 306 .Fa "usb_device_request_t *req"
 307 .Fa "void *buffer"
 308 .Fa "u_int32_t length"
 309 .Fa "u_int16_t flags"
 310 .Fa "usbd_callback callback"
 311 .Fc
 312 .Ft void
 313 .Fo usbd_setup_isoc_xfer
 314 .Fa "usbd_xfer_handle xfer"
 315 .Fa "usbd_pipe_handle pipe"
 316 .Fa "usbd_private_handle priv"
 317 .Fa "u_int16_t *frlengths"
 318 .Fa "u_int32_t nframes"
 319 .Fa "u_int16_t flags"
 320 .Fa "usbd_callback callback"
 321 .Fc
 322 .Ft void
 323 .Fo usbd_setup_xfer
 324 .Fa "usbd_xfer_handle xfer"
 325 .Fa "usbd_pipe_handle pipe"
 326 .Fa "usbd_private_handle priv"
 327 .Fa "void *buffer"
 328 .Fa "u_int32_t length"
 329 .Fa "u_int16_t flags"
 330 .Fa "u_int32_t timeout"
 331 .Fa "usbd_callback callback"
 332 .Fc
 333 .Ft usbd_status
 334 .Fn usbd_sync_transfer "usbd_xfer_handle xfer"
 335 .Ft usbd_status
 336 .Fn usbd_transfer "usbd_xfer_handle xfer"
 337 .Sh DESCRIPTION
 338 The Universal Serial Bus (USB) driver programming interface provides
 339 USB peripheral drivers with a host controller independent API for
 340 controlling and communicating with USB peripherals.
 341 .Pp
 342 Typically, drivers will first use some combination of the functions
 343 .Fn usbd_set_config_no ,
 344 .Fn usbd_get_config_descriptor ,
 345 .Fn usbd_set_interface ,
 346 .Fn usbd_get_interface_descriptor ,
 347 .Fn usbd_device2interface_handle ,
 348 .Fn usbd_endpoint_count
 349 and
 350 .Fn usbd_interface2endpoint_descriptor
 351 to query the device's properties and prepare it for use.
 352 Drivers can then perform requests on the USB control pipe using
 353 .Fn usbd_do_request ,
 354 they can open pipes using the functions
 355 .Fn usbd_open_pipe
 356 and
 357 .Fn usbd_open_pipe_intr ,
 358 and perform transfers over these pipes using
 359 .Fn usbd_alloc_xfer ,
 360 .Fn usbd_setup_xfer
 361 and
 362 .Fn usbd_transfer .
 363 Finally, the functions
 364 .Fn usbd_abort_pipe ,
 365 .Fn usbd_close_pipe
 366 and
 367 .Fn usbd_free_xfer
 368 are used to cancel outstanding transfers, close open pipes and deallocate
 369 transfer structures.
 370 .Pp
 371 The
 372 .Fn usbd_get_device_descriptor
 373 function returns a pointer to the USB device descriptor for
 374 .Fa dev .
 375 See
 376 .Sx "USB Descriptors"
 377 below for information about the USB device descriptor.
 378 .Pp
 379 The
 380 .Fn usbd_get_config_desc
 381 function retrieves the specified configuration descriptor from the device.
 382 The
 383 .Fa confidx
 384 parameter specifies the configuration descriptor index, which must be less
 385 than the
 386 .Fa bNumConfigurations
 387 value in the device descriptor.
 388 The function
 389 .Fn usbd_get_config_desc_full
 390 retrieves a full configuration descriptor, which has all related interface
 391 and endpoint descriptors appended to a normal configuration descriptor.
 392 The parameter
 393 .Fa d
 394 should point to memory that is at least
 395 .Fa size
 396 bytes in length, and this should be at least as long as the
 397 .Fa wTotalLength
 398 value from the configuration descriptor.
 399 See
 400 .Sx "USB Descriptors"
 401 below for information about the USB configuration descriptor.
 402 .Pp
 403 The
 404 .Fn usbd_get_config
 405 function retrieves the current configuration number from the device, i.e.\&
 406 the
 407 .Fa bConfigurationValue
 408 value from the configuration that is active.
 409 If the device is unconfigured then
 410 .Dv USB_UNCONFIG_NO
 411 is returned.
 412 The current configuration can be changed by calling either
 413 .Fn usbd_set_config_index
 414 or
 415 .Fn usbd_set_config_no .
 416 The difference between these functions is that
 417 .Fn usbd_set_config_index
 418 accepts a configuration index number that is less than the
 419 .Fa bNumConfigurations
 420 value from the device descriptor, whereas
 421 .Fn usbd_set_config_no
 422 requires the
 423 .Fa bConfigurationValue
 424 value of the desired configuration to be provided instead.
 425 To unconfigure the device, supply a configuration index of
 426 .Dv USB_UNCONFIG_INDEX
 427 to
 428 .Fn usbd_set_config_index ,
 429 or else specify a configuration number of
 430 .Dv USB_UNCONFIG_NO
 431 to
 432 .Fn usbd_set_config_no .
 433 .Pp
 434 The
 435 .Fn usbd_get_config_descriptor
 436 function returns a pointer to an in-memory copy of the full configuration
 437 descriptor of the configuration that is currently active.
 438 The returned pointer remains valid until the device configuration
 439 is changed using
 440 .Fn usbd_set_config_index
 441 or
 442 .Fn usbd_set_config_no .
 443 If the device is unconfigured then
 444 .Dv NULL
 445 is returned instead.
 446 .Pp
 447 The function
 448 .Fn usbd_interface_count
 449 returns the number of interfaces available in the current device
 450 configuration.
 451 The
 452 .Fn usbd_get_no_alts
 453 function determines the number of alternate interfaces in a full
 454 configuration descriptor by counting the interface descriptors with
 455 .Fa bInterfaceNumber
 456 equal to
 457 .Fa ifaceno
 458 (the count includes alternate index zero).
 459 The
 460 .Fn usbd_find_idesc
 461 function locates an interface descriptor within a full configuration
 462 descriptor.
 463 The
 464 .Fa ifaceidx
 465 parameter specifies the interface index number, which should be less than
 466 the number of interfaces in the configuration descriptor (i.e.\& the value
 467 returned by
 468 .Fn usbd_interface_count
 469 or the
 470 .Fa bNumInterface
 471 field from the configuration descriptor).
 472 An alternate interface can be specified using a non-zero
 473 .Fa altidx ,
 474 which should be less than the value returned by
 475 .Fn usbd_get_no_alts .
 476 The return value is a pointer to the requested interface descriptor
 477 within the full configuration descriptor, or
 478 .Dv NULL
 479 if the specified interface descriptor does not exist.
 480 Note that the
 481 .Fa altidx
 482 parameter specifies the alternate setting by index number starting
 483 at zero; it is not the alternate setting number defined in the
 484 interface descriptor.
 485 .Pp
 486 The function
 487 .Fn usbd_find_edesc
 488 locates an endpoint descriptor within a full configuration descriptor.
 489 The
 490 .Fa ifaceidx
 491 and
 492 .Fa altidx
 493 parameters are the same as described for
 494 .Fn usbd_find_idesc ,
 495 and the
 496 .Fa endptidx
 497 parameter is an endpoint index number that should be less than the
 498 .Fa bNumEndpoints
 499 field in the interface descriptor.
 500 The return value is a pointer to the requested endpoint descriptor
 501 within the full configuration descriptor, or
 502 .Dv NULL
 503 if the specified endpoint descriptor does not exist.
 504 Note that the
 505 .Fa altidx
 506 and
 507 .Fa endptidx
 508 parameters are index numbers starting at zero; they are not the
 509 alternate setting and endpoint address defined in the descriptors.
 510 .Pp
 511 The
 512 .Fn usbd_get_speed
 513 function returns the device speed.
 514 This can be
 515 .Dv USB_SPEED_LOW ,
 516 .Dv USB_SPEED_FULL
 517 or
 518 .Dv USB_SPEED_HIGH .
 519 .Pp
 520 USB devices optionally support string descriptors, which can be
 521 retrieved using the
 522 .Fn usbd_get_string
 523 or
 524 .Fn usbd_get_string_desc
 525 functions.
 526 Device, configuration and interface descriptors reference strings by
 527 an index number that can be supplied to these functions.
 528 The
 529 .Fn usbd_get_string
 530 function should be used unless a non-default language is required.
 531 It requires that
 532 .Fa buf
 533 points to a buffer of at least
 534 .Dv USB_MAX_STRING_LEN
 535 bytes in size.
 536 The
 537 .Fa si
 538 parameter specified which string to retrieve.
 539 .Pp
 540 The
 541 .Fn usb_find_desc
 542 function searches through the in-memory full configuration descriptor
 543 for the active configuration and finds the first descriptor that has a
 544 .Fa bDescriptorType
 545 equal to
 546 .Fa type ,
 547 and if
 548 .Fa subtype
 549 is not equal to
 550 .Dv USBD_SUBTYPE_ANY ,
 551 the descriptor must also have a
 552 .Fa bDescriptorSubtype
 553 equal to
 554 .Fa subtype .
 555 If found, then a pointer to the descriptor is returned.
 556 Otherwise,
 557 .Fn usb_find_desc
 558 returns
 559 .Dv NULL .
 560 The returned pointer is valid until the device configuration is changed using
 561 .Fn usbd_set_config_index
 562 or
 563 .Fn usbd_set_config_no .
 564 .Pp
 565 The USB driver interface uses opaque interface handles to refer to
 566 configuration interfaces.
 567 These handles remain valid until the device configuration is changed using
 568 .Fn usbd_set_config_index
 569 or
 570 .Fn usbd_set_config_no .
 571 The
 572 .Fn usbd_device2interface_handle
 573 function retrieves an interface handle.
 574 The
 575 .Fa ifaceno
 576 parameter is an interface index number starting at zero.
 577 If the device is configured and the specified interface exists, then
 578 .Dv USBD_NORMAL_COMPLETION
 579 is returned and the interface handle is stored in
 580 .Fa *iface .
 581 Otherwise an error code is returned and
 582 .Fa *iface
 583 is not changed.
 584 The
 585 .Fn usbd_interface2device_handle
 586 function retrieves the device handle from an interface handle.
 587 This is just for convenience to save passing around the device
 588 handle as well as the interface handle.
 589 The
 590 .Fn usbd_set_interface
 591 function changes the alternate setting number for an interface to
 592 the alternate setting identified by the zero-based index number
 593 .Fa altidx .
 594 This operation invalidates any existing endpoints on this
 595 interface and their descriptors.
 596 The
 597 .Fn usbd_get_interface_altindex
 598 function returns the current alternative setting index as was
 599 specified when calling
 600 .Fn usbd_set_interface .
 601 The
 602 .Fn usbd_endpoint_count
 603 function retrieves the number of endpoints associated with the
 604 specified interface.
 605 The
 606 .Fn usbd_interface2endpoint_descriptor
 607 function returns a pointer to an in-memory endpoint descriptor for
 608 the endpoint that has an index number of
 609 .Fa index .
 610 This pointer remains valid until the configuration or alternate setting
 611 number are changed.
 612 The function
 613 .Fn usbd_get_endpoint_descriptor
 614 is like
 615 .Fn usbd_interface2endpoint_descriptor
 616 but it accepts a
 617 .Fa bEndpointAddress
 618 address value instead of an index.
 619 .Pp
 620 The
 621 .Fn usbd_fill_deviceinfo
 622 function fills out a
 623 .Vt usb_device_info
 624 structure with information about the device.
 625 The vendor and product names come from the device itself, falling back to
 626 a table lookup or just providing the IDs in hexadecimal.
 627 If
 628 .Fa usedev
 629 is zero then
 630 .Fn usbd_fill_deviceinfo
 631 will not attempt to retrieve the vendor and product names from the
 632 device.
 633 The usb_device_info structure is defined in
 634 .In bus/usb/usb.h
 635 as follows:
 636 .Bd -literal
 637 struct usb_device_info {
 638         u_int8_t        udi_bus;
 639         u_int8_t        udi_addr;       /* device address */
 640         usb_event_cookie_t udi_cookie;
 641         char            udi_product[USB_MAX_STRING_LEN];
 642         char            udi_vendor[USB_MAX_STRING_LEN];
 643         char            udi_release[8];
 644         u_int16_t       udi_productNo;
 645         u_int16_t       udi_vendorNo;
 646         u_int16_t       udi_releaseNo;
 647         u_int8_t        udi_class;
 648         u_int8_t        udi_subclass;
 649         u_int8_t        udi_protocol;
 650         u_int8_t        udi_config;
 651         u_int8_t        udi_speed;
 652 #define USB_SPEED_LOW  1
 653 #define USB_SPEED_FULL 2
 654 #define USB_SPEED_HIGH 3
 655         int             udi_power;      /* power consumption in mA */
 656         int             udi_nports;
 657         char            udi_devnames[USB_MAX_DEVNAMES][USB_MAX_DEVNAMELEN];
 658         /* hub only: addresses of devices on ports */
 659         u_int8_t        udi_ports[16];
 660 #define USB_PORT_ENABLED 0xff
 661 #define USB_PORT_SUSPENDED 0xfe
 662 #define USB_PORT_POWERED 0xfd
 663 #define USB_PORT_DISABLED 0xfc
 664 }
 665 .Ed
 666 .Pp
 667 The
 668 .Fn usbd_devinfo
 669 function generates a string description of the USB device.
 670 The
 671 .Fa cp
 672 argument should point to a 1024-byte buffer (XXX the maximum length
 673 is approximately 320 chars, but there is no sanity checking and everything uses
 674 1024-character buffers).
 675 Device class information is included if the
 676 .Fa showclass
 677 parameter is non-zero.
 678 .Pp
 679 The
 680 .Fn usbd_get_quirks
 681 function returns information from a table of devices that require
 682 special workarounds in order to function correctly.
 683 The returned structure is defined in
 684 .In bus/usb/usb_quirks.h
 685 as follows:
 686 .Bd -literal
 687 struct usbd_quirks {
 688         u_int32_t uq_flags;     /* Device problems */
 689 };
 690 .Ed
 691 .Pp
 692 See
 693 .In bus/usb/usb_quirks.h
 694 for a list of all currently defined quirks.
 695 .Pp
 696 USB control requests are performed via
 697 .Vt usb_device_request_t
 698 structures, defined in
 699 .In bus/usb/usb.h
 700 as follows:
 701 .Bd -literal
 702 typedef struct {
 703         uByte           bmRequestType;
 704         uByte           bRequest;
 705         uWord           wValue;
 706         uWord           wIndex;
 707         uWord           wLength;
 708 } UPACKED usb_device_request_t;
 709 .Ed
 710 .Pp
 711 The
 712 .Fn usbd_do_request
 713 function performs a single request synchronously.
 714 The
 715 .Fa req
 716 parameter should point to a properly initialized
 717 .Vt usb_device_request_t ,
 718 and when the
 719 .Fa wLength
 720 field is non-zero,
 721 .Fa data
 722 should point at a buffer that is at least
 723 .Fa wLength
 724 bytes in length.
 725 The request timeout is set to 5 seconds, so the operation will fail
 726 with
 727 .Er USBD_TIMEOUT
 728 if the device does not respond within that time.
 729 The
 730 .Fn usbd_do_request_async
 731 function is like
 732 .Fn usbd_do_request ,
 733 but it does not wait for the request to complete before returning.
 734 This routine does not block so it can be used from contexts where
 735 sleeping is not allowed.
 736 Note that there is no notification mechanism to report when the
 737 operation completed nor is there a way to determine whether the
 738 request succeeded, so this function is of limited use.
 739 See
 740 .Fn usbd_setup_default_xfer
 741 and
 742 .Fn usbd_transfer
 743 for a way to invoke an asynchronous callback upon completion of
 744 a control request.
 745 The
 746 .Fn usbd_do_request_flags
 747 function is like
 748 .Fn usbd_do_request ,
 749 but additional flags can be specified, the timeout is configurable,
 750 and the actual number of bytes transferred is made available to the
 751 caller.
 752 The
 753 .Fn usbd_do_request_flags_pipe
 754 function uses a specified pipe instead of the default pipe.
 755 .Pp
 756 The function
 757 .Fn usbd_open_pipe
 758 creates a pipe connected to a specified endpoint on a specified interface.
 759 The parameter
 760 .Fa address
 761 should be the
 762 .Fa bEndpointAddress
 763 value from one of this interface's endpoint descriptors.
 764 If
 765 .Fa flags
 766 contains
 767 .Dv USBD_EXCLUSIVE_USE
 768 then the operation will only succeed if there are no open pipes
 769 already connected to the specified endpoint.
 770 The
 771 .Fn usbd_open_pipe_intr
 772 function creates an interrupt pipe connected to the specified endpoint.
 773 The parameter
 774 .Fa address
 775 should be the
 776 .Fa bEndpointAddress
 777 value from one of this interface's endpoint descriptors.
 778 The
 779 .Fa flags
 780 parameter is passed to
 781 .Fn usbd_setup_xfer .
 782 The
 783 .Fa buffer
 784 and
 785 .Fa len
 786 parameters define a buffer that is to be used for the interrupt transfers.
 787 The callback to be invoked each time a transfer completes is specified by
 788 .Fa cb ,
 789 and
 790 .Fa priv
 791 is an argument to be passed to the callback function.
 792 The
 793 .Fa ival
 794 parameter specifies the maximum acceptable interval between transfers;
 795 in practice the transfers may occur more frequently.
 796 The function
 797 .Fn usbd_pipe2device_handle
 798 returns the device associated with the specified
 799 .Fa pipe .
 800 .Pp
 801 The
 802 .Fn usbd_abort_pipe
 803 function aborts all active or waiting transfers on the specified pipe.
 804 Each transfer is aborted with a
 805 .Dv USBD_CANCELLED
 806 status; callback routines must detect this error code to ensure that
 807 they do not attempt to initiate a new transfer in response to one being
 808 aborted.
 809 This routine blocks while it is waiting for the hardware to complete
 810 processing of aborted transfers, so it is only safe to call it in
 811 contexts where sleeping is allowed.
 812 The function
 813 .Fn usbd_abort_default_pipe
 814 aborts all active or waiting transfers on the default pipe.
 815 Like
 816 .Fn usbd_abort_pipe ,
 817 it blocks waiting for the hardware processing to complete.
 818 .Pp
 819 When a pipe has no active or waiting transfers, the pipe may be closed
 820 using the
 821 .Fn usbd_close_pipe
 822 function.
 823 Once a pipe is closed, its pipe handle becomes invalid and may no longer
 824 be used.
 825 .Pp
 826 USB transfer handles are allocated using the function
 827 .Fn usbd_alloc_xfer
 828 and may be freed using
 829 .Fn usbd_free_xfer .
 830 .Pp
 831 The function
 832 .Fn usbd_setup_xfer
 833 initializes a transfer handle with the details of a transfer to or from
 834 a USB device.
 835 The
 836 .Fa xfer
 837 parameter specifies the transfer handle to initialize,
 838 .Fa pipe
 839 specifies the pipe on which the transfer is to take place, and
 840 .Fa priv
 841 is an argument that will be passed to callback function.
 842 The arguments
 843 .Fa buffer
 844 and
 845 .Fa length
 846 define the data buffer for the transfer.
 847 If
 848 .Fa length
 849 is zero then the
 850 .Fa buffer
 851 may be
 852 .Dv NULL .
 853 The
 854 .Fa flags
 855 parameter may contain the following flags:
 856 .Bl -tag -width ".Dv USBD_FORCE_SHORT_XFER"
 857 .It Dv USBD_NO_COPY
 858 This is used in association with
 859 .Fn usbd_alloc_buffer
 860 and
 861 .Fn usbd_free_buffer
 862 to use a dedicated DMA-capable buffer for the transfer.
 863 .It Dv USBD_SYNCHRONOUS
 864 Wait for the transfer to compete in
 865 .Fn usbd_transfer .
 866 .It Dv USBD_SHORT_XFER_OK
 867 Permit transfers shorter than the requested data length.
 868 .It Dv USBD_FORCE_SHORT_XFER
 869 Force a short transfer at the end of a write operation to let the
 870 device know that the transfer has ended.
 871 .El
 872 .Pp
 873 The
 874 .Fa timeout
 875 parameter specifies a timeout for the transfer in milliseconds.
 876 A value of
 877 .Dv USBD_NO_TIMEOUT
 878 indicates that no timeout should be configured.
 879 The parameter
 880 .Fa callback
 881 specifies the function to call when the transfer completes.
 882 Note that
 883 .Fn usbd_setup_xfer
 884 does not actually initiate the transfer.
 885 The
 886 .Fn usbd_setup_default_xfer
 887 initializes a control transfer for the default pipe.
 888 The
 889 .Fa req
 890 parameter should point at a completed
 891 .Vt usb_device_request_t
 892 structure.
 893 The function
 894 .Fn usbd_setup_isoc_xfer
 895 initializes a transfer for an isochronous pipe.
 896 .Pp
 897 The function
 898 .Fn usbd_transfer
 899 initiates a transfer.
 900 Normally it returns
 901 .Dv USBD_IN_PROGRESS
 902 to indicate that the transfer has been queued.
 903 If the USB stack is operating in polling mode, or if the transfer
 904 is synchronous, then
 905 .Dv USBD_NORMAL_COMPLETION
 906 may be returned.
 907 Other return values indicate that the transfer could not be
 908 initiated due to an error.
 909 The
 910 .Fn usbd_sync_transfer
 911 function executes a transfer synchronously.
 912 It will sleep waiting for the transfer to complete and then return
 913 the transfer status.
 914 Note that if the transfer has a callback routine, this will be
 915 invoked before
 916 .Fn usbd_sync_transfer
 917 returns.
 918 .Pp
 919 The
 920 .Fn usbd_intr_transfer
 921 and
 922 .Fn usbd_bulk_transfer
 923 functions set up a transfer and wait synchronously for it to complete
 924 but they allows signals to interrupt the wait.
 925 They returns
 926 .Dv USBD_INTERRUPTED
 927 if the transfer was interrupted by a signal.
 928 XXX these two functions are identical apart from their names.
 929 .Pp
 930 The function
 931 .Fn usbd_get_xfer_status
 932 retrieves various information from a completed transfer.
 933 If the
 934 .Fa priv
 935 parameter is not NULL then the callback private argument is
 936 stored in
 937 .Fa *priv .
 938 If
 939 .Fa buffer
 940 is not NULL then the transfer buffer pointer is stored in
 941 .Fa *buffer .
 942 The actual number of bytes transferred is stored in
 943 .Fa *count
 944 if
 945 .Fa count
 946 is not NULL.
 947 Finally, the transfer status is stored in
 948 .Fa *status
 949 if
 950 .Fa status
 951 is not NULL.
 952 .Pp
 953 The
 954 .Fn usbd_clear_endpoint_stall
 955 function clears an endpoint stall condition synchronously, i.e.\&
 956 it sleeps waiting for the stall clear request to complete.
 957 The function
 958 .Fn usbd_clear_endpoint_stall_async
 959 performs the same function asynchronously, but it provides no
 960 way to determine when the request completed, or whether it was
 961 successful.
 962 The
 963 .Fn usbd_clear_endpoint_toggle
 964 function instructs the host controller driver to reset the toggle bit
 965 on a pipe.
 966 This is used when manually clearing an endpoint stall using a
 967 control pipe request, in order to ensure that the host controller
 968 driver and the USB device restart with the same toggle value.
 969 .Pp
 970 Normally the USB subsystem maps and copies data to and from
 971 DMA-capable memory each time a transfer is performed.
 972 The function
 973 .Fn usbd_alloc_buffer
 974 allocates a permanent DMA-capable buffer associated with the
 975 transfer to avoid this overhead.
 976 The return value is the virtual address of the buffer.
 977 Any time that
 978 .Fn usbd_setup_xfer
 979 is called on the transfer with the
 980 .Dv USBD_NO_COPY
 981 flag enabled, the allocated buffer will be used directly and
 982 the
 983 .Fa buffer
 984 argument passed to
 985 .Fn usbd_setup_xfer
 986 will be ignored.
 987 The
 988 .Fn usbd_get_buffer
 989 function returns a pointer to the virtual address of a buffer previously
 990 allocated by
 991 .Fn usbd_alloc_buffer .
 992 Finally,
 993 .Fn usbd_free_buffer
 994 deallocates the buffer.
 995 .Pp
 996 The
 997 .Fn usbd_errstr
 998 function converts a status code into a string for display.
 999 .Pp
1000 The function
1001 .Fn usbd_set_polling
1002 enables or disables polling mode.
1003 In polling mode, all operations will busy-wait for the device to
1004 respond, so its use is effectively limited to boot time and kernel
1005 debuggers.
1006 It is important to match up calls that enable and disable polling
1007 mode, because the implementation just increments a polling reference
1008 count when
1009 .Fa on
1010 is non-zero and decrements it when
1011 .Fa on
1012 is zero.
1013 The
1014 .Fn usbd_dopoll
1015 causes the host controller driver to poll for any activity.
1016 This should only be used when polling mode is enabled.
1017 .Pp
1018 The
1019 .Fn usbd_ratecheck
1020 function is used to limit the rate at which error messages are
1021 printed to approximately once per second.
1022 The
1023 .Fa last
1024 argument should point at a persistent
1025 .Vt "struct timeval" .
1026 A value of 1 will be returned if a message should be printed, but if
1027 .Fn usbd_ratecheck
1028 has already been called with the same
1029 .Vt "struct timeval"
1030 parameter in the last second then 0 is returned and the error message
1031 should be suppressed.
1032 .Pp
1033 The functions
1034 .Fn usb_detach_wait
1035 and
1036 .Fn usb_detach_wakeup
1037 are used to wait for references to drain before completing the
1038 detachment of a device.
1039 The
1040 .Fn usb_detach_wait
1041 function will wait up to 60 seconds to receive a signal from
1042 .Fn usb_detach_wait .
1043 .Ss "USB Descriptors"
1044 The USB specification defines a number of standard descriptors by
1045 which USB devices report their attributes.
1046 These descriptors are fixed-format structures that all USB devices
1047 make available through USB control pipe requests.
1048 .Pp
1049 Every USB device has exactly one USB device descriptor.
1050 The USB subsystem retrieves this automatically when a device is
1051 attached, and a copy of the descriptor is kept in memory.
1052 The
1053 .Fn usbd_get_device_descriptor
1054 function returns a pointer to the descriptor.
1055 The device descriptor structure is defined in
1056 .In bus/usb/usb.h
1057 as follows:
1058 .Bd -literal
1059 typedef struct {
1060         uByte           bLength;
1061         uByte           bDescriptorType;
1062         uWord           bcdUSB;
1063 #define UD_USB_2_0              0x0200
1064 #define UD_IS_USB2(d) (UGETW((d)->bcdUSB) >= UD_USB_2_0)
1065         uByte           bDeviceClass;
1066         uByte           bDeviceSubClass;
1067         uByte           bDeviceProtocol;
1068         uByte           bMaxPacketSize;
1069         /* The fields below are not part of the initial descriptor. */
1070         uWord           idVendor;
1071         uWord           idProduct;
1072         uWord           bcdDevice;
1073         uByte           iManufacturer;
1074         uByte           iProduct;
1075         uByte           iSerialNumber;
1076         uByte           bNumConfigurations;
1077 } UPACKED usb_device_descriptor_t;
1078 #define USB_DEVICE_DESCRIPTOR_SIZE 18
1079 .Ed
1080 .Pp
1081 USB devices have at least one configuration descriptor.
1082 The
1083 .Fa bNumConfigurations
1084 field of the device descriptor specifies the number of configuration
1085 descriptors that a device supports.
1086 The
1087 .Fn usbd_get_config_desc
1088 function retrieves a particular configuration descriptor from the device
1089 and the
1090 .Fn usbd_get_config_desc_full
1091 function retrieves a full
1092 .Fa wTotalLength
1093 length configuration descriptor, which includes all related interface
1094 and endpoint descriptors.
1095 Only one configuration may be active at a time.
1096 The
1097 .Fn usbd_set_config_index
1098 function activates a specified configuration.
1099 The configuration descriptor structure is defined in
1100 .In bus/usb/usb.h
1101 as follows:
1102 .Bd -literal
1103 typedef struct {
1104         uByte           bLength;
1105         uByte           bDescriptorType;
1106         uWord           wTotalLength;
1107         uByte           bNumInterface;
1108         uByte           bConfigurationValue;
1109         uByte           iConfiguration;
1110         uByte           bmAttributes;
1111 #define UC_BUS_POWERED          0x80
1112 #define UC_SELF_POWERED         0x40
1113 #define UC_REMOTE_WAKEUP        0x20
1114         uByte           bMaxPower; /* max current in 2 mA units */
1115 #define UC_POWER_FACTOR 2
1116 } UPACKED usb_config_descriptor_t;
1117 #define USB_CONFIG_DESCRIPTOR_SIZE 9
1118 .Ed
1119 .Pp
1120 Each device configuration provides one or more interfaces.
1121 The
1122 .Fa bNumInterface
1123 field of the configuration descriptor specifies the number of
1124 interfaces associated with a device configuration.
1125 Interfaces are described by an interface descriptor, which is defined in
1126 .In bus/usb/usb.h
1127 as follows:
1128 .Bd -literal
1129 typedef struct {
1130         uByte           bLength;
1131         uByte           bDescriptorType;
1132         uByte           bInterfaceNumber;
1133         uByte           bAlternateSetting;
1134         uByte           bNumEndpoints;
1135         uByte           bInterfaceClass;
1136         uByte           bInterfaceSubClass;
1137         uByte           bInterfaceProtocol;
1138         uByte           iInterface;
1139 } UPACKED usb_interface_descriptor_t;
1140 #define USB_INTERFACE_DESCRIPTOR_SIZE 9
1141 .Ed
1142 .Pp
1143 Configurations may also have alternate interfaces with the same
1144 .Fa bInterfaceNumber
1145 but different
1146 .Fa bAlternateSetting
1147 values.
1148 These alternate interface settings may be selected by passing a
1149 non-zero
1150 .Fa altidx
1151 parameter to
1152 .Fn usbd_set_interface .
1153 .Pp
1154 Interfaces have zero or more endpoints, and each endpoint has an
1155 endpoint descriptor.
1156 Note that endpoint zero, which is always present, does not have an
1157 endpoint descriptor, and it is never included in the
1158 .Fa bNumEndpoints
1159 count of endpoints.
1160 The endpoint descriptor is defined in
1161 .In bus/usb/usb.h
1162 as follows:
1163 .Bd -literal
1164 typedef struct {
1165         uByte           bLength;
1166         uByte           bDescriptorType;
1167         uByte           bEndpointAddress;
1168 #define UE_GET_DIR(a)   ((a) & 0x80)
1169 #define UE_SET_DIR(a,d) ((a) | (((d)&1) << 7))
1170 #define UE_DIR_IN       0x80
1171 #define UE_DIR_OUT      0x00
1172 #define UE_ADDR         0x0f
1173 #define UE_GET_ADDR(a)  ((a) & UE_ADDR)
1174         uByte           bmAttributes;
1175 #define UE_XFERTYPE     0x03
1176 #define  UE_CONTROL     0x00
1177 #define  UE_ISOCHRONOUS 0x01
1178 #define  UE_BULK        0x02
1179 #define  UE_INTERRUPT   0x03
1180 #define UE_GET_XFERTYPE(a)      ((a) & UE_XFERTYPE)
1181 #define UE_ISO_TYPE     0x0c
1182 #define  UE_ISO_ASYNC   0x04
1183 #define  UE_ISO_ADAPT   0x08
1184 #define  UE_ISO_SYNC    0x0c
1185 #define UE_GET_ISO_TYPE(a)      ((a) & UE_ISO_TYPE)
1186         uWord           wMaxPacketSize;
1187         uByte           bInterval;
1188 } UPACKED usb_endpoint_descriptor_t;
1189 #define USB_ENDPOINT_DESCRIPTOR_SIZE 7
1190 .Ed
1191 .Sh RETURN VALUES
1192 Many functions return a
1193 .Vt usbd_status
1194 type to indicate the outcome of the operation.
1195 If the operation completed successfully then
1196 .Dv USBD_NORMAL_COMPLETION
1197 is returned.
1198 Operations that have been started but not yet completed will return
1199 .Dv USBD_IN_PROGRESS .
1200 Other errors usually indicate a problem.
1201 Error codes can be converted to strings using
1202 .Fn usbd_errstr .
1203 .Sh ERRORS
1204 .Bl -tag -width ".Er USBD_PENDING_REQUESTS"
1205 .It Bq Er USBD_PENDING_REQUESTS
1206 A pipe could not be closed because there are active requests.
1207 .It Bq Er USBD_NOT_STARTED
1208 The transfer has not yet been started.
1209 .It Bq Er USBD_INVAL
1210 An invalid value was supplied.
1211 .It Bq Er USBD_NOMEM
1212 An attempt to allocate memory failed.
1213 .It Bq Er USBD_CANCELLED
1214 The transfer was aborted.
1215 .It Bq Er USBD_BAD_ADDRESS
1216 The specified endpoint address was not found.
1217 .It Bq Er USBD_IN_USE
1218 The endpoint is already in use, or the configuration cannot be changed
1219 because some of its endpoints are in use.
1220 .It Bq Er USBD_NO_ADDR
1221 No free USB devices addresses were found to assign to the device.
1222 .It Bq Er USBD_SET_ADDR_FAILED
1223 The device address could not be set.
1224 .It Bq Er USBD_NO_POWER
1225 Insufficient power was available for the device.
1226 .It Bq Er USBD_TOO_DEEP
1227 Too many levels of chained hubs were found.
1228 .It Bq Er USBD_IOERROR
1229 There was an error communicating with the device.
1230 .It Bq Er USBD_NOT_CONFIGURED
1231 An operation that requires an active configuration was attempted while
1232 the device was in an unconfigured state.
1233 .It Bq Er USBD_TIMEOUT
1234 A transfer timed out.
1235 .It Bq Er USBD_SHORT_XFER
1236 A transfer that disallowed short data lengths completed with less than
1237 the requested length transferred.
1238 .It Bq Er USBD_STALLED
1239 A transfer failed because the pipe is stalled.
1240 .It Bq Er USBD_INTERRUPTED
1241 An interruptible operation caught a signal.
1242 .El
1243 .Sh SEE ALSO
1244 .Xr usb 4
1245 .Sh HISTORY
1246 The USB driver interface first appeared in
1247 .Fx 3.0 .
1248 .Sh AUTHORS
1249 The USB driver was written by
1250 .An Lennart Augustsson
1251 for the
1252 .Nx
1253 project.
1254 .Pp
1255 .An -nosplit
1256 This manual page was written by
1257 .An Ian Dowse Aq iedowse@FreeBSD.org .