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