ng_l2cap(4)

NAME

ng_l2cap - Netgraph node type that implements Bluetooth Log

ical Link Control and Adaptation Protocol (L2CAP)

SYNOPSIS

#include <sys/types.h>
#include <netgraph/bluetooth/include/ng_hci.h>
#include <netgraph/bluetooth/include/ng_l2cap.h>

DESCRIPTION

The l2cap node type is a Netgraph node type that implements

Bluetooth
Logical Link Control and Adaptation Protocol as per chapter

D of the
Bluetooth Specification Book v1.1.

L2CAP provides connection-oriented and connectionless data

services to
upper layer protocols with protocol multiplexing capability,

segmentation
and reassembly operation, and group abstractions. L2CAP

permits higher
level protocols and applications to transmit and receive

L2CAP data packets up to 64 kilobytes in length.

L2CAP Assumptions

1. The ACL link between two units is set up. The

Baseband pro
vides orderly delivery of data packets, although

there might
be individual packet corruption and duplicates.

No more than
one ACL link exists between any two devices.

2. The Baseband always provides the impression of

full-duplex
communication channels. This does not imply that

all L2CAP
communications are bi-directional. Multicasts

and unidirectional traffic (e.g., video) do not require du

plex channels.

3. L2CAP provides a reliable channel using the mech

anisms avail
able at the Baseband layer. The Baseband always

performs data
integrity checks when requested and resends data

until it has
been successfully acknowledged or a timeout oc

curs. As
acknowledgements may be lost, timeouts may occur

even after
the data has been successfully sent.

L2CAP GENERAL OPERATION

The Logical Link Control and Adaptation Protocol (L2CAP) is

based around
the concept of ``channels''. Each channel is bound to a

single protocol
in a many-to-one fashion. Multiple channels can be bound to

the same
protocol, but a channel cannot be bound to multiple proto

cols. Each
L2CAP packet received on a channel is directed to the appro

priate higher
level protocol.

Each one of the end-points of an L2CAP channel is referred

to by a channel identifier. Channel identifiers (CIDs) are local names

representing
a logical channel end-point on the device. Identifiers from

0x0001 to
0x003F are reserved for specific L2CAP functions. The null

identifier
(0x0000) is defined as an illegal identifier and must never

be used as a
destination end-point. All L2CAP signalling commands are

sent to CID
0x0001. CID 0x0002 is reserved for group-oriented channel.

The same CID
must not be reused as a local L2CAP channel endpoint for

multiple simultaneous L2CAP channels between a local device and some re

mote device.

CID assignment is relative to a particular device and a de

vice can assign
CIDs independently from other devices. Thus, even if the

same CID value
has been assigned to (remote) channel endpoints by several

remote devices
connected to a single local device, the local device can

still uniquely
associate each remote CID with a different device.

Channel Operational States

NG_L2CAP_CLOSED
In this state, there is no channel associated with

this CID.
This is the only state when a link level connection

(Baseband)
may not exist. Link disconnection forces all other

states into
the NG_L2CAP_CLOSED state.

NG_L2CAP_W4_L2CAP_CON_RSP
In this state, the CID represents a local end-point

and an L2CAP
Connect Request message has been sent referencing

this endpoint
and it is now waiting for the corresponding L2CAP

Connect
Response message.

NG_L2CAP_W4_L2CA_CON_RSP
In this state, the remote end-point exists and an

L2CAP Connect
Request has been received by the local L2CAP entity.

An L2CA
Connect Indication has been sent to the upper layer

and the part
of the local L2CAP entity processing the received

L2CAP Connect
Request waits for the corresponding response. The

response may
require a security check to be performed.

NG_L2CAP_CONFIG
In this state, the connection has been established

but both sides
are still negotiating the channel parameters. The

Configuration
state may also be entered when the channel parame

ters are being
renegotiated. Prior to entering the NG_L2CAP_CONFIG

state, all
outgoing data traffic is suspended since the traffic

parameters
of the data traffic are to be renegotiated. Incom

ing data traffic is accepted until the remote channel endpoint

has entered the
NG_L2CAP_CONFIG state. In the NG_L2CAP_CONFIG

state, both sides
will issue L2CAP Configuration Request messages if

only defaults
are being used, a null message will be sent. If a

large amount
of parameters need to be negotiated, multiple mes

sages will be
sent to avoid any MTU limitations and negotiate in

crementally.
Moving from the NG_L2CAP_CONFIG state to the

NG_L2CAP_OPEN state
requires both sides to be ready. An L2CAP entity is

ready when
it has received a positive response to its final re

quest and it
has positively responded to the final request from

the remote
device.

NG_L2CAP_OPEN
In this state, the connection has been established

and configured, and data flow may proceed.

NG_L2CAP_W4_L2CAP_DISCON_RSP
In this state, the connection is shutting down and

