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