usr.sbin/usbconfig/usbconfig.8

   1 .\" $FreeBSD$
   2 .\"
   3 .\" Copyright (c) 2008-2010 Hans Petter Selasky. 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 .Dd August 16, 2019
  27 .Dt USBCONFIG 8
  28 .Os
  29 .Sh NAME
  30 .Nm usbconfig
  31 .Nd configure the USB subsystem
  32 .Sh SYNOPSIS
  33 .Nm
  34 .Op Fl u Ar unit
  35 .Op Fl a Ar addr
  36 .Op cmds...
  37 .Nm
  38 .Op Oo Fl d Oc Ar [ugen]<unit>.<addr>
  39 .Op cmds...
  40 .Sh DESCRIPTION
  41 The
  42 .Nm
  43 utility is used to configure and dump information about the USB subsystem.
  44 .Pp
  45 The options are as follows:
  46 .Bl -tag -width "        "
  47 .It Fl u Ar unit
  48 Limit device range to USB devices connected to the given USBUS unit.
  49 .It Fl a Ar addr
  50 Limit device range to the given USB device index.
  51 Should only be used in conjunction with the unit argument.
  52 .It Fl d Ar [ugen]<unit>.<addr>
  53 Limit device range to USB devices connected to the given unit and address.
  54 The unit and address coordinates may be prefixed by the lowercased word "ugen".
  55 .It Fl i Ar interface_index
  56 Specify interface index as indicated by the command description.
  57 If this argument is not specified a value of zero will be used for the interface index.
  58 .It Fl h
  59 Show help and available commands.
  60 .El
  61 .Pp
  62 The following commands may be used with
  63 .Nm :
  64 .Bl -tag -width indent
  65 .It Cm set_config Ar cfg_index
  66 Choose the configuration for the USB device.
  67 Valid values range from zero to the number reported as the
  68 .Ar bNumConfigurations
  69 in
  70 .Cm dump_device_desc
  71 output.
  72 The special value of 255 unconfigures the device, detaching
  73 the interface drivers and reducing the power consumption to minimum,
  74 but without going into power saving mode or detaching from the bus.
  75 In some cases, it prevents the device from charging.
  76 .It Cm set_alt Ar alt_index
  77 Choose the alternate interface for the selected interface and USB device.
  78 Alternative settings for the current configuration are available as the
  79 .Ar bAlternateSetting
  80 in
  81 .Cm dump_curr_config_desc
  82 output.
  83 Usually there is no need to adjust this setting.
  84 .It Cm set_template Ar template
  85 Set the global USB device side template.
  86 See
  87 .Xr usb_template 4
  88 for more information.
  89 .It Cm get_template
  90 Get the current USB device side template.
  91 .It Cm add_dev_quirk_vplh Ar vid Ar pid Ar lo_rev Ar hi_rev Ar quirk_name
  92 Add a quirk by specifying the Vendor ID, Product ID, low and high
  93 revision numbers, and the quirk name.
  94 See
  95 .Xr usb_quirk 4
  96 for more information.
  97 .It Cm remove_dev_quirk_vplh Ar vid Ar pid Ar lo_rev Ar hi_rev Ar quirk_name
  98 Remove a quirk.
  99 .It Cm add_quirk Ar quirk_name
 100 Add quirk for the currently selected USB device.
 101 .It Cm remove_quirk Ar quirk_name
 102 Remove a quirk for the currently selected USB device.
 103 .It Cm dump_all_desc
 104 Display the device and configuration descriptors.
 105 .It Cm dump_quirk_names
 106 Display the list of supported quirk names.
 107 .It Cm dump_device_quirks
 108 Display the list of current device quirks.
 109 .It Cm dump_device_desc
 110 Display the device descriptor.
 111 .It Cm dump_curr_config_desc
 112 Display current configuration descriptor.
 113 .It Cm dump_all_config_desc
 114 Display all the configuration descriptors.
 115 .It Cm dump_string Ar index
 116 Display string descriptor at selected index.
 117 .It Cm dump_info
 118 Display summary information about the device.
 119 .It Cm show_ifdrv
 120 Display the list of interface drivers (such as
 121 .Xr ukbd 4
 122 or
 123 .Xr u3g 4 )
 124 currently attached to the device.
 125 .It Cm detach_kernel_driver
 126 Detach kernel driver for the selected interface and USB device.
 127 .It Cm suspend
 128 Force the device to suspend.
 129 .It Cm resume
 130 Force the device to resume.
 131 .It Cm power_off
 132 Turn the device off.
 133 .It Cm power_save
 134 Turn the automatic suspend and resume on.
 135 This is the default for USB hubs.
 136 .It Cm power_on
 137 Turn the device on and disable automatic suspend and resume.
 138 This is the default for non-hub devices.
 139 .It Cm reset
 140 Reset the device.
 141 This forces the USB stack to reenumerate the bus.
 142 .It Cm list
 143 List all available USB devices.
 144 This is the default if
 145 .Nm
 146 is called without specifying a command.
 147 .It Cm do_request Ar bmReqTyp Ar bReq Ar wVal Ar wIdx Ar wLen Ar data...
 148 Perform a synchronous control request on the specified device.
 149 See
 150 .Xr libusb20_dev_request_sync 3
 151 for more information.
 152 .El
 153 .Sh EXAMPLES
 154 List all connected USB devices and their attached interface drivers:
 155 .Pp
 156 .Dl usbconfig show_ifdrv
 157 .Pp
 158 Dump device and configuration descriptors for device on USB bus 1 at address 2:
 159 .Pp
 160 .Dl usbconfig ugen1.2 dump_all_desc
 161 .Pp
 162 Dump HID descriptor for device on USB bus 1 at address 2:
 163 .Pp
 164 .Dl usbconfig ugen1.2 do_request 0x81 0x06 0x2200 0 0x100
 165 .Pp
 166 Power off the device on USB bus 1 at address 2:
 167 .Pp
 168 .Dl usbconfig ugen1.2 power_off
 169 .Sh SEE ALSO
 170 .Xr usb 4 ,
 171 .Xr usb_quirk 4 ,
 172 .Xr usb_template 4