share/man/man4/btsco.4

   1 .\" $NetBSD: btsco.4,v 1.10 2009/05/27 19:23:59 snj Exp $
   2 .\"
   3 .\" Copyright (c) 2006 Itronix Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" Written by Iain Hibbert for Itronix Inc.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\" 3. The name of Itronix Inc. may not be used to endorse
  17 .\"    or promote products derived from this software without specific
  18 .\"    prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY ITRONIX INC. ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  22 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  23 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL ITRONIX INC. BE LIABLE FOR ANY
  24 .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  25 .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  26 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  27 .\" ON ANY THEORY OF LIABILITY, WHETHER IN
  28 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  29 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  30 .\" POSSIBILITY OF SUCH DAMAGE.
  31 .\"
  32 .Dd October 4, 2006
  33 .Dt BTSCO 4
  34 .Os
  35 .Sh NAME
  36 .Nm btsco
  37 .Nd Bluetooth SCO Audio
  38 .Sh SYNOPSIS
  39 .Cd "btsco*     at bthub?"
  40 .Cd "audio*     at audiobus?"
  41 .Sh DESCRIPTION
  42 The
  43 .Nm
  44 driver provides support for Bluetooth SCO Audio devices through the
  45 .Xr audio 4
  46 driver.
  47 .Pp
  48 The
  49 .Nm
  50 driver must be configured at run time with the
  51 .Xr btdevctl 8
  52 program.
  53 The following properties are used by the
  54 .Nm
  55 driver during autoconfiguration:
  56 .Pp
  57 .Bl -tag -width listenXX
  58 .It local-bdaddr
  59 Local device address.
  60 .It remote-bdaddr
  61 Remote device address.
  62 .It service-name
  63 The
  64 .Nm
  65 driver matches the
  66 .Sq HF
  67 and
  68 .Sq HSET
  69 services.
  70 For the
  71 .Sq HF
  72 service, the
  73 .Nm
  74 device will, on
  75 .Xr open 2 ,
  76 listen for incoming connections from the remote device.
  77 Otherwise,
  78 .Nm
  79 will attempt to initiate a connection to the remote device.
  80 .It rfcomm-channel
  81 This integer value is not used directly, but will be stored and
  82 passed via the
  83 .Dv BTSCO_INFO
  84 ioctl as below:
  85 .El
  86 .Pp
  87 SCO connections require a baseband connection between the two devices before
  88 they can be created.
  89 The
  90 .Nm
  91 driver does not create this, but can provide information to facilitate
  92 an application setting up a control channel prior to use, via the
  93 .Dv BTSCO_INFO
  94 .Xr ioctl 2
  95 call on the mixer device, which returns a
  96 .Ar btsco_info
  97 structure as follows:
  98 .Bd -literal
  99 #include \*[Lt]dev/bluetooth/btsco.h\*[Gt]
 100
 101 struct btsco_info {
 102         bdaddr_t        laddr;          /* controller bdaddr */
 103         bdaddr_t        raddr;          /* headset bdaddr */
 104         uint8_t         channel;        /* RFCOMM channel */
 105         int             vgs;            /* mixer index speaker */
 106         int             vgm;            /* mixer index mic */
 107 };
 108
 109 #define BTSCO_INFO      _IOR('b', 16, struct btsco_info)
 110 .Ed
 111 .Pp
 112 The
 113 .Nm
 114 driver can be configured to act in Connect or Listen mode.
 115 In Connect mode, the
 116 .Nm
 117 driver will initiate a connection to the remote device on an
 118 .Xr open 2
 119 call, whereas in Listen mode,
 120 .Xr open 2
 121 will block until the remote device initiates the connection.
 122 .Sh SEE ALSO
 123 .Xr bthset 1 ,
 124 .Xr ioctl 2 ,
 125 .Xr audio 4 ,
 126 .Xr bluetooth 4 ,
 127 .Xr bthub 4 ,
 128 .Xr btdevctl 8
 129 .Sh HISTORY
 130 The
 131 .Nm
 132 driver
 133 was written for
 134 .Nx 4.0
 135 by
 136 .An Iain Hibbert
 137 under the sponsorship of Itronix, Inc.
 138 .Sh BUGS
 139 .Nm
 140 takes no notice of the HCI Voice Setting in the Bluetooth controller, and this
 141 must be 0x0060 (the default) as alternate values are currently unsupported.