mirror of
https://git.kernel.org/pub/scm/bluetooth/bluez.git
synced 2024-11-15 00:04:29 +08:00
doc: Add initial L2CAP(7) documentation
This adds initial documentation for L2CAP sockets.
This commit is contained in:
Luiz Augusto von Dentz
parent
7589303570
commit
f5e59893e6
@ -348,6 +348,7 @@ CLEANFILES += $(builtin_files)
|
||||
|
||||
if MANPAGES
|
||||
man_MANS += src/bluetoothd.8
|
||||
man_MANS += doc/l2cap.7
|
||||
man_MANS += doc/org.bluez.Adapter.5 doc/org.bluez.Device.5 \
|
||||
doc/org.bluez.DeviceSet.5 doc/org.bluez.AgentManager.5 \
|
||||
doc/org.bluez.Agent.5 doc/org.bluez.ProfileManager.5 \
|
||||
@ -380,6 +381,7 @@ man_MANS += doc/org.bluez.obex.Client.5 doc/org.bluez.obex.Session.5 \
|
||||
doc/org.bluez.obex.AgentManager.5 doc/org.bluez.obex.Agent.5
|
||||
endif
|
||||
manual_pages += src/bluetoothd.8
|
||||
manual_pages += doc/l2cap.7
|
||||
manual_pages += doc/org.bluez.Adapter.5 doc/org.bluez.Device.5 \
|
||||
doc/org.bluez.DeviceSet.5 doc/org.bluez.AgentManager.5 \
|
||||
doc/org.bluez.Agent.5 doc/org.bluez.ProfileManager.5 \
|
||||
@ -457,6 +459,8 @@ EXTRA_DIST += doc/mgmt-api.txt \
|
||||
doc/health-api.txt \
|
||||
doc/sap-api.txt
|
||||
|
||||
EXTRA_DIST += doc/l2cap.rst
|
||||
|
||||
EXTRA_DIST += doc/org.bluez.Adapter.rst doc/org.bluez.Device.rst \
|
||||
doc/org.bluez.DeviceSet.rst doc/org.bluez.AgentManager.rst \
|
||||
doc/org.bluez.Agent.rst doc/org.bluez.ProfileManager.rst \
|
||||
@ -758,6 +762,9 @@ endif
|
||||
%.5: %.rst Makefile
|
||||
$(RST2MAN_PROCESS)
|
||||
|
||||
%.7: %.rst Makefile
|
||||
$(RST2MAN_PROCESS)
|
||||
|
||||
%.8: %.rst Makefile
|
||||
$(RST2MAN_PROCESS)
|
||||
|
||||
|
||||
258
doc/l2cap.rst
Normal file
258
doc/l2cap.rst
Normal file
@ -0,0 +1,258 @@
|
||||
=====
|
||||
l2cap
|
||||
=====
|
||||
|
||||
--------------
|
||||
L2CAP protocol
|
||||
--------------
|
||||
|
||||
:Version: BlueZ
|
||||
:Copyright: Free use of this software is granted under ther terms of the GNU
|
||||
Lesser General Public Licenses (LGPL).
|
||||
:Date: May 2024
|
||||
:Manual section: 7
|
||||
:Manual group: Linux System Administration
|
||||
|
||||
SYNOPSIS
|
||||
========
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#include <sys/socket.h>
|
||||
#include <bluetooth/bluetooth.h>
|
||||
#include <bluetooth/l2cap.h>
|
||||
|
||||
l2cap_socket = socket(PF_BLUETOOTH, SOCK_SEQPACKET, BTPROTO_L2CAP);
|
||||
|
||||
DESCRIPTION
|
||||
===========
|
||||
|
||||
L2CAP is a protocol that provides an interface for higher-level protocols to
|
||||
send and receive data over a Bluetooth connection. L2CAP sits on top of the
|
||||
Bluetooth Host Controller Interface (HCI) and provides a set of channels that
|
||||
can be used by higher-level protocols to transmit data.
|
||||
|
||||
L2CAP provides a number of services to higher-level protocols, including
|
||||
segmentation and reassembly of large data packets and flow control to prevent
|
||||
overloading of the receiver. L2CAP also supports multiple channels per
|
||||
connection, allowing for concurrent data transmission using different protocols.
|
||||
|
||||
SOCKET ADDRESS
|
||||
==============
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
struct sockaddr_l2 {
|
||||
sa_family_t l2_family;
|
||||
unsigned short l2_psm;
|
||||
bdaddr_t l2_bdaddr;
|
||||
unsigned short l2_cid;
|
||||
uint8_t l2_bdaddr_type;
|
||||
};
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
struct sockaddr_l2 addr;
|
||||
|
||||
memset(&addr, 0, sizeof(addr));
|
||||
addr.l2_family = AF_BLUETOOTH;
|
||||
bacpy(&addr.l2_bdaddr, bdaddr);
|
||||
|
||||
if (cid)
|
||||
addr.l2_cid = htobs(cid);
|
||||
else
|
||||
addr.l2_psm = htobs(psm);
|
||||
|
||||
addr.l2_bdaddr_type = bdaddr_type;
|
||||
|
||||
SOCKET OPTIONS
|
||||
==============
|
||||
|
||||
The socket options listed below can be set by using **setsockopt(2)** and read
|
||||
with **getsockopt(2)** with the socket level set to SOL_BLUETOOTH.
|
||||
|
||||
BT_SECURITY (since Linux 2.6.30)
|
||||
--------------------------------
|
||||
|
||||
Channel security level, possible values:
|
||||
|
||||
.. csv-table::
|
||||
:header: "Value", "Security Level", "Link Key Type", "Encryption"
|
||||
:widths: auto
|
||||
|
||||
**BT_SECURITY_SDP**, 0 (SDP Only), None, Not required
|
||||
**BT_SECURITY_LOW**, 1 (Low), Unauthenticated, Not required
|
||||
**BT_SECURITY_MEDIUM**, 2 (Medium - default), Unauthenticated, Desired
|
||||
**BT_SECURITY_HIGH**, 3 (High), Authenticated, Required
|
||||
**BT_SECURITY_FIPS** (since Linux 3.15), 4 (Secure Only), Authenticated (P-256 based Secure Simple Pairing and Secure Authentication), Required
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
int level = BT_SECURITY_HIGH;
|
||||
int err = setsockopt(l2cap_socket, SOL_BLUETOOTH, BT_SECURITY, &level,
|
||||
sizeof(level));
|
||||
if (err == -1) {
|
||||
perror("setsockopt");
|
||||
return 1;
|
||||
}
|
||||
|
||||
BT_DEFER_SETUP (since Linux 2.6.30)
|
||||
-----------------------------------
|
||||
|
||||
Channel defer connection setup, this control if the connection procedure
|
||||
needs to be authorized by userspace before responding which allows
|
||||
authorization at profile level, possible values:
|
||||
|
||||
.. csv-table::
|
||||
:header: "Value", "Description", "Authorization"
|
||||
:widths: auto
|
||||
|
||||
**0**, Disable (default), Not required
|
||||
**1**, Enable, Required
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
int defer_setup = 1;
|
||||
int err = setsockopt(l2cap_socket, SOL_BLUETOOTH, BT_DEFER_SETUP,
|
||||
&defer_setup, sizeof(defer_setup));
|
||||
if (err == -1) {
|
||||
perror("setsockopt");
|
||||
return err;
|
||||
}
|
||||
|
||||
err = listen(l2cap_socket, 5);
|
||||
if (err) {
|
||||
perror("listen");
|
||||
return err;
|
||||
}
|
||||
|
||||
struct sockaddr_l2 remote_addr = {0};
|
||||
socklen_t addr_len = sizeof(remote_addr);
|
||||
int new_socket = accept(l2cap_socket, (struct sockaddr*)&remote_addr,
|
||||
&addr_len);
|
||||
if (new_socket < 0) {
|
||||
perror("accept");
|
||||
return new_socket;
|
||||
}
|
||||
|
||||
/* To complete the connection setup of new_socket read 1 byte */
|
||||
char c;
|
||||
struct pollfd pfd;
|
||||
|
||||
memset(&pfd, 0, sizeof(pfd));
|
||||
pfd.fd = new_socket;
|
||||
pfd.events = POLLOUT;
|
||||
|
||||
err = poll(&pfd, 1, 0);
|
||||
if (err) {
|
||||
perror("poll");
|
||||
return err;
|
||||
}
|
||||
|
||||
if (!(pfd.revents & POLLOUT)) {
|
||||
err = read(sk, &c, 1);
|
||||
if (err < 0) {
|
||||
perror("read");
|
||||
return err;
|
||||
}
|
||||
}
|
||||
|
||||
BT_FLUSHABLE (since Linux 2.6.39)
|
||||
---------------------------------
|
||||
|
||||
Channel flushable flag, this control if the channel data can be flushed or
|
||||
not, possible values:
|
||||
|
||||
.. csv-table::
|
||||
:header: "Define", "Value", "Description"
|
||||
:widths: auto
|
||||
|
||||
**BT_FLUSHABLE_OFF**, 0x00 (default), Do not flush data
|
||||
**BT_FLUSHABLE_ON**, 0x01, Flush data
|
||||
|
||||
BT_POWER (since Linux 3.1)
|
||||
--------------------------
|
||||
|
||||
Channel power policy, this control if the channel shall force exit of sniff
|
||||
mode or not, possible values:
|
||||
|
||||
.. csv-table::
|
||||
:header: "Define", "Value", "Description"
|
||||
:widths: auto
|
||||
|
||||
**BT_POWER_FORCE_ACTIVE_OFF**, 0x00 (default), Don't force exit of sniff mode
|
||||
**BT_POWER_FORCE_ACTIVE_ON**, 0x01, Force exit of sniff mode
|
||||
|
||||
BT_CHANNEL_POLICY (since Linux 3.10)
|
||||
------------------------------------
|
||||
|
||||
High-speed (AMP) channel policy, possible values:
|
||||
|
||||
.. csv-table::
|
||||
:header: "Define", "Value", "Description"
|
||||
:widths: auto
|
||||
|
||||
**BT_CHANNEL_POLICY_BREDR_ONLY**, 0 (default), BR/EDR only
|
||||
**BT_CHANNEL_POLICY_BREDR_PREFERRED**, 1, BR/EDR Preferred
|
||||
**BT_CHANNEL_POLICY_BREDR_PREFERRED**, 2, AMP Preferred
|
||||
|
||||
BT_PHY (since Linux 5.10)
|
||||
-------------------------
|
||||
|
||||
Channel supported PHY(s), possible values:
|
||||
|
||||
.. csv-table::
|
||||
:header: "Define", "Value", "Description"
|
||||
:widths: auto
|
||||
|
||||
**BT_PHY_BR_1M_1SLOT**, BIT 0, BR 1Mbps 1SLOT
|
||||
**BT_PHY_BR_1M_3SLOT**, BIT 1, BR 1Mbps 3SLOT
|
||||
**BT_PHY_BR_1M_5SLOT**, BIT 2, BR 1Mbps 5SLOT
|
||||
**BT_PHY_BR_2M_1SLOT**, BIT 3, EDR 2Mbps 1SLOT
|
||||
**BT_PHY_BR_2M_3SLOT**, BIT 4, EDR 2Mbps 3SLOT
|
||||
**BT_PHY_BR_2M_5SLOT**, BIT 5, EDR 2Mbps 5SLOT
|
||||
**BT_PHY_BR_3M_1SLOT**, BIT 6, EDR 3Mbps 1SLOT
|
||||
**BT_PHY_BR_3M_3SLOT**, BIT 7, EDR 3Mbps 3SLOT
|
||||
**BT_PHY_BR_3M_5SLOT**, BIT 8, EDR 3Mbps 5SLOT
|
||||
**BT_PHY_LE_1M_TX**, BIT 9, LE 1Mbps TX
|
||||
**BT_PHY_LE_1M_RX**, BIT 10, LE 1Mbps RX
|
||||
**BT_PHY_LE_2M_TX**, BIT 11, LE 2Mbps TX
|
||||
**BT_PHY_LE_2M_RX**, BIT 12, LE 2Mbps RX
|
||||
**BT_PHY_LE_CODED_TX**, BIT 13, LE Coded TX
|
||||
**BT_PHY_LE_CODED_RX**, BIT 14, LE Coded RX
|
||||
|
||||
BT_MODE (since Linux 5.10)
|
||||
--------------------------
|
||||
|
||||
Channel Mode, possible values:
|
||||
|
||||
.. csv-table::
|
||||
:header: "Define", "Value", "Description", "Link"
|
||||
:widths: auto
|
||||
|
||||
**BT_MODE_BASIC**, 0x00 (default), Basic mode, Any
|
||||
**BT_MODE_ERTM**, 0x01, Enhanced Retransmission mode, BR/EDR
|
||||
**BT_MODE_STREAM**, 0x02, Stream mode, BR/EDR
|
||||
**BT_MODE_LE_FLOWCTL**, 0x03, Credit based flow control mode, LE
|
||||
**BT_MODE_EXT_FLOWCTL**, 0x04, Extended Credit based flow control mode, Any
|
||||
|
||||
RESOURCES
|
||||
=========
|
||||
|
||||
http://www.bluez.org
|
||||
|
||||
REPORTING BUGS
|
||||
==============
|
||||
|
||||
linux-bluetooth@vger.kernel.org
|
||||
|
||||
SEE ALSO
|
||||
========
|
||||
|
||||
socket(7), l2test(1)
|
||||
Loading…
Reference in New Issue
Block a user