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.\" $FreeBSD$ 26.\" 27.Dd July 4, 2002 28.Dt NG_L2CAP 4 29.Os 30.Sh NAME 31.Nm ng_l2cap 32.Nd Netgraph node type that implements Bluetooth Logical Link Control and 33Adaptation Protocol (L2CAP) 34.Sh SYNOPSIS 35.In sys/types.h 36.In netgraph/ng_message.h 37.In netgraph/netgraph.h 38.In netgraph/ng_hci.h 39.In netgraph/ng_l2cap.h 40.Sh DESCRIPTION 41The 42.Nm l2cap 43node type is a Netgraph node type that implements Bluetooth Logical Link 44Control and Adaptation Protocol as per chapter D of the Bluetooth Specification 45Book v1.1. 46.Pp 47L2CAP provides connection-oriented and connectionless data services to upper 48layer protocols with protocol multiplexing capability, segmentation and 49reassembly operation, and group abstractions. 50L2CAP permits higher level 51protocols and applications to transmit and receive L2CAP data packets up to 5264 kilobytes in length. 53.Ss L2CAP Assumptions 54.Bl -enum -offset indent 55.It 56The ACL link between two units is set up. 57The Baseband provides orderly 58delivery of data packets, although there might be individual packet corruption 59and duplicates. 60No more than 1 ACL link exists between any two devices. 61.It 62The Baseband always provides the impression of full-duplex communication 63channels. 64This does not imply that all L2CAP communications are bi-directional. 65Multicasts and unidirectional traffic (e.g., video) do not require duplex 66channels. 67.It 68L2CAP provides a reliable channel using the mechanisms available at the 69Baseband layer. 70The Baseband always performs data integrity checks when 71requested and resends data until it has been successfully acknowledged or 72a timeout occurs. 73Because acknowledgements may be lost, timeouts may 74occur even after the data has been successfully sent. 75.El 76.Sh L2CAP GENERAL OPERATION 77The Logical Link Control and Adaptation Protocol (L2CAP) is based around the 78concept of 79.Dq channels . 80Each channel is bound to a single protocol in a many-to-one fashion. 81Multiple 82channels can be bound to the same protocol, but a channel cannot be bound to 83multiple protocols. 84Each L2CAP packet received on a channel is directed to 85the appropriate higher level protocol. 86.Pp 87Each one of the end-points of an L2CAP channel is referred to by a channel 88identifier. 89Channel identifiers (CIDs) are local names representing a logical 90channel end-point on the device. 91Identifiers from 0x0001 to 0x003F are reserved 92for specific L2CAP functions. 93The null identifier (0x0000) is defined as an 94illegal identifier and must never be used as a destination end-point. 95All L2CAP signalling commands are sent to CID 0x0001. 96CID 0x0002 is reserved for group-oriented channel. 97The same CID must not be reused as a local L2CAP 98channel endpoint for multiple simultaneous L2CAP channels between a local 99device and some remote device. 100.Pp 101CID assignment is relative to a particular device and a device can assign CIDs 102independently from other devices. 103Thus, even if the same CID value has been 104assigned to (remote) channel endpoints by several remote devices connected 105to a single local device, the local device can still uniquely associate each 106remote CID with a different device. 107.Ss Channel Operational States 108.Bl -tag -width indent 109.It Dv NG_L2CAP_CLOSED 110In this state, there is no channel associated with this CID. 111This is the only 112state when a link level connection (Baseband) may not exist. 113Link disconnection 114forces all other states into the 115.Dv NG_L2CAP_CLOSED 116state. 117.It Dv NG_L2CAP_W4_L2CAP_CON_RSP 118In this state, the CID represents a local end-point and an L2CAP Connect 119Request message has been sent referencing this endpoint and it is now waiting 120for the corresponding L2CAP Connect Response message. 121.It Dv NG_L2CAP_W4_L2CA_CON_RSP 122In this state, the remote end-point exists and an L2CAP Connect Request has 123been received by the local L2CAP entity. 124An L2CA Connect Indication has been 125sent to the upper layer and the part of the local L2CAP entity processing the 126received L2CAP Connect Request waits for the corresponding response. 127The response may require a security check to be performed. 128.It Dv NG_L2CAP_CONFIG 129In this state, the connection has been established but both sides are still 130negotiating the channel parameters. 131The Configuration state may also be 132entered when the channel parameters are being renegotiated. 133Prior to entering 134the 135.Dv NG_L2CAP_CONFIG 136state, all outgoing data traffic is suspended since 137the traffic parameters of the data traffic are to be renegotiated. 138Incoming 139data traffic is accepted until the remote channel endpoint has entered 140the 141.Dv NG_L2CAP_CONFIG 142state. 143In the 144.Dv NG_L2CAP_CONFIG 145state, both sides will issue 146L2CAP Configuration Request messages if only defaults are being used, a null 147message will be sent. 148If a large amount of parameters need to be negotiated, 149multiple messages will be sent to avoid any MTU limitations and negotiate 150incrementally. 151Moving from the 152.Dv NG_L2CAP_CONFIG 153state to the 154.Dv NG_L2CAP_OPEN 155state 156requires both sides to be ready. 157An L2CAP entity is ready when it has received 158a positive response to its final request and it has positively responded to 159the final request from the remote device. 160.It Dv NG_L2CAP_OPEN 161In this state, the connection has been established and configured, and data 162flow may proceed. 163.It Dv NG_L2CAP_W4_L2CAP_DISCON_RSP 164In this state, the connection is shutting down and an L2CAP Disconnect Request 165message has been sent. 166This state is now waiting for the corresponding response. 167.It Dv NG_L2CAP_W4_L2CA_DISCON_RSP 168In this state, the connection on the remote endpoint is shutting down and an 169L2CAP Disconnect Request message has been received. 170An L2CA Disconnect 171Indication has been sent to the upper layer to notify the owner of the CID 172that the remote endpoint is being closed. 173This state is now waiting for the 174corresponding response from the upper layer before responding to the remote 175endpoint. 176.El 177.Ss Protocol Multiplexing 178L2CAP supports protocol multiplexing because the Baseband Protocol does not 179support any 180.Dq type 181field identifying the higher layer protocol being multiplexed above it. 182L2CAP is able to distinguish between upper layer protocols such as the Service 183Discovery Protocol, RFCOMM and Telephony Control. 184.Ss Segmentation and Reassembly 185The data packets defined by the Baseband Protocol are limited in size. 186Large 187L2CAP packets must be segmented into multiple smaller Baseband packets prior 188to their transmission over the air. 189Similarly, multiple received Baseband 190packets may be reassembled into a single larger L2CAP packet. 191.Ss Quality of Service 192The L2CAP connection establishment process allows the exchange of information 193regarding the quality of service (QoS) expected between two Bluetooth units. 194.Ss Groups 195The Baseband Protocol supports the concept of a piconet, a group of devices 196synchronously hopping together using the same clock. 197The L2CAP group 198abstraction permits implementations to efficiently map protocol groups on to 199piconets. 200.Pp 201The following features are outside the scope of L2CAP responsibilities: 202.Bl -dash -offset indent 203.It 204L2CAP does not transport audio designated for SCO links. 205.It 206L2CAP does not enforce a reliable channel or ensure data integrity, 207that is, L2CAP performs no retransmissions or checksum calculations. 208.It 209L2CAP does not support a reliable multicast channel. 210.It 211L2CAP does not support the concept of a global group name. 212.El 213.Sh HOOKS 214This node type supports the following hooks: 215.Pp 216.Bl -tag -width foobar 217.It Dv hci 218Bluetooth Host Controller Interface downstream hook. 219.It Dv l2c 220Upper layer protocol upstream hook. 221Usually Bluetooth L2CAP sockets layer 222is connected to the hook. 223.It Dv ctl 224Control hook. 225Usually Bluetooth raw L2CAP sockets layer is connected to the hook. 226.El 227.Sh INTERFACE TO THE UPPER LAYER PROTOCOLS (L2CA CONTROL MESSAGES) 228Bluetooth specification says that L2CA request must block until response 229is ready. 230L2CAP node uses 231.Va token 232field from Netgraph message header to match L2CA request and response. 233The upper layer protocol must populate 234.Va token . 235L2CAP node will queue request and start processing. 236Later, when response is 237ready or timeout has occured, L2CAP node will create new Netgraph message, set 238.Va token 239and 240.Dv NFG_RESP 241flag and send message to the upper layer. 242Note that L2CA indication messages 243will not populate 244.Va token 245and will not set 246.Dv NGF_RESP 247flag. 248There is no reason for this, because they are just notifications and do 249not require acknowledgment. 250.Bl -tag -width indent 251.It Dv NGM_L2CAP_L2CA_CON 252Requests the creation of a channel representing a logical connection to a 253physical address. 254Input parameters are the target protocol (PSM) and remote 255device's 48-bit address (BD_ADDR). 256Output parameters are the local CID (LCID) 257allocated by the local L2CAP entity, and Result of the request. 258If Result 259indicates a pending notification, the Status value may contain more information 260of what processing is delaying the establishment of the connection. 261.It Dv NGM_L2CAP_L2CA_CON_IND 262This message includes the parameters for the address of the remote device that 263issued the connection request, the local CID representing the channel being 264requested, the Identifier contained in the request, and the PSM value the 265request is targeting. 266.It Dv NGM_L2CAP_L2CA_CON_RSP 267Issues a response to a connection request event indication. 268Input parameters 269are the remote device's 48-bit address, Identifier sent in the request, local 270CID, the Response code, and the Status attached to the Response code. 271The output parameter is the Result of the service request. 272This primitive must be 273called no more than once after receiving the indication. 274.It Dv NGM_L2CAP_L2CA_CFG 275Requests the initial configuration (or reconfiguration) of a channel to a new 276set of channel parameters. 277Input parameters are the local CID endpoint, new 278incoming receivable MTU (InMTU), new outgoing flow spec-ification, and flush 279and link timeouts. 280Output parameters are the Result, accepted incoming MTU 281(InMTU), the remote side's flow requests, and flush and link timeouts. 282.It Dv NGM_L2CAP_L2CA_CFG_IND 283This message includes the parameters indicating the local CID of the channel 284the request has been sent to, the outgoing MTU size (maximum packet that can 285be sent across the channel) and the flowspec describing the characteristics of 286the incoming data. 287All other channel parameters are set to their default values 288if not provided by the remote device. 289.It Dv NGM_L2CAP_L2CA_CFG_RSP 290Issues a response to a configuration request event indication. 291Input parameters 292include the local CID of the endpoint being configured, outgoing transmit MTU 293(which may be equal or less to the OutMTU parameter in the configuration 294indication event) and the accepted flowspec for incoming traffic. 295The output parameter is the Result value. 296.It Dv NGM_L2CAP_L2CA_QOS_IND 297This message includes the parameter indicating the address of the remote 298Bluetooth device where the QoS contract has been violated. 299.It Dv NGM_L2CAP_L2CA_DISCON 300Requests the disconnection of the channel. 301Input parameter is the CID representing the local channel endpoint. 302Output parameter is Result. 303Result 304is zero if a L2CAP Disconnect Response is received, otherwise a non-zero value 305is returned. 306Once disconnection has been requested, no process will be able to 307successfully read or write from the CID. 308.It Dv NGM_L2CAP_L2CA_DISCON_IND 309This message includes the parameter indicating the local CID the request has 310been sent to. 311.It Dv NGM_L2CAP_L2CA_WRITE 312Response to transfer of data request. 313Actual data must be received from 314appropriate upstream hook and must be prepended with header defined as follows. 315.Bd -literal -offset indent 316/* L2CA data packet header */ 317typedef struct { 318 u_int32_t token; /* token to use in L2CAP_L2CA_WRITE */ 319 u_int16_t length; /* length of the data */ 320 u_int16_t lcid; /* local channel ID */ 321} __attribute__ ((packed)) ng_l2cap_l2ca_hdr_t; 322.Ed 323.Pp 324The output parameters are Result and Length of data written. 325.It Dv NGM_L2CAP_L2CA_GRP_CREATE 326Requests the creation of a CID to represent a logical connection to multiple 327devices. 328Input parameter is the PSM value that the outgoing connectionless 329traffic is labelled with, and the filter used for incoming traffic. 330Output parameter is the CID representing the local endpoint. 331On creation, the group 332is empty but incoming traffic destined for the PSM value is readable. 333.Bf -emphasis 334This request has not been implemented. 335.Ef 336.It Dv NGM_L2CAP_L2CA_GRP_CLOSE 337The use of this message closes down a Group. 338.Bf -emphasis 339This request has not been implemented. 340.Ef 341.It Dv NGM_L2CAP_L2CA_GRP_ADD_MEMBER 342Requests the addition of a member to a group. 343The input parameter includes the 344CID representing the group and the BD_ADDR of the group member to be added. 345The output parameter Result confirms the success or failure of the request. 346.Bf -emphasis 347This request has not been implemented. 348.Ef 349.It Dv NGM_L2CAP_L2CA_GRP_REM_MEMBER 350Requests the removal of a member from a group. 351The input parameters include 352the CID representing the group and BD_ADDR of the group member to be removed. 353The output parameter Result confirms the success or failure of the request. 354.Bf -emphasis 355This request has not been implemented. 356.Ef 357.It Dv NGM_L2CAP_L2CA_GRP_MEMBERSHIP 358Requests a report of the members of a group. 359The input parameter CID represents the group being queried. 360The output parameter Result confirms the success or 361failure of the operation. 362If the Result is successful, BD_ADDR_Lst is a list 363of the Bluetooth addresses of the N members of the group. 364.Bf -emphasis 365This request has not been implemented. 366.Ef 367.It Dv NGM_L2CAP_L2CA_PING 368Initiates a L2CA Echo Request message and the reception of the corresponding 369L2CAP Echo Response message. 370The input parameters are remote Bluetooth device 371BD_ADDR, Echo Data and Length of the echo data. 372The output parameters are 373Result, Echo Data and Length of the echo data. 374.It Dv NGM_L2CAP_L2CA_GET_INFO 375Initiates a L2CA Information Request message and the reception of the 376corresponding L2CAP Info Response message. 377The input parameters are remote Bluetooth device BD_ADDR and Information Type. 378The output parameters are 379Result, Information Data and Size of the information data. 380.It Dv NGM_L2CAP_L2CA_ENABLE_CLT 381Request to disable (enable) the reception of connectionless packets. 382The input 383parameter is the PSM value indicating service that should be blocked 384(unblocked) and Enable flag. 385.El 386.Sh NETGRAPH CONTROL MESSAGES 387This node type supports the generic control messages, plus the following: 388.Bl -tag -width indent 389.It Dv NGM_L2CAP_NODE_GET_FLAGS 390Returns current state for the node. 391.It Dv NGM_L2CAP_NODE_GET_DEBUG 392Returns an integer containing the current debug level for the node. 393.It Dv NGM_L2CAP_NODE_SET_DEBUG 394This command takes an integer argument and sets current debug level 395for the node. 396.It Dv NGM_L2CAP_NODE_GET_CON_LIST 397Returns list of active baseband connections (i.e. ACL links). 398.It Dv NGM_L2CAP_NODE_GET_CHAN_LIST 399Returns list of active L2CAP channels. 400.El 401.Sh SHUTDOWN 402This node shuts down upon receipt of an 403.Dv NGM_SHUTDOWN 404control message, or 405when all hooks have been disconnected. 406.Sh BUGS 407Most likely. 408Please report if found. 409.Sh SEE ALSO 410.Xr netgraph 4 , 411.Xr l2control 8 , 412.Xr l2ping 8 , 413.Xr ngctl 8 414.Sh HISTORY 415The 416.Nm l2cap 417node type was implemented in 418.Fx 5.0 . 419.Sh AUTHORS 420.An Maksim Yevmenkin Aq m_evmenkin@yahoo.com 421