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 42The 43.Nm 44module implements three Netgraph node types. 45Each type in its turn implements one protocol within 46.Dv PF_BLUETOOTH 47domain. 48.Sh Dv BLUETOOTH_PROTO_HCI Sh protocol 49.Ss Dv SOCK_RAW Ss HCI sockets 50Implemented by 51.Nm btsock_hci_raw 52Netgraph type. 53Raw HCI sockets allow sending of raw HCI command datagrams 54only to correspondents named in 55.Xr send 2 56calls. 57Raw HCI datagrams (HCI commands, events and data) are generally received with 58.Xr recvfrom 2 , 59which returns the next datagram with its return address. 60Raw HCI sockets can also be used to control HCI nodes. 61.Pp 62The Bluetooth raw HCI socket address is defined as follows: 63.Bd -literal -offset indent 64/* Bluetooth version of struct sockaddr for raw HCI sockets */ 65struct 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 72Raw HCI sockets support a number of 73.Xr ioctl 2 74requests such as: 75.Bl -tag -width foo 76.It Dv SIOC_HCI_RAW_NODE_GET_STATE 77Returns current state for the HCI node. 78.It Dv SIOC_HCI_RAW_NODE_INIT 79Turn on 80.Dq inited 81bit for the HCI node. 82.It Dv SIOC_HCI_RAW_NODE_GET_DEBUG 83Returns current debug level for the HCI node. 84.It Dv SIOC_HCI_RAW_NODE_SET_DEBUG 85Sets current debug level for the HCI node. 86.It Dv SIOC_HCI_RAW_NODE_GET_BUFFER 87Returns current state of data buffers for the HCI node. 88.It Dv SIOC_HCI_RAW_NODE_GET_BDADDR 89Returns BD_ADDR for the HCI node. 90.It Dv SIOC_HCI_RAW_NODE_GET_FEATURES 91Returns the list of features supported by hardware for the HCI node. 92.It Dv SIOC_HCI_RAW_NODE_GET_STAT 93Returns various statistic counters for the HCI node. 94.It Dv SIOC_HCI_RAW_NODE_RESET_STAT 95Resets all statistic counters for the HCI node to zero. 96.It Dv SIOC_HCI_RAW_NODE_FLUSH_NEIGHBOR_CACHE 97Remove all neighbor cache entries for the HCI node. 98.It Dv SIOC_HCI_RAW_NODE_GET_NEIGHBOR_CACHE 99Returns content of the neighbor cache for the HCI node. 100.It Dv SIOC_HCI_RAW_NODE_GET_CON_LIST 101Returns list of active baseband connections (i.e., ACL and SCO links) for 102the HCI node. 103.It SIOC_HCI_RAW_NODE_GET_LINK_POLICY_MASK 104Returns current link policy settings mask for the HCI node. 105.It SIOC_HCI_RAW_NODE_SET_LINK_POLICY_MASK 106Sets current link policy settings mask for the HCI node. 107.It SIOC_HCI_RAW_NODE_GET_PACKET_MASK 108Returns current packet mask for the HCI node. 109.It SIOC_HCI_RAW_NODE_SET_PACKET_MASK 110Sets current packet mask for the HCI node. 111.It SIOC_HCI_RAW_NODE_GET_ROLE_SWITCH 112Returns current value of the role switch parameter for the HCI node. 113.It SIOC_HCI_RAW_NODE_SET_ROLE_SWITCH 114Sets new value of the role switch parameter for the HCI node. 115.El 116.Pp 117The 118.Va net.bluetooth.hci.sockets.raw.ioctl_timeout 119variable, that can be examined and set via 120.Xr sysctl 8 , 121controls the control request timeout (in seconds) for raw HCI sockets. 122.Pp 123Raw HCI sockets support filters. 124The application can filter certain HCI datagram types. 125For HCI event datagrams the application can set additional filter. 126The 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 135struct 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 141The 142.Dv SO_HCI_RAW_FILTER 143option defined at 144.Dv SOL_HCI_RAW 145level can be used to obtain via 146.Xr getsockopt 2 147or change via 148.Xr setsockopt 2 149raw HCI socket's filter. 150.Sh Dv BLUETOOTH_PROTO_L2CAP Sh protocol 151The Bluetooth L2CAP socket address is defined as follows: 152.Bd -literal -offset indent 153/* Bluetooth version of struct sockaddr for L2CAP sockets */ 154struct 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 162Implemented by 163.Nm btsock_l2c_raw 164Netgraph type. 165Raw L2CAP sockets do not provide access to raw L2CAP datagrams. 166These 167sockets used to control L2CAP nodes and to issue special L2CAP requests 168such as 169.Dv ECHO_REQUEST 170and 171.Dv GET_INFO 172request. 173.Pp 174Raw L2CAP sockets support number of 175.Xr ioctl 2 176requests such as: 177.Bl -tag -width foo 178.It Dv SIOC_L2CAP_NODE_GET_FLAGS 179Returns current state for the L2CAP node. 180.It Dv SIOC_L2CAP_NODE_GET_DEBUG 181Returns current debug level for the L2CAP node. 182.It Dv SIOC_L2CAP_NODE_SET_DEBUG 183Sets current debug level for the L2CAP node. 184.It Dv SIOC_L2CAP_NODE_GET_CON_LIST 185Returns list of active baseband connections (i.e., ACL links) for the L2CAP 186node. 187.It Dv SIOC_L2CAP_NODE_GET_CHAN_LIST 188Returns list of active channels for the L2CAP node. 189.It Dv SIOC_L2CAP_NODE_GET_AUTO_DISCON_TIMO 190Returns current value of the auto disconnect timeout for the L2CAP node. 191.It Dv SIOC_L2CAP_NODE_SET_AUTO_DISCON_TIMO 192Sets current value of the auto disconnect timeout for the L2CAP node. 193.It Dv SIOC_L2CAP_L2CA_PING 194Issues L2CAP 195.Dv ECHO_REQUEST . 196.It Dv SIOC_L2CAP_L2CA_GET_INFO 197Issues L2CAP 198.Dv GET_INFO 199request. 200.El 201.Pp 202The 203.Va net.bluetooth.l2cap.sockets.raw.ioctl_timeout 204variable, that can be examined and set via 205.Xr sysctl 8 , 206controls the control request timeout (in seconds) for raw L2CAP sockets. 207.Ss Dv SOCK_SEQPACKET Ss L2CAP sockets 208Implemented by 209.Nm btsock_l2c 210Netgraph type. 211L2CAP sockets are either 212.Dq active 213or 214.Dq passive . 215Active sockets initiate connections to passive sockets. 216By default, L2CAP sockets are created active; to create a passive socket, the 217.Xr listen 2 218system call must be used after binding the socket with the 219.Xr bind 2 220system call. 221Only passive sockets may use the 222.Xr accept 2 223call to accept incoming connections. 224Only active sockets may use the 225.Xr connect 2 226call to initiate connections. 227.Pp 228L2CAP sockets support 229.Dq "wildcard addressing" . 230In this case, socket must be bound to 231.Dv NG_HCI_BDADDR_ANY 232address. 233Note that PSM (Protocol/Service Multiplexor) field is always required. 234Once a connection has been established, the socket's address is 235fixed by the peer entity's location. 236The address assigned to the socket is 237the address associated with the Bluetooth device through which packets are 238being transmitted and received, and PSM (Protocol/Service Multiplexor). 239.Pp 240L2CAP sockets support number of options defined at 241.Dv SOL_L2CAP 242level which can be set with 243.Xr setsockopt 2 244and tested with 245.Xr getsockopt 2 : 246.Bl -tag -width foo 247.It Dv SO_L2CAP_IMTU 248Get (set) maximum payload size the local socket is capable of accepting. 249.It Dv SO_L2CAP_OMTU 250Get maximum payload size the remote socket is capable of accepting. 251.It Dv SO_L2CAP_IFLOW 252Get incoming flow specification for the socket. 253.Bf -emphasis 254Not implemented. 255.Ef 256.It Dv SO_L2CAP_OFLOW 257Get (set) outgoing flow specification for the socket. 258.Bf -emphasis 259Not implemented. 260.Ef 261.It Dv SO_L2CAP_FLUSH 262Get (set) value of the flush timeout. 263.Bf -emphasis 264Not implemented. 265.Ef 266.El 267.Sh Dv BLUETOOTH_PROTO_RFCOMM Sh protocol 268The Bluetooth RFCOMM socket address is defined as follows: 269.Bd -literal -offset indent 270/* Bluetooth version of struct sockaddr for RFCOMM sockets */ 271struct 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 279Note that RFCOMM sockets do not have associated Netgraph node type. 280RFCOMM sockets are implemented as additional layer on top of L2CAP sockets. 281RFCOMM sockets are either 282.Dq active 283or 284.Dq passive . 285Active sockets initiate connections to passive sockets. 286By default, RFCOMM sockets are created active; to create a passive socket, the 287.Xr listen 2 288system call must be used after binding the socket with the 289.Xr bind 2 290system call. 291Only passive sockets may use the 292.Xr accept 2 293call to accept incoming connections. 294Only active sockets may use the 295.Xr connect 2 296call to initiate connections. 297.Pp 298RFCOMM sockets support 299.Dq "wildcard addressing" . 300In this case, socket must be bound to 301.Dv NG_HCI_BDADDR_ANY 302address. 303Note that RFCOMM channel field is always required. 304Once a connection has been established, the socket's address is fixed by the 305peer entity's location. 306The address assigned to the socket is the address associated with the 307Bluetooth device through which packets are being transmitted and received, 308and RFCOMM channel. 309.Pp 310The following options, which can be tested with 311.Xr getsockopt 2 312call, are defined at 313.Dv SOL_RFCOMM 314level for RFCOMM sockets: 315.Bl -tag -width foo 316.It Dv SO_RFCOMM_MTU 317Returns the maximum transfer unit size (in bytes) for the underlying RFCOMM 318channel. 319Note that application still can write/read bigger chunks to/from the socket. 320.It Dv SO_RFCOMM_FC_INFO 321Return the flow control information for the underlying RFCOMM channel. 322.El 323.Pp 324The 325.Va net.bluetooth.rfcomm.sockets.stream.timeout 326variable, that can be examined and set via 327.Xr sysctl 8 , 328controls the connection timeout (in seconds) for RFCOMM sockets. 329.Sh HOOKS 330These node types support hooks with arbitrary names (as long as they are 331unique) and always accept hook connection requests. 332.Sh NETGRAPH CONTROL MESSAGES 333These node types support the generic control messages. 334.Sh SHUTDOWN 335These 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 346The 347.Nm 348module was implemented in 349.Fx 5.0 . 350.Sh AUTHORS 351.An Maksim Yevmenkin Aq m_evmenkin@yahoo.com 352.Sh BUGS 353Most likely. 354Please report if found. 355