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