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