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 indent 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.Pp 213.Bl -tag -width indent 214.It Dv hci 215Bluetooth Host Controller Interface downstream hook. 216.It Dv l2c 217Upper layer protocol upstream hook. 218Usually the Bluetooth L2CAP socket layer is connected to the hook. 219.It Dv ctl 220Control hook. 221Usually the Bluetooth raw L2CAP sockets layer is connected to the hook. 222.El 223.Sh INTERFACE TO THE UPPER LAYER PROTOCOLS (L2CA CONTROL MESSAGES) 224Bluetooth specification says that L2CA request must block until response 225is ready. 226L2CAP node uses 227.Va token 228field from Netgraph message header to match L2CA request and response. 229The upper layer protocol must populate 230.Va token . 231L2CAP node will queue request and start processing. 232Later, when response is 233ready or timeout has occurred, L2CAP node will create new Netgraph message, set 234.Va token 235and 236.Dv NFG_RESP 237flag and send message to the upper layer. 238Note that L2CA indication messages 239will not populate 240.Va token 241and will not set 242.Dv NGF_RESP 243flag. 244There is no reason for this, because they are just notifications and do 245not require acknowledgment. 246.Bl -tag -width indent 247.It Dv NGM_L2CAP_L2CA_CON 248Requests the creation of a channel representing a logical connection to a 249physical address. 250Input parameters are the target protocol (PSM) and remote 251device's 48-bit address (BD_ADDR). 252Output parameters are the local CID (LCID) 253allocated by the local L2CAP entity, and Result of the request. 254If Result 255indicates a pending notification, the Status value may contain more information 256of what processing is delaying the establishment of the connection. 257.It Dv NGM_L2CAP_L2CA_CON_IND 258This message includes the parameters for the address of the remote device that 259issued the connection request, the local CID representing the channel being 260requested, the Identifier contained in the request, and the PSM value the 261request is targeting. 262.It Dv NGM_L2CAP_L2CA_CON_RSP 263Issues a response to a connection request event indication. 264Input parameters 265are the remote device's 48-bit address, Identifier sent in the request, local 266CID, the Response code, and the Status attached to the Response code. 267The output parameter is the Result of the service request. 268This primitive must be 269called no more than once after receiving the indication. 270.It Dv NGM_L2CAP_L2CA_CFG 271Requests the initial configuration (or reconfiguration) of a channel to a new 272set of channel parameters. 273Input parameters are the local CID endpoint, new 274incoming receivable MTU (InMTU), new outgoing flow spec-ification, and flush 275and link timeouts. 276Output parameters are the Result, accepted incoming MTU 277(InMTU), the remote side's flow requests, and flush and link timeouts. 278.It Dv NGM_L2CAP_L2CA_CFG_IND 279This message includes the parameters indicating the local CID of the channel 280the request has been sent to, the outgoing MTU size (maximum packet that can 281be sent across the channel) and the flowspec describing the characteristics of 282the incoming data. 283All other channel parameters are set to their default values 284if not provided by the remote device. 285.It Dv NGM_L2CAP_L2CA_CFG_RSP 286Issues a response to a configuration request event indication. 287Input parameters 288include the local CID of the endpoint being configured, outgoing transmit MTU 289(which may be equal or less to the OutMTU parameter in the configuration 290indication event) and the accepted flowspec for incoming traffic. 291The output parameter is the Result value. 292.It Dv NGM_L2CAP_L2CA_QOS_IND 293This message includes the parameter indicating the address of the remote 294Bluetooth device where the QoS contract has been violated. 295.It Dv NGM_L2CAP_L2CA_DISCON 296Requests the disconnection of the channel. 297Input parameter is the CID representing the local channel endpoint. 298Output parameter is Result. 299Result 300is zero if an L2CAP Disconnect Response is received, otherwise a non-zero value 301is returned. 302Once disconnection has been requested, no process will be able to 303successfully read or write from the CID. 304.It Dv NGM_L2CAP_L2CA_DISCON_IND 305This message includes the parameter indicating the local CID the request has 306been sent to. 307.It Dv NGM_L2CAP_L2CA_WRITE 308Response to transfer of data request. 309Actual data must be received from 310appropriate upstream hook and must be prepended with header defined as follows. 311.Bd -literal -offset indent 312/* L2CA data packet header */ 313typedef struct { 314 u_int32_t token; /* token to use in L2CAP_L2CA_WRITE */ 315 u_int16_t length; /* length of the data */ 316 u_int16_t lcid; /* local channel ID */ 317} __attribute__ ((packed)) ng_l2cap_l2ca_hdr_t; 318.Ed 319.Pp 320The output parameters are Result and Length of data written. 321.It Dv NGM_L2CAP_L2CA_GRP_CREATE 322Requests the creation of a CID to represent a logical connection to multiple 323devices. 324Input parameter is the PSM value that the outgoing connectionless 325traffic is labelled with, and the filter used for incoming traffic. 326Output parameter is the CID representing the local endpoint. 327On creation, the group 328is empty but incoming traffic destined for the PSM value is readable. 329.Bf -emphasis 330This request has not been implemented. 331.Ef 332.It Dv NGM_L2CAP_L2CA_GRP_CLOSE 333The use of this message closes down a Group. 334.Bf -emphasis 335This request has not been implemented. 336.Ef 337.It Dv NGM_L2CAP_L2CA_GRP_ADD_MEMBER 338Requests the addition of a member to a group. 339The input parameter includes the 340CID representing the group and the BD_ADDR of the group member to be added. 341The output parameter Result confirms the success or failure of the request. 342.Bf -emphasis 343This request has not been implemented. 344.Ef 345.It Dv NGM_L2CAP_L2CA_GRP_REM_MEMBER 346Requests the removal of a member from a group. 347The input parameters include 348the CID representing the group and BD_ADDR of the group member to be removed. 349The output parameter Result confirms the success or failure of the request. 350.Bf -emphasis 351This request has not been implemented. 352.Ef 353.It Dv NGM_L2CAP_L2CA_GRP_MEMBERSHIP 354Requests a report of the members of a group. 355The input parameter CID represents the group being queried. 356The output parameter Result confirms the success or 357failure of the operation. 358If the Result is successful, BD_ADDR_Lst is a list 359of the Bluetooth addresses of the N members of the group. 360.Bf -emphasis 361This request has not been implemented. 362.Ef 363.It Dv NGM_L2CAP_L2CA_PING 364Initiates an L2CA Echo Request message and the reception of the corresponding 365L2CAP Echo Response message. 366The input parameters are remote Bluetooth device 367BD_ADDR, Echo Data and Length of the echo data. 368The output parameters are 369Result, Echo Data and Length of the echo data. 370.It Dv NGM_L2CAP_L2CA_GET_INFO 371Initiates an L2CA Information Request message and the reception of the 372corresponding L2CAP Info Response message. 373The input parameters are remote Bluetooth device BD_ADDR and Information Type. 374The output parameters are 375Result, Information Data and Size of the information data. 376.It Dv NGM_L2CAP_L2CA_ENABLE_CLT 377Request to disable (enable) the reception of connectionless packets. 378The input 379parameter is the PSM value indicating service that should be blocked 380(unblocked) and Enable flag. 381.El 382.Sh NETGRAPH CONTROL MESSAGES 383This node type supports the generic control messages, plus the following: 384.Bl -tag -width indent 385.It Dv NGM_L2CAP_NODE_GET_FLAGS 386Returns current state for the node. 387.It Dv NGM_L2CAP_NODE_GET_DEBUG 388Returns an integer containing the current debug level for the node. 389.It Dv NGM_L2CAP_NODE_SET_DEBUG 390This command takes an integer argument and sets current debug level 391for the node. 392.It Dv NGM_L2CAP_NODE_GET_CON_LIST 393Returns list of active baseband connections (i.e., ACL links). 394.It Dv NGM_L2CAP_NODE_GET_CHAN_LIST 395Returns list of active L2CAP channels. 396.It Dv NGM_L2CAP_NODE_GET_AUTO_DISCON_TIMO 397Returns an integer containing the current value of the auto disconnect 398timeout (in sec). 399.It Dv NGM_L2CAP_NODE_SET_AUTO_DISCON_TIMO 400This command accepts an integer and sets the value of the auto disconnect 401timeout (in sec). 402The special value of 0 (zero) disables auto disconnect timeout. 403.El 404.Sh SHUTDOWN 405This node shuts down upon receipt of an 406.Dv NGM_SHUTDOWN 407control message, or 408when all hooks have been disconnected. 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.Sh BUGS 422Most likely. 423Please report if found. 424