From: Luiz Augusto von Dentz <luiz.von.dentz@xxxxxxxxx>
This adds initial documentation for L2CAP sockets.
---
Makefile.am | 7 ++
doc/l2cap.rst | 222 ++++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 229 insertions(+)
create mode 100644 doc/l2cap.rst
diff --git a/Makefile.am b/Makefile.am
index 05d02932f205..8aedbb20d0d8 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -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)
diff --git a/doc/l2cap.rst b/doc/l2cap.rst
new file mode 100644
index 000000000000..b358515e4e75
--- /dev/null
+++ b/doc/l2cap.rst
@@ -0,0 +1,222 @@
+=====
+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: July 2023
+: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(AF_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 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"
+
+ **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::
+ :align: left
+ :header: "Value", "Description"
+
+ **0**, Disable (userspace authorization not required)
+ **1**, Enable (userspace authorization 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::
+ :align: left
+ :header: "Define", "Value", "Description"
+
+ **BT_FLUSHABLE_OFF**, 0x00, 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::
+ :align: left
+ :header: "Define", "Value", "Description"
+
+ **BT_POWER_FORCE_ACTIVE_OFF**, 0x00, 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::
+ :align: left
+ :header: "Define", "Value", "Description"
+
+ **BT_CHANNEL_POLICY_BREDR_ONLY**, 0, BR/EDR only - default
+ **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::
+ :align: left
+ :header: "Define", "Value", "Description"
+
+ **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::
+ :align: left
+ :header: "Define", "Value", "Description"
+
+ **BT_MODE_BASIC**, 0x00, Basic mode - default
+ **BT_MODE_ERTM**, 0x01, Enhanced Retransmission mode - BR/EDR only
+ **BT_MODE_STREAM**, 0x02, Stream mode - BR/EDR only
+ **BT_MODE_LE_FLOWCTL**, 0x03, Credit based flow control mode - LE only
+ **BT_MODE_EXT_FLOWCTL**, 0x04, Extended Credit based flow control mode
+
+RESOURCES
+=========
+
+http://www.bluez.org
+
+REPORTING BUGS
+==============
+
+linux-bluetooth@xxxxxxxxxxxxxxx
--
2.45.0
