share/man/man4/ubt.4

   1 .\" $NetBSD: ubt.4,v 1.5 2006/09/02 23:54:23 wiz Exp $
   2 .\" $DragonFly: src/share/man/man4/ubt.4,v 1.3 2008/02/03 06:33:00 hasso Exp $
   3 .\"
   4 .\" Copyright (c) 2006 Itronix Inc.
   5 .\" All rights reserved.
   6 .\"
   7 .\" Written by Iain Hibbert for Itronix Inc.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\" 3. The name of Itronix Inc. may not be used to endorse
  18 .\"    or promote products derived from this software without specific
  19 .\"    prior written permission.
  20 .\"
  21 .\" THIS SOFTWARE IS PROVIDED BY ITRONIX INC. ``AS IS'' AND
  22 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  23 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  24 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL ITRONIX INC. BE LIABLE FOR ANY
  25 .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  26 .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  27 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  28 .\" ON ANY THEORY OF LIABILITY, WHETHER IN
  29 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  30 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  31 .\" POSSIBILITY OF SUCH DAMAGE.
  32 .\"
  33 .Dd August 27, 2006
  34 .Dt UBT 4
  35 .Os
  36 .Sh NAME
  37 .Nm ubt
  38 .Nd USB Bluetooth driver
  39 .Sh SYNOPSIS
  40 To compile this driver into the kernel,
  41 place the following lines in your
  42 kernel configuration file:
  43 .Bd -ragged -offset indent
  44 .Cd "device ubt"
  45 .Ed
  46 .Pp
  47 Alternatively, to load the driver as a
  48 module at boot time, place the following line in
  49 .Xr loader.conf 5 :
  50 .Bd -literal -offset indent
  51 ubt_load="YES"
  52 .Ed
  53 .Sh DESCRIPTION
  54 The
  55 .Nm
  56 driver provides support for USB Bluetooth dongles
  57 to the Bluetooth protocol stack.
  58 .Pp
  59 USB Bluetooth dongles provide two interfaces, both of which the
  60 .Nm
  61 driver claims.
  62 The second interface is used for Isochronous data and will have
  63 several alternate configurations regarding bandwidth consumption,
  64 which can be set using the hw.ubtN.config
  65 .Xr sysctl 8
  66 variable.
  67 The number of alternate configurations is indicated by the value
  68 in the hw.ubtN.alt_config variable, and the isoc frame size for the current
  69 configuration is shown in the hw.ubtN.sco_rxsize and hw.ubtN.sco_txsize
  70 variables.
  71 .Pp
  72 By default, configuration 0 is selected, which means that no bandwidth
  73 is used on the Isochronous interface and no SCO data can be sent.
  74 Consult the Bluetooth USB specification at https://www.bluetooth.org/
  75 for complete instructions on setting bandwidth consumption.
  76 The following extract may be
  77 useful as a general guidance though details may differ between manufacturers.
  78 .Pp
  79 .Bl -tag -compact -width XXX
  80 .It 0
  81 No active voice channels
  82 .It 1
  83 One voice channel with 8-bit encoding
  84 .It 2
  85 Two voice channels with 8-bit encoding, or one voice channel with
  86 16-bit encoding.
  87 .It 3
  88 Three voice channels with 8-bit encoding
  89 .It 4
  90 Two voice channels with 16-bit encoding
  91 .It 5
  92 Three voice channels with 16-bit encoding
  93 .El
  94 .Sh SEE ALSO
  95 .Xr bluetooth 4
  96 .\".Xr uhub 4 ,
  97 .Xr sysctl 8
  98 .Sh HISTORY
  99 This
 100 .Nm
 101 device driver was originally a character device written by
 102 .An David Sainty
 103 and
 104 .An Lennart Augustsson .
 105 It was rewritten to support socket based Bluetooth access for
 106 .Nx 4.0
 107 by
 108 .An Iain Hibbert .
 109 The
 110 .Nm
 111 driver was imported into
 112 .Dx 1.11 .
 113 .Sh CAVEATS
 114 Isochronous data is seemingly not well supported over USB in the current
 115 system and to get SCO working, you may have to calculate the SCO packet
 116 size that the stack will use.
 117 This is the sco_mtu value reported by the
 118 .Xr btconfig 8
 119 command, and when combined with the SCO header (3 bytes) should
 120 fit exactly into an integer number of Isochronous data frames where
 121 the frame size is indicated by the
 122 .Sq hw.ubtN.sco_txsize
 123 sysctl variable.
 124 .Pp
 125 For example: I want one voice channel (which is all that is supported,
 126 for now) so am using configuration #2, with a frame length of 17
 127 bytes.
 128 This gives possible values of:
 129 .Pp
 130 .Dl "(17 * 1) - 3 = 14"
 131 .Dl "(17 * 2) - 3 = 31"
 132 .Dl "(17 * 3) - 3 = 48"
 133 .Dl "(17 * 4) - 3 = 65"
 134 .Dl "(17 * 5) - 3 = 82"
 135 .Dl "etc."
 136 .Pp
 137 .Xr btconfig 8
 138 shows the maximum SCO payload as 64 bytes, so I am using the next smaller
 139 size of 48, to minimize the overhead of the 3 header bytes.
 140 .Pp
 141 The SCO packet size can be changed using the
 142 .Sq scomtu
 143 option to
 144 .Xr btconfig 8 .
 145 .Pp
 146 The failure mode is that the USB Bluetooth dongle locks up though
 147 generally removal/reinsertion will clear the problem.
 148 .Sh BUGS
 149 The Isochronous configuration can only be changed when the device is not
 150 marked up.