share/man/man4/ng_l2cap.4

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