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