From: Luiz Augusto von Dentz <[email protected]>
This adds initial documentation for L2CAP sockets.
---
Makefile.am | 7 ++
doc/l2cap.rst | 258 ++++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 265 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..2486f7c6f55a
--- /dev/null
+++ b/doc/l2cap.rst
@@ -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
+==============
+
[email protected]
+
+SEE ALSO
+========
+
+socket(7), l2test(1)
--
2.45.1
From: Luiz Augusto von Dentz <[email protected]>
This adds initial documentation for RFCOMM sockets.
---
Makefile.am | 4 +-
doc/rfcomm.rst | 225 +++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 227 insertions(+), 2 deletions(-)
create mode 100644 doc/rfcomm.rst
diff --git a/Makefile.am b/Makefile.am
index 8aedbb20d0d8..8f5d2fb553b4 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -348,7 +348,7 @@ CLEANFILES += $(builtin_files)
if MANPAGES
man_MANS += src/bluetoothd.8
-man_MANS += doc/l2cap.7
+man_MANS += doc/l2cap.7 doc/rfcomm.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 \
@@ -381,7 +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/l2cap.7 doc/rfcomm.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 \
diff --git a/doc/rfcomm.rst b/doc/rfcomm.rst
new file mode 100644
index 000000000000..4e43094b797d
--- /dev/null
+++ b/doc/rfcomm.rst
@@ -0,0 +1,225 @@
+======
+rfcomm
+======
+
+---------------
+RFCOMM 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/rfcomm.h>
+
+ rfcomm_socket = socket(PF_BLUETOOTH, SOCK_STREAM, BTPROTO_RFCOMM);
+
+DESCRIPTION
+===========
+
+The RFCOMM protocol provides emulation of serial ports over the L2CAP(7)
+protocol. The protocol is based on the ETSI standard TS 07.10.
+
+RFCOMM is a simple transport protocol, with additional provisions for emulating
+the 9 circuits of RS-232 (EIATIA-232-E) serial ports.
+
+SOCKET ADDRESS
+==============
+
+.. code-block:: c
+
+ struct sockaddr_rc {
+ sa_family_t rc_family;
+ unsigned short rc_bdaddr;
+ unsigned char rc_channel;
+ };
+
+Example:
+
+.. code-block:: c
+
+ struct sockaddr_rc addr;
+
+ memset(&addr, 0, sizeof(addr));
+ addr.rc_family = AF_BLUETOOTH;
+ bacpy(&addr.rc_bdaddr, bdaddr);
+ addr.rc_channel = channel;
+
+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(rfcomm_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(rfcomm_socket, SOL_BLUETOOTH, BT_DEFER_SETUP,
+ &defer_setup, sizeof(defer_setup));
+ if (err == -1) {
+ perror("setsockopt");
+ return err;
+ }
+
+ err = listen(rfcomm_socket, 5);
+ if (err) {
+ perror("listen");
+ return err;
+ }
+
+ struct sockaddr_rc remote_addr = {0};
+ socklen_t addr_len = sizeof(remote_addr);
+ int new_socket = accept(rfcomm_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
+
+RESOURCES
+=========
+
+http://www.bluez.org
+
+REPORTING BUGS
+==============
+
[email protected]
+
+SEE ALSO
+========
+
+socket(7), rctest(1)
--
2.45.1
This is automated email and please do not reply to this email!
Dear submitter,
Thank you for submitting the patches to the linux bluetooth mailing list.
This is a CI test results with your patch series:
PW Link:https://patchwork.kernel.org/project/bluetooth/list/?series=855726
---Test result---
Test Summary:
CheckPatch PASS 0.91 seconds
GitLint PASS 0.66 seconds
BuildEll PASS 24.43 seconds
BluezMake PASS 1632.38 seconds
MakeCheck PASS 13.14 seconds
MakeDistcheck PASS 175.13 seconds
CheckValgrind PASS 247.40 seconds
CheckSmatch PASS 350.48 seconds
bluezmakeextell PASS 118.44 seconds
IncrementalBuild PASS 2937.96 seconds
ScanBuild PASS 982.44 seconds
---
Regards,
Linux Bluetooth
Hello:
This series was applied to bluetooth/bluez.git (master)
by Luiz Augusto von Dentz <[email protected]>:
On Fri, 24 May 2024 10:47:08 -0400 you wrote:
> From: Luiz Augusto von Dentz <[email protected]>
>
> This adds initial documentation for L2CAP sockets.
> ---
> Makefile.am | 7 ++
> doc/l2cap.rst | 258 ++++++++++++++++++++++++++++++++++++++++++++++++++
> 2 files changed, 265 insertions(+)
> create mode 100644 doc/l2cap.rst
Here is the summary with links:
- [BlueZ,v3,1/2] doc: Add initial L2CAP(7) documentation
https://git.kernel.org/pub/scm/bluetooth/bluez.git/?id=f5e59893e634
- [BlueZ,v3,2/2] doc: Add initial RFCOMM(7) documentation
https://git.kernel.org/pub/scm/bluetooth/bluez.git/?id=098ff00dea08
You are awesome, thank you!
--
Deet-doot-dot, I am a bot.
https://korg.docs.kernel.org/patchwork/pwbot.html