an L2CAP Disconnect Request message has been sent. This state

is now waiting
for the corresponding response.

NG_L2CAP_W4_L2CA_DISCON_RSP
In this state, the connection on the remote endpoint

is shutting
down and an L2CAP Disconnect Request message has

been received.
An L2CA Disconnect Indication has been sent to the

upper layer to
notify the owner of the CID that the remote endpoint

is being
closed. This state is now waiting for the corre

sponding response
from the upper layer before responding to the remote

endpoint.

Protocol Multiplexing
L2CAP supports protocol multiplexing because the Baseband

Protocol does
not support any ``type'' field identifying the higher layer

protocol
being multiplexed above it. L2CAP is able to distinguish

between upper
layer protocols such as the Service Discovery Protocol, RF

COMM and Telephony Control.

Segmentation and ReassemblyThe data packets defined by the Baseband Protocol are limit

ed in size.
Large L2CAP packets must be segmented into multiple smaller

Baseband
packets prior to their transmission over the air. Similar

ly, multiple
received Baseband packets may be reassembled into a single

larger L2CAP
packet.

Quality of ServiceThe L2CAP connection establishment process allows the ex

change of information regarding the quality of service (QoS) expected be

tween two Bluetooth units.

Groups
The Baseband Protocol supports the concept of a piconet, a

group of
devices synchronously hopping together using the same clock.

The L2CAP
group abstraction permits implementations to efficiently map

protocol
groups on to piconets.

The following features are outside the scope of L2CAP re

sponsibilities:

- L2CAP does not transport audio designated for SCO

links.

- L2CAP does not enforce a reliable channel or en

sure dataintegrity, that is, L2CAP performs no retransmis

sions or checksum calculations.

- L2CAP does not support a reliable multicast chan

nel.

- L2CAP does not support the concept of a global

group name.

HOOKS

This node type supports the following hooks:

hci Bluetooth Host Controller Interface downstream hook.

l2c Upper layer protocol upstream hook. Usually the

Bluetooth L2CAP
socket layer is connected to the hook.

ctl Control hook. Usually the Bluetooth raw L2CAP sock

ets layer is
connected to the hook.

INTERFACE TO THE UPPER LAYER PROTOCOLS (L2CA CONTROL MESSAGES)

Bluetooth specification says that L2CA request must block

until response
is ready. L2CAP node uses token field from Netgraph message

header to
match L2CA request and response. The upper layer protocol

must populate
token. L2CAP node will queue request and start processing.

Later, when
response is ready or timeout has occurred, L2CAP node will

create new
Netgraph message, set token and NFG_RESP flag and send mes

sage to the
upper layer. Note that L2CA indication messages will not

populate token
and will not set NGF_RESP flag. There is no reason for

this, because
they are just notifications and do not require acknowledg

ment.

NGM_L2CAP_L2CA_CON
Requests the creation of a channel representing a

logical connection to a physical address. Input parameters are

the target protocol (PSM) and remote device's 48-bit address

(BD_ADDR). Output
parameters are the local CID (LCID) allocated by the

local L2CAP
entity, and Result of the request. If Result indi

cates a pending
notification, the Status value may contain more in

formation of
what processing is delaying the establishment of the

connection.

NGM_L2CAP_L2CA_CON_IND
This message includes the parameters for the address

of the
remote device that issued the connection request,

the local CID
representing the channel being requested, the Iden

tifier contained in the request, and the PSM value the request

is targeting.

NGM_L2CAP_L2CA_CON_RSPIssues a response to a connection request event in

dication.
Input parameters are the remote device's 48-bit ad

dress, Identifier sent in the request, local CID, the Response

code, and the
Status attached to the Response code. The output

parameter is
the Result of the service request. This primitive

must be called
no more than once after receiving the indication.

NGM_L2CAP_L2CA_CFGRequests the initial configuration (or reconfigura

tion) of a
channel to a new set of channel parameters. Input

parameters are
the local CID endpoint, new incoming receivable MTU

(InMTU), new
outgoing flow spec-ification, and flush and link

timeouts. Output parameters are the Result, accepted incoming MTU

(InMTU), the
remote side's flow requests, and flush and link

timeouts.

NGM_L2CAP_L2CA_CFG_IND
This message includes the parameters indicating the

local CID of
the channel the request has been sent to, the outgo

ing MTU size
(maximum packet that can be sent across the channel)

and the
flowspec describing the characteristics of the in

coming data.
All other channel parameters are set to their de

fault values if
not provided by the remote device.

NGM_L2CAP_L2CA_CFG_RSP
Issues a response to a configuration request event

indication.
Input parameters include the local CID of the end

point being configured, outgoing transmit MTU (which may be equal

or less to the
OutMTU parameter in the configuration indication

event) and the
accepted flowspec for incoming traffic. The output

parameter is
the Result value.

