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