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.6 2003/03/18 00:09:34 max Exp $ 26.\" $FreeBSD$ 27.\" 28.Dd July 8, 2002 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 bitstring.h 38.In ng_hci.h 39.In ng_l2cap.h 40.In 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[16]; /* HCI node name */ 69}; 70.Ed 71.Pp 72Raw HCI sockets support number of 73.Xr ioctl 2 74requests such as: 75.Bl -tag -width indent 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 u_int16_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 indent 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_L2CA_PING 190Issues L2CAP 191.Dv ECHO_REQUEST . 192.It Dv SIOC_L2CAP_L2CA_GET_INFO 193Issues L2CAP 194.Dv GET_INFO 195request. 196.El 197.Pp 198The 199.Va net.bluetooth.l2cap.sockets.raw.ioctl_timeout 200variable, that can be examined and set via 201.Xr sysctl 8 , 202controls the control request timeout (in seconds) for raw L2CAP sockets. 203.Ss Dv SOCK_SEQPACKET Ss L2CAP sockets 204Implemented by 205.Nm btsock_l2c 206Netgraph type. 207L2CAP sockets are either 208.Dq active 209or 210.Dq passive . 211Active sockets initiate connections to passive sockets. 212By default, L2CAP sockets are created active; to create a passive socket, the 213.Xr listen 2 214system call must be used after binding the socket with the 215.Xr bind 2 216system call. 217Only passive sockets may use the 218.Xr accept 2 219call to accept incoming connections. 220Only active sockets may use the 221.Xr connect 2 222call to initiate connections. 223.Pp 224L2CAP sockets support 225.Dq "wildcard addressing" . 226In this case, socket must be bound to 227.Dv NG_HCI_BDADDR_ANY 228address. 229Note that PSM (Protocol/Service Multiplexor) field is always required. 230Once a connection has been established, the socket's address is 231fixed by the peer entity's location. 232The address assigned to the socket is 233the address associated with the Bluetooth device through which packets are 234being transmitted and received, and PSM (Protocol/Service Multiplexor). 235.Pp 236L2CAP sockets support number of options defined at 237.Dv SOL_L2CAP 238level which can be set with 239.Xr setsockopt 2 240and tested with 241.Xr getsockopt 2 : 242.Bl -tag -width indent 243.It Dv SO_L2CAP_IMTU 244Get (set) maximum payload size the local socket is capable of accepting. 245.It Dv SO_L2CAP_OMTU 246Get maximum payload size the remote socket is capable of accepting. 247.It Dv SO_L2CAP_IFLOW 248Get incoming flow specification for the socket. 249.Bf -emphasis 250Not implemented. 251.Ef 252.It Dv SO_L2CAP_OFLOW 253Get (set) outgoing flow specification for the socket. 254.Bf -emphasis 255Not implemented. 256.Ef 257.It Dv SO_L2CAP_FLUSH 258Get (set) value of the flush timeout. 259.Bf -emphasis 260Not implemented. 261.Ef 262.El 263.Sh Dv BLUETOOTH_PROTO_RFCOMM Sh protocol 264The Bluetooth RFCOMM socket address is defined as follows: 265.Bd -literal -offset indent 266/* Bluetooth version of struct sockaddr for RFCOMM sockets */ 267struct sockaddr_rfcomm { 268 u_char rfcomm_len; /* total length */ 269 u_char rfcomm_family; /* address family */ 270 bdaddr_t rfcomm_bdaddr; /* address */ 271 u_int8_t rfcomm_channel; /* channel */ 272}; 273.Ed 274.Ss Dv SOCK_STREAM Ss RFCOMM sockets 275Note that RFCOMM sockets do not have associated Netgraph node type. 276RFCOMM sockets are implemented as additional layer on top of L2CAP sockets. 277RFCOMM sockets are either 278.Dq active 279or 280.Dq passive . 281Active sockets initiate connections to passive sockets. 282By default, RFCOMM sockets are created active; to create a passive socket, the 283.Xr listen 2 284system call must be used after binding the socket with the 285.Xr bind 2 286system call. 287Only passive sockets may use the 288.Xr accept 2 289call to accept incoming connections. 290Only active sockets may use the 291.Xr connect 2 292call to initiate connections. 293.Pp 294RFCOMM sockets support 295.Dq "wildcard addressing" . 296In this case, socket must be bound to 297.Dv NG_HCI_BDADDR_ANY 298address. 299Note that RFCOMM channel field is always required. 300Once a connection has been established, the socket's address is fixed by the 301peer entity's location. 302The address assigned to the socket is the address associated with the 303Bluetooth device through which packets are being transmitted and received, 304and RFCOMM channel. 305.Pp 306The following options, which can be tested with 307.Xr getsockopt 2 308call, are defined at 309.Dv SOL_RFCOMM 310level for RFCOMM sockets: 311.Bl -tag -width indent 312.It Dv SO_RFCOMM_MTU 313Returns the maximum transfer unit size (in bytes) for the underlying RFCOMM 314channel. 315Note that application still can write/read bigger chunks to/from the socket. 316.It Dv SO_RFCOMM_FC_INFO 317Return the flow control information for the underlying RFCOMM channel. 318.El 319.Pp 320The 321.Va net.bluetooth.rfcomm.sockets.stream.timeout 322variable, that can be examined and set via 323.Xr sysctl 8 , 324controls the connection timeout (in seconds) for RFCOMM sockets. 325.Sh HOOKS 326These node types support hooks with arbitrary names (as long as they are 327unique) and always accept hook connection requests. 328.Sh NETGRAPH CONTROL MESSAGES 329These node types support the generic control messages. 330.Sh SHUTDOWN 331These nodes are persistent and cannot be shut down. 332.Sh BUGS 333Most likely. 334Please report if found. 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 m_evmenkin@yahoo.com 351