NGM_L2CAP_L2CA_QOS_IND
This message includes the parameter indicating the

address of the
remote Bluetooth device where the QoS contract has

been violated.

NGM_L2CAP_L2CA_DISCON
Requests the disconnection of the channel. Input

parameter is
the CID representing the local channel endpoint.

Output parameter is Result. Result is zero if an L2CAP Discon

nect Response is
received, otherwise a non-zero value is returned.

Once disconnection has been requested, no process will be able

to successfully read or write from the CID.

NGM_L2CAP_L2CA_DISCON_IND
This message includes the parameter indicating the

local CID the
request has been sent to.

NGM_L2CAP_L2CA_WRITE
Response to transfer of data request. Actual data

must be
received from appropriate upstream hook and must be

prepended
with header defined as follows.

/* L2CA data packet header */
typedef struct {
u_int32_t token; /* token to use in

L2CAP_L2CA_WRITE */
u_int16_t length; /* length of the da

ta */
u_int16_t lcid; /* local channel ID

*/

} __attribute__ ((packed))

ng_l2cap_l2ca_hdr_t;

The output parameters are Result and Length of data

written.

NGM_L2CAP_L2CA_GRP_CREATERequests the creation of a CID to represent a logi

cal connection
to multiple devices. Input parameter is the PSM

value that the
outgoing connectionless traffic is labelled with,

and the filter
used for incoming traffic. Output parameter is the

CID representing the local endpoint. On creation, the group

is empty but
incoming traffic destined for the PSM value is read

able. This
request has not been implemented.

NGM_L2CAP_L2CA_GRP_CLOSE
The use of this message closes down a Group. This

request has
not been implemented.

NGM_L2CAP_L2CA_GRP_ADD_MEMBER
Requests the addition of a member to a group. The

input parameter includes the CID representing the group and the

BD_ADDR of
the group member to be added. The output parameter

Result confirms the success or failure of the request. This

request has
not been implemented.

NGM_L2CAP_L2CA_GRP_REM_MEMBER
Requests the removal of a member from a group. The

input parameters include the CID representing the group and

BD_ADDR of the
group member to be removed. The output parameter

Result confirms
the success or failure of the request. This request

has not been
implemented.

NGM_L2CAP_L2CA_GRP_MEMBERSHIP
Requests a report of the members of a group. The

input parameter
CID represents the group being queried. The output

parameter
Result confirms the success or failure of the opera

tion. If the
Result is successful, BD_ADDR_Lst is a list of the

Bluetooth
addresses of the N members of the group. This

request has not
been implemented.

NGM_L2CAP_L2CA_PINGInitiates an L2CA Echo Request message and the re

ception of the
corresponding L2CAP Echo Response message. The in

put parameters
are remote Bluetooth device BD_ADDR, Echo Data and

Length of the
echo data. The output parameters are Result, Echo

Data and
Length of the echo data.

NGM_L2CAP_L2CA_GET_INFO
Initiates an L2CA Information Request message and

the reception
of the corresponding L2CAP Info Response message.

The input
parameters are remote Bluetooth device BD_ADDR and

Information
Type. The output parameters are Result, Information

Data and
Size of the information data.

NGM_L2CAP_L2CA_ENABLE_CLTRequest to disable (enable) the reception of connec

tionless packets. The input parameter is the PSM value indicat

ing service
that should be blocked (unblocked) and Enable flag.

NETGRAPH CONTROL MESSAGES

This node type supports the generic control messages, plus

the following:

NGM_L2CAP_NODE_GET_FLAGS
Returns current state for the node.

NGM_L2CAP_NODE_GET_DEBUGReturns an integer containing the current debug lev

el for the
node.

NGM_L2CAP_NODE_SET_DEBUGThis command takes an integer argument and sets cur

rent debug
level for the node.

NGM_L2CAP_NODE_GET_CON_LIST
Returns list of active baseband connections (i.e.,

ACL links).

NGM_L2CAP_NODE_GET_CHAN_LIST
Returns list of active L2CAP channels.

NGM_L2CAP_NODE_GET_AUTO_DISCON_TIMO
Returns an integer containing the current value of

the auto disconnect timeout (in sec).

NGM_L2CAP_NODE_SET_AUTO_DISCON_TIMO
This command accepts an integer and sets the value

of the auto
disconnect timeout (in sec). The special value of 0

(zero) disables auto disconnect timeout.

SHUTDOWN

This node shuts down upon receipt of an NGM_SHUTDOWN control

message, or
when all hooks have been disconnected.

SEE ALSO

netgraph(4), l2control(8), l2ping(8), ngctl(8)

HISTORY

The l2cap node type was implemented in FreeBSD 5.0.

AUTHORS

Maksim Yevmenkin <m_evmenkin@yahoo.com>

BUGS

Most likely. Please report if found.

BSD July 4, 2002

BSD