man/man4/ng_l2cap.4

.\" $MidnightBSD$
.\" Copyright (c) 2001-2002 Maksim Yevmenkin <m_evmenkin@yahoo.com>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $Id: ng_l2cap.4,v 1.4 2003/09/14 23:37:52 max Exp $
.\" $FreeBSD: stable/10/share/man/man4/ng_l2cap.4 242997 2012-11-13 20:41:36Z joel $
.\"
.Dd July 4, 2002
.Dt NG_L2CAP 4
.Os
.Sh NAME
.Nm ng_l2cap
.Nd Netgraph node type that implements Bluetooth Logical Link Control and
Adaptation Protocol (L2CAP)
.Sh SYNOPSIS
.In sys/types.h
.In netgraph/bluetooth/include/ng_hci.h
.In netgraph/bluetooth/include/ng_l2cap.h
.Sh DESCRIPTION
The
.Nm 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.
.Pp
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.
.Ss L2CAP Assumptions
.Bl -enum -offset indent
.It
The ACL link between two units is set up.
The Baseband provides 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.
.It
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 duplex
channels.
.It
L2CAP provides a reliable channel using the mechanisms available 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 occurs.
As acknowledgements may be lost, timeouts may
occur even after the data has been successfully sent.
.El
.Sh L2CAP GENERAL OPERATION
The Logical Link Control and Adaptation Protocol (L2CAP) is based around the
concept of
.Dq 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 protocols.
Each L2CAP packet received on a channel is directed to
the appropriate higher level protocol.
.Pp
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 remote device.
.Pp
CID assignment is relative to a particular device and a device 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.
.Ss Channel Operational States
.Bl -tag -width foo
.It Dv 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
.Dv NG_L2CAP_CLOSED
state.
.It Dv 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.
.It Dv 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.
.It Dv 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 parameters are being renegotiated.
Prior to entering the
.Dv NG_L2CAP_CONFIG
state, all outgoing data traffic is suspended since
the traffic parameters of the data traffic are to be renegotiated.
Incoming
data traffic is accepted until the remote channel endpoint has entered
the
.Dv NG_L2CAP_CONFIG
state.
In the
.Dv 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 messages will be sent to avoid any MTU limitations and negotiate
incrementally.
Moving from the
.Dv NG_L2CAP_CONFIG
state to the
.Dv 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 request and it has positively responded to
the final request from the remote device.
.It Dv NG_L2CAP_OPEN
In this state, the connection has been established and configured, and data
flow may proceed.
.It Dv 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.
.It Dv 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
corresponding response from the upper layer before responding to the remote
endpoint.
.El
.Ss Protocol Multiplexing
L2CAP supports protocol multiplexing because the Baseband Protocol does not
support any
.Dq 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, RFCOMM and Telephony Control.
.Ss Segmentation and Reassembly
The data packets defined by the Baseband Protocol are limited in size.
Large
L2CAP packets must be segmented into multiple smaller Baseband packets prior
to their transmission over the air.
Similarly, multiple received Baseband
packets may be reassembled into a single larger L2CAP packet.
.Ss Quality of Service
The L2CAP connection establishment process allows the exchange of information
regarding the quality of service (QoS) expected between two Bluetooth units.
.Ss 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.
.Pp
The following features are outside the scope of L2CAP responsibilities:
.Bl -dash -offset indent
.It
L2CAP does not transport audio designated for SCO links.
.It
L2CAP does not enforce a reliable channel or ensure data integrity,
that is, L2CAP performs no retransmissions or checksum calculations.
.It
L2CAP does not support a reliable multicast channel.
.It
L2CAP does not support the concept of a global group name.
.El
.Sh HOOKS
This node type supports the following hooks:
.Bl -tag -width ".Va hci"
.It Va hci
Bluetooth Host Controller Interface downstream hook.
.It Va l2c
Upper layer protocol upstream hook.
Usually the Bluetooth L2CAP socket layer is connected to the hook.
.It Va ctl
Control hook.
Usually the Bluetooth raw L2CAP sockets layer is connected to the hook.
.El
.Sh INTERFACE TO THE UPPER LAYER PROTOCOLS (L2CA CONTROL MESSAGES)
Bluetooth specification says that L2CA request must block until response
is ready.
L2CAP node uses
.Va token
field from Netgraph message header to match L2CA request and response.
The upper layer protocol must populate
.Va 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
.Va token
and
.Dv NFG_RESP
flag and send message to the upper layer.
Note that L2CA indication messages
will not populate
.Va token
and will not set
.Dv NGF_RESP
flag.
There is no reason for this, because they are just notifications and do
not require acknowledgment.
.Bl -tag -width foo
.It Dv 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
indicates a pending notification, the Status value may contain more information
of what processing is delaying the establishment of the connection.
.It Dv 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 Identifier contained in the request, and the PSM value the
request is targeting.
.It Dv NGM_L2CAP_L2CA_CON_RSP
Issues a response to a connection request event indication.
Input parameters
are the remote device's 48-bit address, 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.
.It Dv NGM_L2CAP_L2CA_CFG
Requests the initial configuration (or reconfiguration) 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.
.It Dv NGM_L2CAP_L2CA_CFG_IND
This message includes the parameters indicating the local CID of the channel
the request has been sent to, the outgoing MTU size (maximum packet that can
be sent across the channel) and the flowspec describing the characteristics of
the incoming data.
All other channel parameters are set to their default values
if not provided by the remote device.
.It Dv NGM_L2CAP_L2CA_CFG_RSP
Issues a response to a configuration request event indication.
Input parameters
include the local CID of the endpoint 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.
.It Dv 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.
.It Dv 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 Disconnect 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.
.It Dv NGM_L2CAP_L2CA_DISCON_IND
This message includes the parameter indicating the local CID the request has
been sent to.
.It Dv 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.
.Bd -literal -offset indent
/* L2CA data packet header */
typedef struct {
        uint32_t token;  /* token to use in L2CAP_L2CA_WRITE */
        uint16_t length; /* length of the data */
        uint16_t lcid;   /* local channel ID */
} __attribute__ ((packed)) ng_l2cap_l2ca_hdr_t;
.Ed
.Pp
The output parameters are Result and Length of data written.
.It Dv NGM_L2CAP_L2CA_GRP_CREATE
Requests the creation of a CID to represent a logical 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 readable.
.Bf -emphasis
This request has not been implemented.
.Ef
.It Dv NGM_L2CAP_L2CA_GRP_CLOSE
The use of this message closes down a Group.
.Bf -emphasis
This request has not been implemented.
.Ef
.It Dv 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.
.Bf -emphasis
This request has not been implemented.
.Ef
.It Dv 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.
.Bf -emphasis
This request has not been implemented.
.Ef
.It Dv 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 operation.
If the Result is successful, BD_ADDR_Lst is a list
of the Bluetooth addresses of the N members of the group.
.Bf -emphasis
This request has not been implemented.
.Ef
.It Dv NGM_L2CAP_L2CA_PING
Initiates an L2CA Echo Request message and the reception of the corresponding
L2CAP Echo Response message.
The input 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.
.It Dv 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.
.It Dv NGM_L2CAP_L2CA_ENABLE_CLT
Request to disable (enable) the reception of connectionless packets.
The input
parameter is the PSM value indicating service that should be blocked
(unblocked) and Enable flag.
.El
.Sh NETGRAPH CONTROL MESSAGES
This node type supports the generic control messages, plus the following:
.Bl -tag -width foo
.It Dv NGM_L2CAP_NODE_GET_FLAGS
Returns current state for the node.
.It Dv NGM_L2CAP_NODE_GET_DEBUG
Returns an integer containing the current debug level for the node.
.It Dv NGM_L2CAP_NODE_SET_DEBUG
This command takes an integer argument and sets current debug level
for the node.
.It Dv NGM_L2CAP_NODE_GET_CON_LIST
Returns list of active baseband connections (i.e., ACL links).
.It Dv NGM_L2CAP_NODE_GET_CHAN_LIST
Returns list of active L2CAP channels.
.It Dv NGM_L2CAP_NODE_GET_AUTO_DISCON_TIMO
Returns an integer containing the current value of the auto disconnect
timeout (in sec).
.It Dv 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.
.El
.Sh SHUTDOWN
This node shuts down upon receipt of an
.Dv NGM_SHUTDOWN
control message, or
when all hooks have been disconnected.
.Sh SEE ALSO
.Xr netgraph 4 ,
.Xr l2control 8 ,
.Xr l2ping 8 ,
.Xr ngctl 8
.Sh HISTORY
The
.Nm l2cap
node type was implemented in
.Fx 5.0 .
.Sh AUTHORS
.An Maksim Yevmenkin Aq m_evmenkin@yahoo.com
.Sh BUGS
Most likely.
Please report if found.
Revision:	11734
Committed:	Mon Jul 9 23:26:56 2018 UTC (5 years, 9 months ago) by laffer1
File size:	17177 byte(s)
Log Message:	update more
#	Content
1	.\" $MidnightBSD$
2	.\" Copyright (c) 2001-2002 Maksim Yevmenkin <m_evmenkin@yahoo.com>
3	.\" All rights reserved.
4	.\"
5	.\" Redistribution and use in source and binary forms, with or without
6	.\" modification, are permitted provided that the following conditions
7	.\" are met:
8	.\" 1. Redistributions of source code must retain the above copyright
9	.\" notice, this list of conditions and the following disclaimer.
10	.\" 2. Redistributions in binary form must reproduce the above copyright
11	.\" notice, this list of conditions and the following disclaimer in the
12	.\" documentation and/or other materials provided with the distribution.
13	.\"
14	.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24	.\" SUCH DAMAGE.
25	.\"
26	.\" $Id: ng_l2cap.4,v 1.4 2003/09/14 23:37:52 max Exp $
27	.\" $FreeBSD: stable/10/share/man/man4/ng_l2cap.4 242997 2012-11-13 20:41:36Z joel $
28	.\"
29	.Dd July 4, 2002
30	.Dt NG_L2CAP 4
31	.Os
32	.Sh NAME
33	.Nm ng_l2cap
34	.Nd Netgraph node type that implements Bluetooth Logical Link Control and
35	Adaptation Protocol (L2CAP)
36	.Sh SYNOPSIS
37	.In sys/types.h
38	.In netgraph/bluetooth/include/ng_hci.h
39	.In netgraph/bluetooth/include/ng_l2cap.h
40	.Sh DESCRIPTION
41	The
42	.Nm l2cap
43	node type is a Netgraph node type that implements Bluetooth Logical Link
44	Control and Adaptation Protocol as per chapter D of the Bluetooth Specification
45	Book v1.1.
46	.Pp
47	L2CAP provides connection-oriented and connectionless data services to upper
48	layer protocols with protocol multiplexing capability, segmentation and
49	reassembly operation, and group abstractions.
50	L2CAP permits higher level
51	protocols and applications to transmit and receive L2CAP data packets up to
52	64 kilobytes in length.
53	.Ss L2CAP Assumptions
54	.Bl -enum -offset indent
55	.It
56	The ACL link between two units is set up.
57	The Baseband provides orderly
58	delivery of data packets, although there might be individual packet corruption
59	and duplicates.
60	No more than one ACL link exists between any two devices.
61	.It
62	The Baseband always provides the impression of full-duplex communication
63	channels.
64	This does not imply that all L2CAP communications are bi-directional.
65	Multicasts and unidirectional traffic (e.g., video) do not require duplex
66	channels.
67	.It
68	L2CAP provides a reliable channel using the mechanisms available at the
69	Baseband layer.
70	The Baseband always performs data integrity checks when
71	requested and resends data until it has been successfully acknowledged or
72	a timeout occurs.
73	As acknowledgements may be lost, timeouts may
74	occur even after the data has been successfully sent.
75	.El
76	.Sh L2CAP GENERAL OPERATION
77	The Logical Link Control and Adaptation Protocol (L2CAP) is based around the
78	concept of
79	.Dq channels .
80	Each channel is bound to a single protocol in a many-to-one fashion.
81	Multiple
82	channels can be bound to the same protocol, but a channel cannot be bound to
83	multiple protocols.
84	Each L2CAP packet received on a channel is directed to
85	the appropriate higher level protocol.
86	.Pp
87	Each one of the end-points of an L2CAP channel is referred to by a channel
88	identifier.
89	Channel identifiers (CIDs) are local names representing a logical
90	channel end-point on the device.
91	Identifiers from 0x0001 to 0x003F are reserved
92	for specific L2CAP functions.
93	The null identifier (0x0000) is defined as an
94	illegal identifier and must never be used as a destination end-point.
95	All L2CAP signalling commands are sent to CID 0x0001.
96	CID 0x0002 is reserved for group-oriented channel.
97	The same CID must not be reused as a local L2CAP
98	channel endpoint for multiple simultaneous L2CAP channels between a local
99	device and some remote device.
100	.Pp
101	CID assignment is relative to a particular device and a device can assign CIDs
102	independently from other devices.
103	Thus, even if the same CID value has been
104	assigned to (remote) channel endpoints by several remote devices connected
105	to a single local device, the local device can still uniquely associate each
106	remote CID with a different device.
107	.Ss Channel Operational States
108	.Bl -tag -width foo
109	.It Dv NG_L2CAP_CLOSED
110	In this state, there is no channel associated with this CID.
111	This is the only
112	state when a link level connection (Baseband) may not exist.
113	Link disconnection
114	forces all other states into the
115	.Dv NG_L2CAP_CLOSED
116	state.
117	.It Dv NG_L2CAP_W4_L2CAP_CON_RSP
118	In this state, the CID represents a local end-point and an L2CAP Connect
119	Request message has been sent referencing this endpoint and it is now waiting
120	for the corresponding L2CAP Connect Response message.
121	.It Dv NG_L2CAP_W4_L2CA_CON_RSP
122	In this state, the remote end-point exists and an L2CAP Connect Request has
123	been received by the local L2CAP entity.
124	An L2CA Connect Indication has been
125	sent to the upper layer and the part of the local L2CAP entity processing the
126	received L2CAP Connect Request waits for the corresponding response.
127	The response may require a security check to be performed.
128	.It Dv NG_L2CAP_CONFIG
129	In this state, the connection has been established but both sides are still
130	negotiating the channel parameters.
131	The Configuration state may also be
132	entered when the channel parameters are being renegotiated.
133	Prior to entering the
134	.Dv NG_L2CAP_CONFIG
135	state, all outgoing data traffic is suspended since
136	the traffic parameters of the data traffic are to be renegotiated.
137	Incoming
138	data traffic is accepted until the remote channel endpoint has entered
139	the
140	.Dv NG_L2CAP_CONFIG
141	state.
142	In the
143	.Dv NG_L2CAP_CONFIG
144	state, both sides will issue
145	L2CAP Configuration Request messages if only defaults are being used, a null
146	message will be sent.
147	If a large amount of parameters need to be negotiated,
148	multiple messages will be sent to avoid any MTU limitations and negotiate
149	incrementally.
150	Moving from the
151	.Dv NG_L2CAP_CONFIG
152	state to the
153	.Dv NG_L2CAP_OPEN
154	state requires both sides to be ready.
155	An L2CAP entity is ready when it has received
156	a positive response to its final request and it has positively responded to
157	the final request from the remote device.
158	.It Dv NG_L2CAP_OPEN
159	In this state, the connection has been established and configured, and data
160	flow may proceed.
161	.It Dv NG_L2CAP_W4_L2CAP_DISCON_RSP
162	In this state, the connection is shutting down and an L2CAP Disconnect Request
163	message has been sent.
164	This state is now waiting for the corresponding response.
165	.It Dv NG_L2CAP_W4_L2CA_DISCON_RSP
166	In this state, the connection on the remote endpoint is shutting down and an
167	L2CAP Disconnect Request message has been received.
168	An L2CA Disconnect
169	Indication has been sent to the upper layer to notify the owner of the CID
170	that the remote endpoint is being closed.
171	This state is now waiting for the
172	corresponding response from the upper layer before responding to the remote
173	endpoint.
174	.El
175	.Ss Protocol Multiplexing
176	L2CAP supports protocol multiplexing because the Baseband Protocol does not
177	support any
178	.Dq type
179	field identifying the higher layer protocol being multiplexed above it.
180	L2CAP is able to distinguish between upper layer protocols such as the Service
181	Discovery Protocol, RFCOMM and Telephony Control.
182	.Ss Segmentation and Reassembly
183	The data packets defined by the Baseband Protocol are limited in size.
184	Large
185	L2CAP packets must be segmented into multiple smaller Baseband packets prior
186	to their transmission over the air.
187	Similarly, multiple received Baseband
188	packets may be reassembled into a single larger L2CAP packet.
189	.Ss Quality of Service
190	The L2CAP connection establishment process allows the exchange of information
191	regarding the quality of service (QoS) expected between two Bluetooth units.
192	.Ss Groups
193	The Baseband Protocol supports the concept of a piconet, a group of devices
194	synchronously hopping together using the same clock.
195	The L2CAP group
196	abstraction permits implementations to efficiently map protocol groups on to
197	piconets.
198	.Pp
199	The following features are outside the scope of L2CAP responsibilities:
200	.Bl -dash -offset indent
201	.It
202	L2CAP does not transport audio designated for SCO links.
203	.It
204	L2CAP does not enforce a reliable channel or ensure data integrity,
205	that is, L2CAP performs no retransmissions or checksum calculations.
206	.It
207	L2CAP does not support a reliable multicast channel.
208	.It
209	L2CAP does not support the concept of a global group name.
210	.El
211	.Sh HOOKS
212	This node type supports the following hooks:
213	.Bl -tag -width ".Va hci"
214	.It Va hci
215	Bluetooth Host Controller Interface downstream hook.
216	.It Va l2c
217	Upper layer protocol upstream hook.
218	Usually the Bluetooth L2CAP socket layer is connected to the hook.
219	.It Va 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 foo
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	uint32_t token; /* token to use in L2CAP_L2CA_WRITE */
315	uint16_t length; /* length of the data */
316	uint16_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 foo
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.