share/man/man4/ng_btsocket.4

   1 .\" Copyright (c) 2001-2002 Maksim Yevmenkin <m_evmenkin@yahoo.com>
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $Id: ng_btsocket.4,v 1.7 2003/05/21 19:37:35 max Exp $
  26 .\" $FreeBSD$
  27 .\"
  28 .Dd November 13, 2012
  29 .Dt NG_BTSOCKET 4
  30 .Os
  31 .Sh NAME
  32 .Nm ng_btsocket
  33 .Nd Bluetooth sockets layer
  34 .Sh SYNOPSIS
  35 .In sys/types.h
  36 .In sys/socket.h
  37 .In sys/bitstring.h
  38 .In netgraph/bluetooth/include/ng_hci.h
  39 .In netgraph/bluetooth/include/ng_l2cap.h
  40 .In netgraph/bluetooth/include/ng_btsocket.h
  41 .Sh DESCRIPTION
  42 The
  43 .Nm
  44 module implements three Netgraph node types.
  45 Each type in its turn implements one protocol within
  46 .Dv PF_BLUETOOTH
  47 domain.
  48 .Sh Dv BLUETOOTH_PROTO_HCI Sh protocol
  49 .Ss Dv SOCK_RAW Ss HCI sockets
  50 Implemented by
  51 .Nm btsock_hci_raw
  52 Netgraph type.
  53 Raw HCI sockets allow sending of raw HCI command datagrams
  54 only to correspondents named in
  55 .Xr send 2
  56 calls.
  57 Raw HCI datagrams (HCI commands, events and data) are generally received with
  58 .Xr recvfrom 2 ,
  59 which returns the next datagram with its return address.
  60 Raw HCI sockets can also be used to control HCI nodes.
  61 .Pp
  62 The Bluetooth raw HCI socket address is defined as follows:
  63 .Bd -literal -offset indent
  64 /* Bluetooth version of struct sockaddr for raw HCI sockets */
  65 struct sockaddr_hci {
  66         u_char  hci_len;      /* total length */
  67         u_char  hci_family;   /* address family */
  68         char    hci_node[32]; /* address (size == NG_NODESIZ ) */
  69 };
  70 .Ed
  71 .Pp
  72 Raw HCI sockets support a number of
  73 .Xr ioctl 2
  74 requests such as:
  75 .Bl -tag -width foo
  76 .It Dv SIOC_HCI_RAW_NODE_GET_STATE
  77 Returns current state for the HCI node.
  78 .It Dv SIOC_HCI_RAW_NODE_INIT
  79 Turn on
  80 .Dq inited
  81 bit for the HCI node.
  82 .It Dv SIOC_HCI_RAW_NODE_GET_DEBUG
  83 Returns current debug level for the HCI node.
  84 .It Dv SIOC_HCI_RAW_NODE_SET_DEBUG
  85 Sets current debug level for the HCI node.
  86 .It Dv SIOC_HCI_RAW_NODE_GET_BUFFER
  87 Returns current state of data buffers for the HCI node.
  88 .It Dv SIOC_HCI_RAW_NODE_GET_BDADDR
  89 Returns BD_ADDR for the HCI node.
  90 .It Dv SIOC_HCI_RAW_NODE_GET_FEATURES
  91 Returns the list of features supported by hardware for the HCI node.
  92 .It Dv SIOC_HCI_RAW_NODE_GET_STAT
  93 Returns various statistic counters for the HCI node.
  94 .It Dv SIOC_HCI_RAW_NODE_RESET_STAT
  95 Resets all statistic counters for the HCI node to zero.
  96 .It Dv SIOC_HCI_RAW_NODE_FLUSH_NEIGHBOR_CACHE
  97 Remove all neighbor cache entries for the HCI node.
  98 .It Dv SIOC_HCI_RAW_NODE_GET_NEIGHBOR_CACHE
  99 Returns content of the neighbor cache for the HCI node.
 100 .It Dv SIOC_HCI_RAW_NODE_GET_CON_LIST
 101 Returns list of active baseband connections (i.e., ACL and SCO links) for
 102 the HCI node.
 103 .It SIOC_HCI_RAW_NODE_GET_LINK_POLICY_MASK
 104 Returns current link policy settings mask for the HCI node.
 105 .It SIOC_HCI_RAW_NODE_SET_LINK_POLICY_MASK
 106 Sets current link policy settings mask for the HCI node.
 107 .It SIOC_HCI_RAW_NODE_GET_PACKET_MASK
 108 Returns current packet mask for the HCI node.
 109 .It SIOC_HCI_RAW_NODE_SET_PACKET_MASK
 110 Sets current packet mask for the HCI node.
 111 .It SIOC_HCI_RAW_NODE_GET_ROLE_SWITCH
 112 Returns current value of the role switch parameter for the HCI node.
 113 .It SIOC_HCI_RAW_NODE_SET_ROLE_SWITCH
 114 Sets new value of the role switch parameter for the HCI node.
 115 .El
 116 .Pp
 117 The
 118 .Va net.bluetooth.hci.sockets.raw.ioctl_timeout
 119 variable, that can be examined and set via
 120 .Xr sysctl 8 ,
 121 controls the control request timeout (in seconds) for raw HCI sockets.
 122 .Pp
 123 Raw HCI sockets support filters.
 124 The application can filter certain HCI datagram types.
 125 For HCI event datagrams the application can set additional filter.
 126 The raw HCI socket filter defined as follows:
 127 .Bd -literal -offset indent
 128 /*
 129  * Raw HCI socket filter.
 130  *
 131  * For packet mask use (1 << (HCI packet indicator - 1))
 132  * For event mask use (1 << (Event - 1))
 133  */
 134
 135 struct ng_btsocket_hci_raw_filter {
 136         bitstr_t bit_decl(packet_mask, 32);
 137         bitstr_t bit_decl(event_mask, (NG_HCI_EVENT_MASK_SIZE * 8));
 138 };
 139 .Ed
 140 .Pp
 141 The
 142 .Dv SO_HCI_RAW_FILTER
 143 option defined at
 144 .Dv SOL_HCI_RAW
 145 level can be used to obtain via
 146 .Xr getsockopt 2
 147 or change via
 148 .Xr setsockopt 2
 149 raw HCI socket's filter.
 150 .Sh Dv BLUETOOTH_PROTO_L2CAP Sh protocol
 151 The Bluetooth L2CAP socket address is defined as follows:
 152 .Bd -literal -offset indent
 153 /* Bluetooth version of struct sockaddr for L2CAP sockets */
 154 struct sockaddr_l2cap {
 155         u_char    l2cap_len;    /* total length */
 156         u_char    l2cap_family; /* address family */
 157         uint16_t  l2cap_psm;    /* Protocol/Service Multiplexor */
 158         bdaddr_t  l2cap_bdaddr; /* address */
 159 };
 160 .Ed
 161 .Ss Dv SOCK_RAW Ss L2CAP sockets
 162 Implemented by
 163 .Nm btsock_l2c_raw
 164 Netgraph type.
 165 Raw L2CAP sockets do not provide access to raw L2CAP datagrams.
 166 These
 167 sockets used to control L2CAP nodes and to issue special L2CAP requests
 168 such as
 169 .Dv ECHO_REQUEST
 170 and
 171 .Dv GET_INFO
 172 request.
 173 .Pp
 174 Raw L2CAP sockets support number of
 175 .Xr ioctl 2
 176 requests such as:
 177 .Bl -tag -width foo
 178 .It Dv SIOC_L2CAP_NODE_GET_FLAGS
 179 Returns current state for the L2CAP node.
 180 .It Dv SIOC_L2CAP_NODE_GET_DEBUG
 181 Returns current debug level for the L2CAP node.
 182 .It Dv SIOC_L2CAP_NODE_SET_DEBUG
 183 Sets current debug level for the L2CAP node.
 184 .It Dv SIOC_L2CAP_NODE_GET_CON_LIST
 185 Returns list of active baseband connections (i.e., ACL links) for the L2CAP
 186 node.
 187 .It Dv SIOC_L2CAP_NODE_GET_CHAN_LIST
 188 Returns list of active channels for the L2CAP node.
 189 .It Dv SIOC_L2CAP_NODE_GET_AUTO_DISCON_TIMO
 190 Returns current value of the auto disconnect timeout for the L2CAP node.
 191 .It Dv SIOC_L2CAP_NODE_SET_AUTO_DISCON_TIMO
 192 Sets current value of the auto disconnect timeout for the L2CAP node.
 193 .It Dv SIOC_L2CAP_L2CA_PING
 194 Issues L2CAP
 195 .Dv ECHO_REQUEST .
 196 .It Dv SIOC_L2CAP_L2CA_GET_INFO
 197 Issues L2CAP
 198 .Dv GET_INFO
 199 request.
 200 .El
 201 .Pp
 202 The
 203 .Va net.bluetooth.l2cap.sockets.raw.ioctl_timeout
 204 variable, that can be examined and set via
 205 .Xr sysctl 8 ,
 206 controls the control request timeout (in seconds) for raw L2CAP sockets.
 207 .Ss Dv SOCK_SEQPACKET Ss L2CAP sockets
 208 Implemented by
 209 .Nm btsock_l2c
 210 Netgraph type.
 211 L2CAP sockets are either
 212 .Dq active
 213 or
 214 .Dq passive .
 215 Active sockets initiate connections to passive sockets.
 216 By default, L2CAP sockets are created active; to create a passive socket, the
 217 .Xr listen 2
 218 system call must be used after binding the socket with the
 219 .Xr bind 2
 220 system call.
 221 Only passive sockets may use the
 222 .Xr accept 2
 223 call to accept incoming connections.
 224 Only active sockets may use the
 225 .Xr connect 2
 226 call to initiate connections.
 227 .Pp
 228 L2CAP sockets support
 229 .Dq "wildcard addressing" .
 230 In this case, socket must be bound to
 231 .Dv NG_HCI_BDADDR_ANY
 232 address.
 233 Note that PSM (Protocol/Service Multiplexor) field is always required.
 234 Once a connection has been established, the socket's address is
 235 fixed by the peer entity's location.
 236 The address assigned to the socket is
 237 the address associated with the Bluetooth device through which packets are
 238 being transmitted and received, and PSM (Protocol/Service Multiplexor).
 239 .Pp
 240 L2CAP sockets support number of options defined at
 241 .Dv SOL_L2CAP
 242 level which can be set with
 243 .Xr setsockopt 2
 244 and tested with
 245 .Xr getsockopt 2 :
 246 .Bl -tag -width foo
 247 .It Dv SO_L2CAP_IMTU
 248 Get (set) maximum payload size the local socket is capable of accepting.
 249 .It Dv SO_L2CAP_OMTU
 250 Get maximum payload size the remote socket is capable of accepting.
 251 .It Dv SO_L2CAP_IFLOW
 252 Get incoming flow specification for the socket.
 253 .Bf -emphasis
 254 Not implemented.
 255 .Ef
 256 .It Dv SO_L2CAP_OFLOW
 257 Get (set) outgoing flow specification for the socket.
 258 .Bf -emphasis
 259 Not implemented.
 260 .Ef
 261 .It Dv SO_L2CAP_FLUSH
 262 Get (set) value of the flush timeout.
 263 .Bf -emphasis
 264 Not implemented.
 265 .Ef
 266 .El
 267 .Sh Dv BLUETOOTH_PROTO_RFCOMM Sh protocol
 268 The Bluetooth RFCOMM socket address is defined as follows:
 269 .Bd -literal -offset indent
 270 /* Bluetooth version of struct sockaddr for RFCOMM sockets */
 271 struct sockaddr_rfcomm {
 272         u_char   rfcomm_len;     /* total length */
 273         u_char   rfcomm_family;  /* address family */
 274         bdaddr_t rfcomm_bdaddr;  /* address */
 275         uint8_t  rfcomm_channel; /* channel */
 276 };
 277 .Ed
 278 .Ss Dv SOCK_STREAM Ss RFCOMM sockets
 279 Note that RFCOMM sockets do not have associated Netgraph node type.
 280 RFCOMM sockets are implemented as additional layer on top of L2CAP sockets.
 281 RFCOMM sockets are either
 282 .Dq active
 283 or
 284 .Dq passive .
 285 Active sockets initiate connections to passive sockets.
 286 By default, RFCOMM sockets are created active; to create a passive socket, the
 287 .Xr listen 2
 288 system call must be used after binding the socket with the
 289 .Xr bind 2
 290 system call.
 291 Only passive sockets may use the
 292 .Xr accept 2
 293 call to accept incoming connections.
 294 Only active sockets may use the
 295 .Xr connect 2
 296 call to initiate connections.
 297 .Pp
 298 RFCOMM sockets support
 299 .Dq "wildcard addressing" .
 300 In this case, socket must be bound to
 301 .Dv NG_HCI_BDADDR_ANY
 302 address.
 303 Note that RFCOMM channel field is always required.
 304 Once a connection has been established, the socket's address is fixed by the
 305 peer entity's location.
 306 The address assigned to the socket is the address associated with the
 307 Bluetooth device through which packets are being transmitted and received,
 308 and RFCOMM channel.
 309 .Pp
 310 The following options, which can be tested with
 311 .Xr getsockopt 2
 312 call, are defined at
 313 .Dv SOL_RFCOMM
 314 level for RFCOMM sockets:
 315 .Bl -tag -width foo
 316 .It Dv SO_RFCOMM_MTU
 317 Returns the maximum transfer unit size (in bytes) for the underlying RFCOMM
 318 channel.
 319 Note that application still can write/read bigger chunks to/from the socket.
 320 .It Dv SO_RFCOMM_FC_INFO
 321 Return the flow control information for the underlying RFCOMM channel.
 322 .El
 323 .Pp
 324 The
 325 .Va net.bluetooth.rfcomm.sockets.stream.timeout
 326 variable, that can be examined and set via
 327 .Xr sysctl 8 ,
 328 controls the connection timeout (in seconds) for RFCOMM sockets.
 329 .Sh HOOKS
 330 These node types support hooks with arbitrary names (as long as they are
 331 unique) and always accept hook connection requests.
 332 .Sh NETGRAPH CONTROL MESSAGES
 333 These node types support the generic control messages.
 334 .Sh SHUTDOWN
 335 These nodes are persistent and cannot be shut down.
 336 .Sh SEE ALSO
 337 .Xr btsockstat 1 ,
 338 .Xr socket 2 ,
 339 .Xr netgraph 4 ,
 340 .Xr ng_bluetooth 4 ,
 341 .Xr ng_hci 4 ,
 342 .Xr ng_l2cap 4 ,
 343 .Xr ngctl 8 ,
 344 .Xr sysctl 8
 345 .Sh HISTORY
 346 The
 347 .Nm
 348 module was implemented in
 349 .Fx 5.0 .
 350 .Sh AUTHORS
 351 .An Maksim Yevmenkin Aq m_evmenkin@yahoo.com
 352 .Sh BUGS
 353 Most likely.
 354 Please report if found.