* [PATCH BlueZ v1] doc: Add initial ISO(7) documentation
@ 2025-07-15 18:07 Luiz Augusto von Dentz
2025-07-15 18:17 ` Luiz Augusto von Dentz
2025-07-15 19:48 ` [BlueZ,v1] " bluez.test.bot
0 siblings, 2 replies; 5+ messages in thread
From: Luiz Augusto von Dentz @ 2025-07-15 18:07 UTC (permalink / raw)
To: linux-bluetooth
From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
This adds initial documentation for ISO sockets.
---
Makefile.am | 8 +-
doc/iso.rst | 436 ++++++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 441 insertions(+), 3 deletions(-)
create mode 100644 doc/iso.rst
diff --git a/Makefile.am b/Makefile.am
index c4b88d83c962..8319373409cd 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -356,7 +356,7 @@ CLEANFILES += $(builtin_files)
if MANPAGES
man_MANS += src/bluetoothd.8
-man_MANS += doc/hci.7 doc/mgmt.7 doc/l2cap.7 doc/rfcomm.7 doc/sco.7
+man_MANS += doc/hci.7 doc/mgmt.7 doc/l2cap.7 doc/rfcomm.7 doc/sco.7 doc/iso.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 \
@@ -390,7 +390,8 @@ man_MANS += doc/org.bluez.obex.Client.5 doc/org.bluez.obex.Session.5 \
doc/org.bluez.obex.Image.5
endif
manual_pages += src/bluetoothd.8
-manual_pages += doc/hci.7 doc/mgmt.7 doc/l2cap.7 doc/rfcomm.7 doc/sco.7
+manual_pages += doc/hci.7 doc/mgmt.7 doc/l2cap.7 doc/rfcomm.7 doc/sco.7 \
+ doc/iso.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 \
@@ -467,7 +468,8 @@ EXTRA_DIST += doc/assigned-numbers.txt doc/supported-features.txt \
EXTRA_DIST += doc/health-api.txt \
doc/sap-api.txt
-EXTRA_DIST += doc/hci.rst doc/mgmt.rst doc/l2cap.rst doc/rfcomm.rst doc/sco.rst
+EXTRA_DIST += doc/hci.rst doc/mgmt.rst doc/l2cap.rst doc/rfcomm.rst \
+ doc/sco.rst doc/iso.rst
EXTRA_DIST += doc/org.bluez.Adapter.rst doc/org.bluez.Device.rst \
doc/org.bluez.DeviceSet.rst doc/org.bluez.AgentManager.rst \
diff --git a/doc/iso.rst b/doc/iso.rst
new file mode 100644
index 000000000000..d08b60d20865
--- /dev/null
+++ b/doc/iso.rst
@@ -0,0 +1,436 @@
+===
+iso
+===
+-------------
+ISO transport
+-------------
+
+:Version: BlueZ
+:Copyright: Free use of this software is granted under the terms of the GNU
+ Lesser General Public Licenses (LGPL).
+:Date: July 2025
+:Manual section: 7
+:Manual group: Linux System Administration
+
+SYNOPSIS (since Linux 6.0 [experimental])
+=========================================
+
+.. code-block::
+
+ #include <sys/socket.h>
+ #include <bluetooth/bluetooth.h>
+ #include <bluetooth/iso.h>
+
+ iso_socket = socket(PF_BLUETOOTH, SOCK_SEQPACKET, BTPROTO_ISO);
+
+DESCRIPTION
+===========
+
+Bluetooth Isochronous Channels is a feature introduced in Bluetooth 5.2 that
+allow for the transmission of multiple, synchronized audio streams between
+devices.
+
+For unicast/multi-stream audio, connected isochronous group (CIG), and
+connected isochronous stream (CIS) are used. A CIG is created by the central and
+it can include one or more CISs. A CIS is a point-to-point data transportation
+stream between a central and a certain peripheral, and is a bidirectional
+communication protocol with acknowledgment.
+
+For broadcast audio, broadcast isochronous group (BIG) and broadcast isochronous
+stream (BIS) are used. There are two types of devices: isochronous broadcaster
+and synchronized receiver. A BIG is created by an isochronous broadcaster, and
+it can include one or more BISs. A BIS is a one-to-many data transportation
+stream.
+
+SOCKET ADDRESS
+==============
+
+.. code-block::
+
+ struct sockaddr_iso_bc {
+ bdaddr_t bc_bdaddr;
+ uint8_t bc_bdaddr_type;
+ uint8_t bc_sid;
+ uint8_t bc_num_bis;
+ uint8_t bc_bis[ISO_MAX_NUM_BIS];
+ };
+
+ struct sockaddr_iso {
+ sa_family_t iso_family;
+ bdaddr_t iso_bdaddr;
+ uint8_t iso_bdaddr_type;
+ struct sockaddr_iso_bc iso_bc[];
+ };
+
+Unicast example:
+
+.. code-block::
+
+ struct sockaddr_iso addr;
+
+ memset(&addr, 0, sizeof(addr));
+ addr.iso_family = AF_BLUETOOTH;
+ bacpy(&addr.iso_bdaddr, bdaddr);
+ addr.iso_bdaddr_type = BDADDR_LE_PUBLIC;
+
+Broadcast example:
+
+.. code-block::
+
+ struct sockaddr_iso *addr;
+ size_t addr_len;
+
+ addr_len = sizeof(*addr) + sizeof(*addr->iso_bc);
+
+ memset(addr, 0, addr_len);
+ addr->iso_family = AF_BLUETOOTH;
+ bacpy(&addr->iso_bdaddr, bdaddr);
+ addr->iso_bdaddr_type = BDADDR_LE_PUBLIC;
+
+Broadcast Source (Broadcaster) example:
+
+.. code-block::
+
+ struct sockaddr_iso *addr;
+ size_t addr_len;
+
+ addr_len = sizeof(*addr) + sizeof(*addr->iso_bc);
+
+ memset(addr, 0, addr_len);
+ addr->iso_family = AF_BLUETOOTH;
+
+ /* Set address to BDADR_ANY(00:00:00:00:00:00) */
+ bacpy(&addr->iso_bdaddr, BADDR_ANY);
+ addr->iso_bdaddr_type = BDADDR_LE_PUBLIC;
+
+ /* Connect to Broadcast address */
+ connect(iso_socket, (struct sockaddr *)addr, addr_len);
+
+Broadcast Sink (Receiver) example:
+
+.. code-block::
+
+ struct sockaddr_iso *addr;
+ size_t addr_len;
+
+ addr_len = sizeof(*addr) + sizeof(*addr->iso_bc);
+
+ memset(addr, 0, addr_len);
+ addr->iso_family = AF_BLUETOOTH;
+
+ /* Set destination to Broadcaster address */
+ bacpy(&addr->iso_bdaddr, bdaddr);
+ addr->iso_bdaddr_type = BDADDR_LE_PUBLIC;
+
+ /* Bind to Broadcaster address */
+ bind(iso_socket, (struct sockaddr *)addr, addr_len);
+
+SOCKET OPTIONS (SOL_BLUETOOTH)
+==============================
+
+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
+-----------
+
+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::
+
+ int level = BT_SECURITY_HIGH;
+ int err = setsockopt(iso_socket, SOL_BLUETOOTH, BT_SECURITY, &level,
+ sizeof(level));
+ if (err == -1) {
+ perror("setsockopt");
+ return 1;
+ }
+
+BT_DEFER_SETUP
+--------------
+
+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::
+
+ int defer_setup = 1;
+ int err = setsockopt(iso_socket, SOL_BLUETOOTH, BT_DEFER_SETUP,
+ &defer_setup, sizeof(defer_setup));
+ if (err == -1) {
+ perror("setsockopt");
+ return err;
+ }
+
+ err = listen(iso_socket, 5);
+ if (err) {
+ perror("listen");
+ return err;
+ }
+
+ struct sockaddr_iso remote_addr = {0};
+ socklen_t addr_len = sizeof(remote_addr);
+ int new_socket = accept(iso_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_PKT_STATUS
+-------------
+
+Enable reporting packet status via `BT_SCM_PKT_STATUS` CMSG on
+received packets. Possible values:
+
+.. csv-table::
+ :header: "Value", "Description"
+ :widths: auto
+
+ **0**, Disable (default)
+ **1**, Enable
+
+
+:BT_SCM_PKT_STATUS:
+
+ Level ``SOL_BLUETOOTH`` CMSG with data::
+
+ uint8_t pkt_status;
+
+ The values are equal to the "Packet_Status_Flag" defined in
+ Core Specification v6.1, 5.4.5. HCI ISO Data packets:
+
+ https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-61/out/en/host-controller-interface/host-controller-interface-functional-specification.html#UUID-9b5fb085-278b-5084-ac33-bee2839abe6b
+
+ .. csv-table::
+ :header: "pkt_status", "Description"
+ :widths: auto
+
+ **0x0**, Valid data. The complete SDU was received correctly.
+ **0x1**, Possibly invalid data. The contents of the ISO_SDU_Fragment
+ , may contain errors or part of the SDU may be missing.
+ , This is reported as "data with possible errors".
+ **0x2**, Part(s) of the SDU were not received correctly.
+ , This is reported as "lost data".
+
+SOCKET OPTIONS (SOL_SOCKET)
+===========================
+
+``SOL_SOCKET`` level socket options that modify generic socket
+features (``SO_SNDBUF``, ``SO_RCVBUF``, etc.) have their usual
+meaning, see **socket(7)**.
+
+The ``SOL_SOCKET`` level ISO socket options that have
+Bluetooth-specific handling in kernel are listed below.
+
+SO_TIMESTAMPING, SO_TIMESTAMP, SO_TIMESTAMPNS
+---------------------------------------------
+
+See https://docs.kernel.org/networking/timestamping.html
+
+For ISO sockets, software RX timestamps are supported. Software TX
+timestamps (SOF_TIMESTAMPING_TX_SOFTWARE) are supported since
+Linux 6.15.
+
+The software RX timestamp is the time when the kernel received the
+packet from the controller driver.
+
+The ``SCM_TSTAMP_SND`` timestamp is emitted when packet is sent to the
+controller driver.
+
+The ``SCM_TSTAMP_COMPLETION`` timestamp is emitted when controller
+reports the packet completed. Completion timestamps are only
+supported on controllers that have ISO flow control. Other TX
+timestamp types are not supported.
+
+You can use ``SIOCETHTOOL`` to query supported flags.
+
+The timestamps are in ``CLOCK_REALTIME`` time.
+
+Example (Enable RX timestamping):
+
+.. code-block::
+
+ int flags = SOF_TIMESTAMPING_SOFTWARE |
+ SOF_TIMESTAMPING_RX_SOFTWARE;
+ setsockopt(fd, SOL_SOCKET, SO_TIMESTAMPING, &flags, sizeof(flags));
+
+Example (Read packet and its RX timestamp):
+
+.. code-block::
+
+ char data_buf[256];
+ union {
+ char buf[CMSG_SPACE(sizeof(struct scm_timestamping))];
+ struct cmsghdr align;
+ } control;
+ struct iovec data = {
+ .iov_base = data_buf,
+ .iov_len = sizeof(data_buf),
+ };
+ struct msghdr msg = {
+ .msg_iov = &data,
+ .msg_iovlen = 1,
+ .msg_control = control.buf,
+ .msg_controllen = sizeof(control.buf),
+ };
+ struct scm_timestamping tss;
+
+ res = recvmsg(fd, &msg, MSG_ERRQUEUE | MSG_DONTWAIT);
+ if (res < 0)
+ goto error;
+
+ for (cmsg = CMSG_FIRSTHDR(&msg); cmsg; cmsg = CMSG_NXTHDR(&msg, cmsg)) {
+ if (cmsg->cmsg_level == SOL_SOCKET && cmsg->cmsg_type == SCM_TIMESTAMPING)
+ memcpy(&tss, CMSG_DATA(cmsg), sizeof(tss));
+ }
+
+ tstamp_clock_realtime = tss.ts[0];
+
+Example (Enable TX timestamping):
+
+.. code-block::
+
+ int flags = SOF_TIMESTAMPING_SOFTWARE |
+ SOF_TIMESTAMPING_TX_SOFTWARE |
+ SOF_TIMESTAMPING_OPT_ID;
+ setsockopt(fd, SOL_SOCKET, SO_TIMESTAMPING, &flags, sizeof(flags));
+
+Example (Read TX timestamps):
+
+.. code-block::
+
+ union {
+ char buf[CMSG_SPACE(sizeof(struct scm_timestamping))];
+ struct cmsghdr align;
+ } control;
+ struct iovec data = {
+ .iov_base = NULL,
+ .iov_len = 0
+ };
+ struct msghdr msg = {
+ .msg_iov = &data,
+ .msg_iovlen = 1,
+ .msg_control = control.buf,
+ .msg_controllen = sizeof(control.buf),
+ };
+ struct cmsghdr *cmsg;
+ struct scm_timestamping tss;
+ struct sock_extended_err serr;
+ int res;
+
+ res = recvmsg(fd, &msg, MSG_ERRQUEUE | MSG_DONTWAIT);
+ if (res < 0)
+ goto error;
+
+ for (cmsg = CMSG_FIRSTHDR(&msg); cmsg; cmsg = CMSG_NXTHDR(&msg, cmsg)) {
+ if (cmsg->cmsg_level == SOL_SOCKET && cmsg->cmsg_type == SCM_TIMESTAMPING)
+ memcpy(&tss, CMSG_DATA(cmsg), sizeof(tss));
+ else if (cmsg->cmsg_level == SOL_BLUETOOTH && cmsg->cmsg_type == BT_SCM_ERROR)
+ memcpy(&serr, CMSG_DATA(cmsg), sizeof(serr));
+ }
+
+ tstamp_clock_realtime = tss.ts[0];
+ tstamp_type = serr->ee_info; /* SCM_TSTAMP_SND or SCM_TSTAMP_COMPLETION */
+ tstamp_seqnum = serr->ee_data;
+
+
+IOCTLS
+======
+
+The following ioctls with operation specific for ISO sockets are
+available.
+
+SIOCETHTOOL (since Linux 6.16-rc1)
+----------------------------------
+
+Supports only command `ETHTOOL_GET_TS_INFO`, which may be used to
+query supported `SOF_TIMESTAMPING_*` flags. The
+`SOF_TIMESTAMPING_OPT_*` flags are always available as applicable.
+
+Example:
+
+.. code-block::
+
+ #include <linux/ethtool.h>
+ #include <linux/sockios.h>
+ #include <net/if.h>
+ #include <sys/socket.h>
+ #include <sys/ioctl.h>
+
+ ...
+
+ struct ifreq ifr = {};
+ struct ethtool_ts_info cmd = {};
+ int sk;
+
+ snprintf(ifr.ifr_name, sizeof(ifr.ifr_name), "hci0");
+ ifr.ifr_data = (void *)&cmd;
+ cmd.cmd = ETHTOOL_GET_TS_INFO;
+
+ sk = socket(PF_BLUETOOTH, SOCK_SEQPACKET, BTPROTO_ISO);
+ if (sk < 0)
+ goto error;
+ if (ioctl(sk, SIOCETHTOOL, &ifr))
+ goto error;
+
+ sof_available = cmd.so_timestamping;
+
+RESOURCES
+=========
+
+http://www.bluez.org
+
+REPORTING BUGS
+==============
+
+linux-bluetooth@vger.kernel.org
+
+SEE ALSO
+========
+
+socket(7), isotest(1)
--
2.50.0
^ permalink raw reply related [flat|nested] 5+ messages in thread
* Re: [PATCH BlueZ v1] doc: Add initial ISO(7) documentation
2025-07-15 18:07 [PATCH BlueZ v1] doc: Add initial ISO(7) documentation Luiz Augusto von Dentz
@ 2025-07-15 18:17 ` Luiz Augusto von Dentz
2025-07-15 19:49 ` Pauli Virtanen
2025-07-15 19:48 ` [BlueZ,v1] " bluez.test.bot
1 sibling, 1 reply; 5+ messages in thread
From: Luiz Augusto von Dentz @ 2025-07-15 18:17 UTC (permalink / raw)
To: linux-bluetooth, Pauli Virtanen
Hi Pauli,
On Tue, Jul 15, 2025 at 2:07 PM Luiz Augusto von Dentz
<luiz.dentz@gmail.com> wrote:
>
> From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
>
> This adds initial documentation for ISO sockets.
> ---
> Makefile.am | 8 +-
> doc/iso.rst | 436 ++++++++++++++++++++++++++++++++++++++++++++++++++++
> 2 files changed, 441 insertions(+), 3 deletions(-)
> create mode 100644 doc/iso.rst
>
> diff --git a/Makefile.am b/Makefile.am
> index c4b88d83c962..8319373409cd 100644
> --- a/Makefile.am
> +++ b/Makefile.am
> @@ -356,7 +356,7 @@ CLEANFILES += $(builtin_files)
>
> if MANPAGES
> man_MANS += src/bluetoothd.8
> -man_MANS += doc/hci.7 doc/mgmt.7 doc/l2cap.7 doc/rfcomm.7 doc/sco.7
> +man_MANS += doc/hci.7 doc/mgmt.7 doc/l2cap.7 doc/rfcomm.7 doc/sco.7 doc/iso.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 \
> @@ -390,7 +390,8 @@ man_MANS += doc/org.bluez.obex.Client.5 doc/org.bluez.obex.Session.5 \
> doc/org.bluez.obex.Image.5
> endif
> manual_pages += src/bluetoothd.8
> -manual_pages += doc/hci.7 doc/mgmt.7 doc/l2cap.7 doc/rfcomm.7 doc/sco.7
> +manual_pages += doc/hci.7 doc/mgmt.7 doc/l2cap.7 doc/rfcomm.7 doc/sco.7 \
> + doc/iso.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 \
> @@ -467,7 +468,8 @@ EXTRA_DIST += doc/assigned-numbers.txt doc/supported-features.txt \
> EXTRA_DIST += doc/health-api.txt \
> doc/sap-api.txt
>
> -EXTRA_DIST += doc/hci.rst doc/mgmt.rst doc/l2cap.rst doc/rfcomm.rst doc/sco.rst
> +EXTRA_DIST += doc/hci.rst doc/mgmt.rst doc/l2cap.rst doc/rfcomm.rst \
> + doc/sco.rst doc/iso.rst
>
> EXTRA_DIST += doc/org.bluez.Adapter.rst doc/org.bluez.Device.rst \
> doc/org.bluez.DeviceSet.rst doc/org.bluez.AgentManager.rst \
> diff --git a/doc/iso.rst b/doc/iso.rst
> new file mode 100644
> index 000000000000..d08b60d20865
> --- /dev/null
> +++ b/doc/iso.rst
> @@ -0,0 +1,436 @@
> +===
> +iso
> +===
> +-------------
> +ISO transport
> +-------------
> +
> +:Version: BlueZ
> +:Copyright: Free use of this software is granted under the terms of the GNU
> + Lesser General Public Licenses (LGPL).
> +:Date: July 2025
> +:Manual section: 7
> +:Manual group: Linux System Administration
> +
> +SYNOPSIS (since Linux 6.0 [experimental])
> +=========================================
> +
> +.. code-block::
> +
> + #include <sys/socket.h>
> + #include <bluetooth/bluetooth.h>
> + #include <bluetooth/iso.h>
> +
> + iso_socket = socket(PF_BLUETOOTH, SOCK_SEQPACKET, BTPROTO_ISO);
> +
> +DESCRIPTION
> +===========
> +
> +Bluetooth Isochronous Channels is a feature introduced in Bluetooth 5.2 that
> +allow for the transmission of multiple, synchronized audio streams between
> +devices.
> +
> +For unicast/multi-stream audio, connected isochronous group (CIG), and
> +connected isochronous stream (CIS) are used. A CIG is created by the central and
> +it can include one or more CISs. A CIS is a point-to-point data transportation
> +stream between a central and a certain peripheral, and is a bidirectional
> +communication protocol with acknowledgment.
> +
> +For broadcast audio, broadcast isochronous group (BIG) and broadcast isochronous
> +stream (BIS) are used. There are two types of devices: isochronous broadcaster
> +and synchronized receiver. A BIG is created by an isochronous broadcaster, and
> +it can include one or more BISs. A BIS is a one-to-many data transportation
> +stream.
> +
> +SOCKET ADDRESS
> +==============
> +
> +.. code-block::
> +
> + struct sockaddr_iso_bc {
> + bdaddr_t bc_bdaddr;
> + uint8_t bc_bdaddr_type;
> + uint8_t bc_sid;
> + uint8_t bc_num_bis;
> + uint8_t bc_bis[ISO_MAX_NUM_BIS];
> + };
> +
> + struct sockaddr_iso {
> + sa_family_t iso_family;
> + bdaddr_t iso_bdaddr;
> + uint8_t iso_bdaddr_type;
> + struct sockaddr_iso_bc iso_bc[];
> + };
> +
> +Unicast example:
> +
> +.. code-block::
> +
> + struct sockaddr_iso addr;
> +
> + memset(&addr, 0, sizeof(addr));
> + addr.iso_family = AF_BLUETOOTH;
> + bacpy(&addr.iso_bdaddr, bdaddr);
> + addr.iso_bdaddr_type = BDADDR_LE_PUBLIC;
> +
> +Broadcast example:
> +
> +.. code-block::
> +
> + struct sockaddr_iso *addr;
> + size_t addr_len;
> +
> + addr_len = sizeof(*addr) + sizeof(*addr->iso_bc);
> +
> + memset(addr, 0, addr_len);
> + addr->iso_family = AF_BLUETOOTH;
> + bacpy(&addr->iso_bdaddr, bdaddr);
> + addr->iso_bdaddr_type = BDADDR_LE_PUBLIC;
> +
> +Broadcast Source (Broadcaster) example:
> +
> +.. code-block::
> +
> + struct sockaddr_iso *addr;
> + size_t addr_len;
> +
> + addr_len = sizeof(*addr) + sizeof(*addr->iso_bc);
> +
> + memset(addr, 0, addr_len);
> + addr->iso_family = AF_BLUETOOTH;
> +
> + /* Set address to BDADR_ANY(00:00:00:00:00:00) */
> + bacpy(&addr->iso_bdaddr, BADDR_ANY);
> + addr->iso_bdaddr_type = BDADDR_LE_PUBLIC;
> +
> + /* Connect to Broadcast address */
> + connect(iso_socket, (struct sockaddr *)addr, addr_len);
> +
> +Broadcast Sink (Receiver) example:
> +
> +.. code-block::
> +
> + struct sockaddr_iso *addr;
> + size_t addr_len;
> +
> + addr_len = sizeof(*addr) + sizeof(*addr->iso_bc);
> +
> + memset(addr, 0, addr_len);
> + addr->iso_family = AF_BLUETOOTH;
> +
> + /* Set destination to Broadcaster address */
> + bacpy(&addr->iso_bdaddr, bdaddr);
> + addr->iso_bdaddr_type = BDADDR_LE_PUBLIC;
> +
> + /* Bind to Broadcaster address */
> + bind(iso_socket, (struct sockaddr *)addr, addr_len);
> +
> +SOCKET OPTIONS (SOL_BLUETOOTH)
> +==============================
> +
> +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
> +-----------
> +
> +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::
> +
> + int level = BT_SECURITY_HIGH;
> + int err = setsockopt(iso_socket, SOL_BLUETOOTH, BT_SECURITY, &level,
> + sizeof(level));
> + if (err == -1) {
> + perror("setsockopt");
> + return 1;
> + }
> +
> +BT_DEFER_SETUP
> +--------------
> +
> +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::
> +
> + int defer_setup = 1;
> + int err = setsockopt(iso_socket, SOL_BLUETOOTH, BT_DEFER_SETUP,
> + &defer_setup, sizeof(defer_setup));
> + if (err == -1) {
> + perror("setsockopt");
> + return err;
> + }
> +
> + err = listen(iso_socket, 5);
> + if (err) {
> + perror("listen");
> + return err;
> + }
> +
> + struct sockaddr_iso remote_addr = {0};
> + socklen_t addr_len = sizeof(remote_addr);
> + int new_socket = accept(iso_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_PKT_STATUS
> +-------------
> +
> +Enable reporting packet status via `BT_SCM_PKT_STATUS` CMSG on
> +received packets. Possible values:
> +
> +.. csv-table::
> + :header: "Value", "Description"
> + :widths: auto
> +
> + **0**, Disable (default)
> + **1**, Enable
> +
> +
> +:BT_SCM_PKT_STATUS:
> +
> + Level ``SOL_BLUETOOTH`` CMSG with data::
> +
> + uint8_t pkt_status;
> +
> + The values are equal to the "Packet_Status_Flag" defined in
> + Core Specification v6.1, 5.4.5. HCI ISO Data packets:
> +
> + https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-61/out/en/host-controller-interface/host-controller-interface-functional-specification.html#UUID-9b5fb085-278b-5084-ac33-bee2839abe6b
> +
> + .. csv-table::
> + :header: "pkt_status", "Description"
> + :widths: auto
> +
> + **0x0**, Valid data. The complete SDU was received correctly.
> + **0x1**, Possibly invalid data. The contents of the ISO_SDU_Fragment
> + , may contain errors or part of the SDU may be missing.
> + , This is reported as "data with possible errors".
> + **0x2**, Part(s) of the SDU were not received correctly.
> + , This is reported as "lost data".
> +
> +SOCKET OPTIONS (SOL_SOCKET)
> +===========================
> +
> +``SOL_SOCKET`` level socket options that modify generic socket
> +features (``SO_SNDBUF``, ``SO_RCVBUF``, etc.) have their usual
> +meaning, see **socket(7)**.
> +
> +The ``SOL_SOCKET`` level ISO socket options that have
> +Bluetooth-specific handling in kernel are listed below.
> +
> +SO_TIMESTAMPING, SO_TIMESTAMP, SO_TIMESTAMPNS
> +---------------------------------------------
> +
> +See https://docs.kernel.org/networking/timestamping.html
> +
> +For ISO sockets, software RX timestamps are supported. Software TX
> +timestamps (SOF_TIMESTAMPING_TX_SOFTWARE) are supported since
> +Linux 6.15.
> +
> +The software RX timestamp is the time when the kernel received the
> +packet from the controller driver.
> +
> +The ``SCM_TSTAMP_SND`` timestamp is emitted when packet is sent to the
> +controller driver.
> +
> +The ``SCM_TSTAMP_COMPLETION`` timestamp is emitted when controller
> +reports the packet completed. Completion timestamps are only
> +supported on controllers that have ISO flow control. Other TX
> +timestamp types are not supported.
> +
> +You can use ``SIOCETHTOOL`` to query supported flags.
> +
> +The timestamps are in ``CLOCK_REALTIME`` time.
> +
> +Example (Enable RX timestamping):
> +
> +.. code-block::
> +
> + int flags = SOF_TIMESTAMPING_SOFTWARE |
> + SOF_TIMESTAMPING_RX_SOFTWARE;
> + setsockopt(fd, SOL_SOCKET, SO_TIMESTAMPING, &flags, sizeof(flags));
> +
> +Example (Read packet and its RX timestamp):
> +
> +.. code-block::
> +
> + char data_buf[256];
> + union {
> + char buf[CMSG_SPACE(sizeof(struct scm_timestamping))];
> + struct cmsghdr align;
> + } control;
> + struct iovec data = {
> + .iov_base = data_buf,
> + .iov_len = sizeof(data_buf),
> + };
> + struct msghdr msg = {
> + .msg_iov = &data,
> + .msg_iovlen = 1,
> + .msg_control = control.buf,
> + .msg_controllen = sizeof(control.buf),
> + };
> + struct scm_timestamping tss;
> +
> + res = recvmsg(fd, &msg, MSG_ERRQUEUE | MSG_DONTWAIT);
> + if (res < 0)
> + goto error;
> +
> + for (cmsg = CMSG_FIRSTHDR(&msg); cmsg; cmsg = CMSG_NXTHDR(&msg, cmsg)) {
> + if (cmsg->cmsg_level == SOL_SOCKET && cmsg->cmsg_type == SCM_TIMESTAMPING)
> + memcpy(&tss, CMSG_DATA(cmsg), sizeof(tss));
> + }
> +
> + tstamp_clock_realtime = tss.ts[0];
> +
> +Example (Enable TX timestamping):
> +
> +.. code-block::
> +
> + int flags = SOF_TIMESTAMPING_SOFTWARE |
> + SOF_TIMESTAMPING_TX_SOFTWARE |
> + SOF_TIMESTAMPING_OPT_ID;
> + setsockopt(fd, SOL_SOCKET, SO_TIMESTAMPING, &flags, sizeof(flags));
> +
> +Example (Read TX timestamps):
> +
> +.. code-block::
> +
> + union {
> + char buf[CMSG_SPACE(sizeof(struct scm_timestamping))];
> + struct cmsghdr align;
> + } control;
> + struct iovec data = {
> + .iov_base = NULL,
> + .iov_len = 0
> + };
> + struct msghdr msg = {
> + .msg_iov = &data,
> + .msg_iovlen = 1,
> + .msg_control = control.buf,
> + .msg_controllen = sizeof(control.buf),
> + };
> + struct cmsghdr *cmsg;
> + struct scm_timestamping tss;
> + struct sock_extended_err serr;
> + int res;
> +
> + res = recvmsg(fd, &msg, MSG_ERRQUEUE | MSG_DONTWAIT);
> + if (res < 0)
> + goto error;
> +
> + for (cmsg = CMSG_FIRSTHDR(&msg); cmsg; cmsg = CMSG_NXTHDR(&msg, cmsg)) {
> + if (cmsg->cmsg_level == SOL_SOCKET && cmsg->cmsg_type == SCM_TIMESTAMPING)
> + memcpy(&tss, CMSG_DATA(cmsg), sizeof(tss));
> + else if (cmsg->cmsg_level == SOL_BLUETOOTH && cmsg->cmsg_type == BT_SCM_ERROR)
> + memcpy(&serr, CMSG_DATA(cmsg), sizeof(serr));
> + }
> +
> + tstamp_clock_realtime = tss.ts[0];
> + tstamp_type = serr->ee_info; /* SCM_TSTAMP_SND or SCM_TSTAMP_COMPLETION */
> + tstamp_seqnum = serr->ee_data;
> +
> +
> +IOCTLS
> +======
> +
> +The following ioctls with operation specific for ISO sockets are
> +available.
> +
> +SIOCETHTOOL (since Linux 6.16-rc1)
> +----------------------------------
> +
> +Supports only command `ETHTOOL_GET_TS_INFO`, which may be used to
> +query supported `SOF_TIMESTAMPING_*` flags. The
> +`SOF_TIMESTAMPING_OPT_*` flags are always available as applicable.
> +
> +Example:
> +
> +.. code-block::
> +
> + #include <linux/ethtool.h>
> + #include <linux/sockios.h>
> + #include <net/if.h>
> + #include <sys/socket.h>
> + #include <sys/ioctl.h>
> +
> + ...
> +
> + struct ifreq ifr = {};
> + struct ethtool_ts_info cmd = {};
> + int sk;
> +
> + snprintf(ifr.ifr_name, sizeof(ifr.ifr_name), "hci0");
> + ifr.ifr_data = (void *)&cmd;
> + cmd.cmd = ETHTOOL_GET_TS_INFO;
> +
> + sk = socket(PF_BLUETOOTH, SOCK_SEQPACKET, BTPROTO_ISO);
> + if (sk < 0)
> + goto error;
> + if (ioctl(sk, SIOCETHTOOL, &ifr))
> + goto error;
> +
> + sof_available = cmd.so_timestamping;
> +
> +RESOURCES
> +=========
> +
> +http://www.bluez.org
> +
> +REPORTING BUGS
> +==============
> +
> +linux-bluetooth@vger.kernel.org
> +
> +SEE ALSO
> +========
> +
> +socket(7), isotest(1)
> --
> 2.50.0
>
Have a look if the above makes sense, I didn't include BT_PKT_SEQNUM
since that is sort of new, but if you feel that should be included
from the start I just need an example to go with it.
--
Luiz Augusto von Dentz
^ permalink raw reply [flat|nested] 5+ messages in thread
* RE: [BlueZ,v1] doc: Add initial ISO(7) documentation
2025-07-15 18:07 [PATCH BlueZ v1] doc: Add initial ISO(7) documentation Luiz Augusto von Dentz
2025-07-15 18:17 ` Luiz Augusto von Dentz
@ 2025-07-15 19:48 ` bluez.test.bot
1 sibling, 0 replies; 5+ messages in thread
From: bluez.test.bot @ 2025-07-15 19:48 UTC (permalink / raw)
To: linux-bluetooth, luiz.dentz
[-- Attachment #1: Type: text/plain, Size: 1261 bytes --]
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=982635
---Test result---
Test Summary:
CheckPatch PENDING 0.35 seconds
GitLint PENDING 0.48 seconds
BuildEll PASS 20.10 seconds
BluezMake PASS 2966.96 seconds
MakeCheck PASS 20.47 seconds
MakeDistcheck PASS 193.24 seconds
CheckValgrind PASS 244.16 seconds
CheckSmatch PASS 316.42 seconds
bluezmakeextell PASS 130.35 seconds
IncrementalBuild PENDING 0.23 seconds
ScanBuild PASS 966.88 seconds
Details
##############################
Test: CheckPatch - PENDING
Desc: Run checkpatch.pl script
Output:
##############################
Test: GitLint - PENDING
Desc: Run gitlint
Output:
##############################
Test: IncrementalBuild - PENDING
Desc: Incremental build with the patches in the series
Output:
---
Regards,
Linux Bluetooth
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH BlueZ v1] doc: Add initial ISO(7) documentation
2025-07-15 18:17 ` Luiz Augusto von Dentz
@ 2025-07-15 19:49 ` Pauli Virtanen
2025-07-15 19:59 ` Luiz Augusto von Dentz
0 siblings, 1 reply; 5+ messages in thread
From: Pauli Virtanen @ 2025-07-15 19:49 UTC (permalink / raw)
To: Luiz Augusto von Dentz, linux-bluetooth
Hi,
ti, 2025-07-15 kello 14:17 -0400, Luiz Augusto von Dentz kirjoitti:
> Hi Pauli,
>
> On Tue, Jul 15, 2025 at 2:07 PM Luiz Augusto von Dentz
> <luiz.dentz@gmail.com> wrote:
> >
> > From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
> >
> > This adds initial documentation for ISO sockets.
> > ---
> > Makefile.am | 8 +-
> > doc/iso.rst | 436 ++++++++++++++++++++++++++++++++++++++++++++++++++++
> > 2 files changed, 441 insertions(+), 3 deletions(-)
> > create mode 100644 doc/iso.rst
> >
> > diff --git a/Makefile.am b/Makefile.am
> > index c4b88d83c962..8319373409cd 100644
> > --- a/Makefile.am
> > +++ b/Makefile.am
> > @@ -356,7 +356,7 @@ CLEANFILES += $(builtin_files)
> >
> > if MANPAGES
> > man_MANS += src/bluetoothd.8
> > -man_MANS += doc/hci.7 doc/mgmt.7 doc/l2cap.7 doc/rfcomm.7 doc/sco.7
> > +man_MANS += doc/hci.7 doc/mgmt.7 doc/l2cap.7 doc/rfcomm.7 doc/sco.7 doc/iso.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 \
> > @@ -390,7 +390,8 @@ man_MANS += doc/org.bluez.obex.Client.5 doc/org.bluez.obex.Session.5 \
> > doc/org.bluez.obex.Image.5
> > endif
> > manual_pages += src/bluetoothd.8
> > -manual_pages += doc/hci.7 doc/mgmt.7 doc/l2cap.7 doc/rfcomm.7 doc/sco.7
> > +manual_pages += doc/hci.7 doc/mgmt.7 doc/l2cap.7 doc/rfcomm.7 doc/sco.7 \
> > + doc/iso.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 \
> > @@ -467,7 +468,8 @@ EXTRA_DIST += doc/assigned-numbers.txt doc/supported-features.txt \
> > EXTRA_DIST += doc/health-api.txt \
> > doc/sap-api.txt
> >
> > -EXTRA_DIST += doc/hci.rst doc/mgmt.rst doc/l2cap.rst doc/rfcomm.rst doc/sco.rst
> > +EXTRA_DIST += doc/hci.rst doc/mgmt.rst doc/l2cap.rst doc/rfcomm.rst \
> > + doc/sco.rst doc/iso.rst
> >
> > EXTRA_DIST += doc/org.bluez.Adapter.rst doc/org.bluez.Device.rst \
> > doc/org.bluez.DeviceSet.rst doc/org.bluez.AgentManager.rst \
> > diff --git a/doc/iso.rst b/doc/iso.rst
> > new file mode 100644
> > index 000000000000..d08b60d20865
> > --- /dev/null
> > +++ b/doc/iso.rst
> > @@ -0,0 +1,436 @@
> > +===
> > +iso
> > +===
> > +-------------
> > +ISO transport
> > +-------------
> > +
> > +:Version: BlueZ
> > +:Copyright: Free use of this software is granted under the terms of the GNU
> > + Lesser General Public Licenses (LGPL).
> > +:Date: July 2025
> > +:Manual section: 7
> > +:Manual group: Linux System Administration
> > +
> > +SYNOPSIS (since Linux 6.0 [experimental])
> > +=========================================
> > +
> > +.. code-block::
> > +
> > + #include <sys/socket.h>
> > + #include <bluetooth/bluetooth.h>
> > + #include <bluetooth/iso.h>
> > +
> > + iso_socket = socket(PF_BLUETOOTH, SOCK_SEQPACKET, BTPROTO_ISO);
> > +
> > +DESCRIPTION
> > +===========
> > +
> > +Bluetooth Isochronous Channels is a feature introduced in Bluetooth 5.2 that
> > +allow for the transmission of multiple, synchronized audio streams between
> > +devices.
> > +
> > +For unicast/multi-stream audio, connected isochronous group (CIG), and
> > +connected isochronous stream (CIS) are used. A CIG is created by the central and
> > +it can include one or more CISs. A CIS is a point-to-point data transportation
> > +stream between a central and a certain peripheral, and is a bidirectional
> > +communication protocol with acknowledgment.
> > +
> > +For broadcast audio, broadcast isochronous group (BIG) and broadcast isochronous
> > +stream (BIS) are used. There are two types of devices: isochronous broadcaster
> > +and synchronized receiver. A BIG is created by an isochronous broadcaster, and
> > +it can include one or more BISs. A BIS is a one-to-many data transportation
> > +stream.
> > +
> > +SOCKET ADDRESS
> > +==============
> > +
> > +.. code-block::
> > +
> > + struct sockaddr_iso_bc {
> > + bdaddr_t bc_bdaddr;
> > + uint8_t bc_bdaddr_type;
> > + uint8_t bc_sid;
> > + uint8_t bc_num_bis;
> > + uint8_t bc_bis[ISO_MAX_NUM_BIS];
> > + };
> > +
> > + struct sockaddr_iso {
> > + sa_family_t iso_family;
> > + bdaddr_t iso_bdaddr;
> > + uint8_t iso_bdaddr_type;
> > + struct sockaddr_iso_bc iso_bc[];
> > + };
> > +
> > +Unicast example:
> > +
> > +.. code-block::
> > +
> > + struct sockaddr_iso addr;
> > +
> > + memset(&addr, 0, sizeof(addr));
> > + addr.iso_family = AF_BLUETOOTH;
> > + bacpy(&addr.iso_bdaddr, bdaddr);
> > + addr.iso_bdaddr_type = BDADDR_LE_PUBLIC;
> > +
> > +Broadcast example:
> > +
> > +.. code-block::
> > +
> > + struct sockaddr_iso *addr;
> > + size_t addr_len;
> > +
> > + addr_len = sizeof(*addr) + sizeof(*addr->iso_bc);
> > +
> > + memset(addr, 0, addr_len);
> > + addr->iso_family = AF_BLUETOOTH;
> > + bacpy(&addr->iso_bdaddr, bdaddr);
> > + addr->iso_bdaddr_type = BDADDR_LE_PUBLIC;
> > +
> > +Broadcast Source (Broadcaster) example:
> > +
> > +.. code-block::
> > +
> > + struct sockaddr_iso *addr;
> > + size_t addr_len;
> > +
> > + addr_len = sizeof(*addr) + sizeof(*addr->iso_bc);
> > +
> > + memset(addr, 0, addr_len);
> > + addr->iso_family = AF_BLUETOOTH;
> > +
> > + /* Set address to BDADR_ANY(00:00:00:00:00:00) */
> > + bacpy(&addr->iso_bdaddr, BADDR_ANY);
> > + addr->iso_bdaddr_type = BDADDR_LE_PUBLIC;
> > +
> > + /* Connect to Broadcast address */
> > + connect(iso_socket, (struct sockaddr *)addr, addr_len);
> > +
> > +Broadcast Sink (Receiver) example:
> > +
> > +.. code-block::
> > +
> > + struct sockaddr_iso *addr;
> > + size_t addr_len;
> > +
> > + addr_len = sizeof(*addr) + sizeof(*addr->iso_bc);
> > +
> > + memset(addr, 0, addr_len);
> > + addr->iso_family = AF_BLUETOOTH;
> > +
> > + /* Set destination to Broadcaster address */
> > + bacpy(&addr->iso_bdaddr, bdaddr);
> > + addr->iso_bdaddr_type = BDADDR_LE_PUBLIC;
> > +
> > + /* Bind to Broadcaster address */
> > + bind(iso_socket, (struct sockaddr *)addr, addr_len);
> > +
> > +SOCKET OPTIONS (SOL_BLUETOOTH)
> > +==============================
> > +
> > +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
> > +-----------
> > +
> > +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::
> > +
> > + int level = BT_SECURITY_HIGH;
> > + int err = setsockopt(iso_socket, SOL_BLUETOOTH, BT_SECURITY, &level,
> > + sizeof(level));
> > + if (err == -1) {
> > + perror("setsockopt");
> > + return 1;
> > + }
> > +
> > +BT_DEFER_SETUP
> > +--------------
> > +
> > +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::
> > +
> > + int defer_setup = 1;
> > + int err = setsockopt(iso_socket, SOL_BLUETOOTH, BT_DEFER_SETUP,
> > + &defer_setup, sizeof(defer_setup));
> > + if (err == -1) {
> > + perror("setsockopt");
> > + return err;
> > + }
> > +
> > + err = listen(iso_socket, 5);
> > + if (err) {
> > + perror("listen");
> > + return err;
> > + }
> > +
> > + struct sockaddr_iso remote_addr = {0};
> > + socklen_t addr_len = sizeof(remote_addr);
> > + int new_socket = accept(iso_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_PKT_STATUS
> > +-------------
> > +
> > +Enable reporting packet status via `BT_SCM_PKT_STATUS` CMSG on
> > +received packets. Possible values:
> > +
> > +.. csv-table::
> > + :header: "Value", "Description"
> > + :widths: auto
> > +
> > + **0**, Disable (default)
> > + **1**, Enable
> > +
> > +
> > +:BT_SCM_PKT_STATUS:
> > +
> > + Level ``SOL_BLUETOOTH`` CMSG with data::
> > +
> > + uint8_t pkt_status;
> > +
> > + The values are equal to the "Packet_Status_Flag" defined in
> > + Core Specification v6.1, 5.4.5. HCI ISO Data packets:
> > +
> > + https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-61/out/en/host-controller-interface/host-controller-interface-functional-specification.html#UUID-9b5fb085-278b-5084-ac33-bee2839abe6b
> > +
> > + .. csv-table::
> > + :header: "pkt_status", "Description"
> > + :widths: auto
> > +
> > + **0x0**, Valid data. The complete SDU was received correctly.
> > + **0x1**, Possibly invalid data. The contents of the ISO_SDU_Fragment
> > + , may contain errors or part of the SDU may be missing.
> > + , This is reported as "data with possible errors".
> > + **0x2**, Part(s) of the SDU were not received correctly.
> > + , This is reported as "lost data".
> > +
> > +SOCKET OPTIONS (SOL_SOCKET)
> > +===========================
> > +
> > +``SOL_SOCKET`` level socket options that modify generic socket
> > +features (``SO_SNDBUF``, ``SO_RCVBUF``, etc.) have their usual
> > +meaning, see **socket(7)**.
> > +
> > +The ``SOL_SOCKET`` level ISO socket options that have
> > +Bluetooth-specific handling in kernel are listed below.
> > +
> > +SO_TIMESTAMPING, SO_TIMESTAMP, SO_TIMESTAMPNS
> > +---------------------------------------------
> > +
> > +See https://docs.kernel.org/networking/timestamping.html
> > +
> > +For ISO sockets, software RX timestamps are supported. Software TX
> > +timestamps (SOF_TIMESTAMPING_TX_SOFTWARE) are supported since
> > +Linux 6.15.
> > +
> > +The software RX timestamp is the time when the kernel received the
> > +packet from the controller driver.
> > +
> > +The ``SCM_TSTAMP_SND`` timestamp is emitted when packet is sent to the
> > +controller driver.
> > +
> > +The ``SCM_TSTAMP_COMPLETION`` timestamp is emitted when controller
> > +reports the packet completed. Completion timestamps are only
> > +supported on controllers that have ISO flow control.
> >
Completion timestamps are always available for ISO, as currently kernel
only does flow-controlled ISO.
> > Other TX
> > +timestamp types are not supported.
> > +
> > +You can use ``SIOCETHTOOL`` to query supported flags.
> > +
> > +The timestamps are in ``CLOCK_REALTIME`` time.
> > +
> > +Example (Enable RX timestamping):
> > +
> > +.. code-block::
> > +
> > + int flags = SOF_TIMESTAMPING_SOFTWARE |
> > + SOF_TIMESTAMPING_RX_SOFTWARE;
> > + setsockopt(fd, SOL_SOCKET, SO_TIMESTAMPING, &flags, sizeof(flags));
> > +
> > +Example (Read packet and its RX timestamp):
> > +
> > +.. code-block::
> > +
> > + char data_buf[256];
> > + union {
> > + char buf[CMSG_SPACE(sizeof(struct scm_timestamping))];
> > + struct cmsghdr align;
> > + } control;
> > + struct iovec data = {
> > + .iov_base = data_buf,
> > + .iov_len = sizeof(data_buf),
> > + };
> > + struct msghdr msg = {
> > + .msg_iov = &data,
> > + .msg_iovlen = 1,
> > + .msg_control = control.buf,
> > + .msg_controllen = sizeof(control.buf),
> > + };
> > + struct scm_timestamping tss;
> > +
> > + res = recvmsg(fd, &msg, MSG_ERRQUEUE | MSG_DONTWAIT);
> > + if (res < 0)
> > + goto error;
> > +
> > + for (cmsg = CMSG_FIRSTHDR(&msg); cmsg; cmsg = CMSG_NXTHDR(&msg, cmsg)) {
> > + if (cmsg->cmsg_level == SOL_SOCKET && cmsg->cmsg_type == SCM_TIMESTAMPING)
> > + memcpy(&tss, CMSG_DATA(cmsg), sizeof(tss));
> > + }
> > +
> > + tstamp_clock_realtime = tss.ts[0];
> > +
> > +Example (Enable TX timestamping):
> > +
> > +.. code-block::
> > +
> > + int flags = SOF_TIMESTAMPING_SOFTWARE |
> > + SOF_TIMESTAMPING_TX_SOFTWARE |
> > + SOF_TIMESTAMPING_OPT_ID;
> > + setsockopt(fd, SOL_SOCKET, SO_TIMESTAMPING, &flags, sizeof(flags));
> > +
> > +Example (Read TX timestamps):
> > +
> > +.. code-block::
> > +
> > + union {
> > + char buf[CMSG_SPACE(sizeof(struct scm_timestamping))];
> > + struct cmsghdr align;
> > + } control;
> > + struct iovec data = {
> > + .iov_base = NULL,
> > + .iov_len = 0
> > + };
> > + struct msghdr msg = {
> > + .msg_iov = &data,
> > + .msg_iovlen = 1,
> > + .msg_control = control.buf,
> > + .msg_controllen = sizeof(control.buf),
> > + };
> > + struct cmsghdr *cmsg;
> > + struct scm_timestamping tss;
> > + struct sock_extended_err serr;
> > + int res;
> > +
> > + res = recvmsg(fd, &msg, MSG_ERRQUEUE | MSG_DONTWAIT);
> > + if (res < 0)
> > + goto error;
> > +
> > + for (cmsg = CMSG_FIRSTHDR(&msg); cmsg; cmsg = CMSG_NXTHDR(&msg, cmsg)) {
> > + if (cmsg->cmsg_level == SOL_SOCKET && cmsg->cmsg_type == SCM_TIMESTAMPING)
> > + memcpy(&tss, CMSG_DATA(cmsg), sizeof(tss));
> > + else if (cmsg->cmsg_level == SOL_BLUETOOTH && cmsg->cmsg_type == BT_SCM_ERROR)
> > + memcpy(&serr, CMSG_DATA(cmsg), sizeof(serr));
> > + }
> > +
> > + tstamp_clock_realtime = tss.ts[0];
> > + tstamp_type = serr->ee_info; /* SCM_TSTAMP_SND or SCM_TSTAMP_COMPLETION */
> > + tstamp_seqnum = serr->ee_data;
> > +
> > +
> > +IOCTLS
> > +======
> > +
> > +The following ioctls with operation specific for ISO sockets are
> > +available.
> > +
> > +SIOCETHTOOL (since Linux 6.16-rc1)
> > +----------------------------------
> > +
> > +Supports only command `ETHTOOL_GET_TS_INFO`, which may be used to
> > +query supported `SOF_TIMESTAMPING_*` flags. The
> > +`SOF_TIMESTAMPING_OPT_*` flags are always available as applicable.
> > +
> > +Example:
> > +
> > +.. code-block::
> > +
> > + #include <linux/ethtool.h>
> > + #include <linux/sockios.h>
> > + #include <net/if.h>
> > + #include <sys/socket.h>
> > + #include <sys/ioctl.h>
> > +
> > + ...
> > +
> > + struct ifreq ifr = {};
> > + struct ethtool_ts_info cmd = {};
> > + int sk;
> > +
> > + snprintf(ifr.ifr_name, sizeof(ifr.ifr_name), "hci0");
> > + ifr.ifr_data = (void *)&cmd;
> > + cmd.cmd = ETHTOOL_GET_TS_INFO;
> > +
> > + sk = socket(PF_BLUETOOTH, SOCK_SEQPACKET, BTPROTO_ISO);
> > + if (sk < 0)
> > + goto error;
> > + if (ioctl(sk, SIOCETHTOOL, &ifr))
> > + goto error;
> > +
> > + sof_available = cmd.so_timestamping;
> > +
> > +RESOURCES
> > +=========
> > +
> > +http://www.bluez.org
> > +
> > +REPORTING BUGS
> > +==============
> > +
> > +linux-bluetooth@vger.kernel.org
> > +
> > +SEE ALSO
> > +========
> > +
> > +socket(7), isotest(1)
> > --
> > 2.50.0
> >
>
> Have a look if the above makes sense, I didn't include BT_PKT_SEQNUM
> since that is sort of new, but if you feel that should be included
> from the start I just need an example to go with it.
Looks right to me. BT_PKT_SEQNUM if added would be like
BT_PKT_SEQNUM
-------------
Enable reporting packet ISO sequence number via `BT_SCM_PKT_SEQNUM`
CMSG on received packets. Possible values:
.. csv-table::
:header: "Value", "Description"
:widths: auto
**0**, Disable (default)
**1**, Enable
:BT_SCM_PKT_SEQNUM:
Level ``SOL_BLUETOOTH`` CMSG with data::
uint16_t pkt_seqnum;
The values are equal to the "Packet_Sequence_Number" defined in
Core Specification v6.1, 5.4.5. HCI ISO Data packets:
https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-61/out/en/host-controller-interface/host-controller-interface-functional-specification.html#UUID-9b5fb085-278b-5084-ac33-bee2839abe6b
Example (Enable sequence numbers):
.. code-block::
uint32_t opt = 1;
if (setsockopt(fd, SOL_BLUETOOTH, BT_PKT_SEQNUM, &opt, sizeof(opt)) < 0)
goto error;
Example (Read packet and its sequence number):
.. code-block::
char data_buf[256];
uint16_t seqnum;
union {
char buf[CMSG_SPACE(sizeof(uint16_t))];
struct cmsghdr align;
} control;
struct iovec data = {
.iov_base = data_buf,
.iov_len = sizeof(data_buf),
};
struct msghdr msg = {
.msg_iov = &data,
.msg_iovlen = 1,
.msg_control = control.buf,
.msg_controllen = sizeof(control.buf),
};
struct scm_timestamping tss;
res = recvmsg(fd, &msg, 0);
if (res < 0)
goto error;
for (cmsg = CMSG_FIRSTHDR(&msg); cmsg; cmsg = CMSG_NXTHDR(&msg, cmsg)) {
if (cmsg->cmsg_level == SOL_BLUETOOTH && cmsg->cmsg_type == BT_PKT_SEQNUM)
memcpy(&seqnum, CMSG_DATA(cmsg), sizeof(seqnum));
}
--
Pauli Virtanen
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH BlueZ v1] doc: Add initial ISO(7) documentation
2025-07-15 19:49 ` Pauli Virtanen
@ 2025-07-15 19:59 ` Luiz Augusto von Dentz
0 siblings, 0 replies; 5+ messages in thread
From: Luiz Augusto von Dentz @ 2025-07-15 19:59 UTC (permalink / raw)
To: Pauli Virtanen; +Cc: linux-bluetooth
Hi Pauli,
On Tue, Jul 15, 2025 at 3:49 PM Pauli Virtanen <pav@iki.fi> wrote:
>
> Hi,
>
> ti, 2025-07-15 kello 14:17 -0400, Luiz Augusto von Dentz kirjoitti:
> > Hi Pauli,
> >
> > On Tue, Jul 15, 2025 at 2:07 PM Luiz Augusto von Dentz
> > <luiz.dentz@gmail.com> wrote:
> > >
> > > From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
> > >
> > > This adds initial documentation for ISO sockets.
> > > ---
> > > Makefile.am | 8 +-
> > > doc/iso.rst | 436 ++++++++++++++++++++++++++++++++++++++++++++++++++++
> > > 2 files changed, 441 insertions(+), 3 deletions(-)
> > > create mode 100644 doc/iso.rst
> > >
> > > diff --git a/Makefile.am b/Makefile.am
> > > index c4b88d83c962..8319373409cd 100644
> > > --- a/Makefile.am
> > > +++ b/Makefile.am
> > > @@ -356,7 +356,7 @@ CLEANFILES += $(builtin_files)
> > >
> > > if MANPAGES
> > > man_MANS += src/bluetoothd.8
> > > -man_MANS += doc/hci.7 doc/mgmt.7 doc/l2cap.7 doc/rfcomm.7 doc/sco.7
> > > +man_MANS += doc/hci.7 doc/mgmt.7 doc/l2cap.7 doc/rfcomm.7 doc/sco.7 doc/iso.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 \
> > > @@ -390,7 +390,8 @@ man_MANS += doc/org.bluez.obex.Client.5 doc/org.bluez.obex.Session.5 \
> > > doc/org.bluez.obex.Image.5
> > > endif
> > > manual_pages += src/bluetoothd.8
> > > -manual_pages += doc/hci.7 doc/mgmt.7 doc/l2cap.7 doc/rfcomm.7 doc/sco.7
> > > +manual_pages += doc/hci.7 doc/mgmt.7 doc/l2cap.7 doc/rfcomm.7 doc/sco.7 \
> > > + doc/iso.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 \
> > > @@ -467,7 +468,8 @@ EXTRA_DIST += doc/assigned-numbers.txt doc/supported-features.txt \
> > > EXTRA_DIST += doc/health-api.txt \
> > > doc/sap-api.txt
> > >
> > > -EXTRA_DIST += doc/hci.rst doc/mgmt.rst doc/l2cap.rst doc/rfcomm.rst doc/sco.rst
> > > +EXTRA_DIST += doc/hci.rst doc/mgmt.rst doc/l2cap.rst doc/rfcomm.rst \
> > > + doc/sco.rst doc/iso.rst
> > >
> > > EXTRA_DIST += doc/org.bluez.Adapter.rst doc/org.bluez.Device.rst \
> > > doc/org.bluez.DeviceSet.rst doc/org.bluez.AgentManager.rst \
> > > diff --git a/doc/iso.rst b/doc/iso.rst
> > > new file mode 100644
> > > index 000000000000..d08b60d20865
> > > --- /dev/null
> > > +++ b/doc/iso.rst
> > > @@ -0,0 +1,436 @@
> > > +===
> > > +iso
> > > +===
> > > +-------------
> > > +ISO transport
> > > +-------------
> > > +
> > > +:Version: BlueZ
> > > +:Copyright: Free use of this software is granted under the terms of the GNU
> > > + Lesser General Public Licenses (LGPL).
> > > +:Date: July 2025
> > > +:Manual section: 7
> > > +:Manual group: Linux System Administration
> > > +
> > > +SYNOPSIS (since Linux 6.0 [experimental])
> > > +=========================================
> > > +
> > > +.. code-block::
> > > +
> > > + #include <sys/socket.h>
> > > + #include <bluetooth/bluetooth.h>
> > > + #include <bluetooth/iso.h>
> > > +
> > > + iso_socket = socket(PF_BLUETOOTH, SOCK_SEQPACKET, BTPROTO_ISO);
> > > +
> > > +DESCRIPTION
> > > +===========
> > > +
> > > +Bluetooth Isochronous Channels is a feature introduced in Bluetooth 5.2 that
> > > +allow for the transmission of multiple, synchronized audio streams between
> > > +devices.
> > > +
> > > +For unicast/multi-stream audio, connected isochronous group (CIG), and
> > > +connected isochronous stream (CIS) are used. A CIG is created by the central and
> > > +it can include one or more CISs. A CIS is a point-to-point data transportation
> > > +stream between a central and a certain peripheral, and is a bidirectional
> > > +communication protocol with acknowledgment.
> > > +
> > > +For broadcast audio, broadcast isochronous group (BIG) and broadcast isochronous
> > > +stream (BIS) are used. There are two types of devices: isochronous broadcaster
> > > +and synchronized receiver. A BIG is created by an isochronous broadcaster, and
> > > +it can include one or more BISs. A BIS is a one-to-many data transportation
> > > +stream.
> > > +
> > > +SOCKET ADDRESS
> > > +==============
> > > +
> > > +.. code-block::
> > > +
> > > + struct sockaddr_iso_bc {
> > > + bdaddr_t bc_bdaddr;
> > > + uint8_t bc_bdaddr_type;
> > > + uint8_t bc_sid;
> > > + uint8_t bc_num_bis;
> > > + uint8_t bc_bis[ISO_MAX_NUM_BIS];
> > > + };
> > > +
> > > + struct sockaddr_iso {
> > > + sa_family_t iso_family;
> > > + bdaddr_t iso_bdaddr;
> > > + uint8_t iso_bdaddr_type;
> > > + struct sockaddr_iso_bc iso_bc[];
> > > + };
> > > +
> > > +Unicast example:
> > > +
> > > +.. code-block::
> > > +
> > > + struct sockaddr_iso addr;
> > > +
> > > + memset(&addr, 0, sizeof(addr));
> > > + addr.iso_family = AF_BLUETOOTH;
> > > + bacpy(&addr.iso_bdaddr, bdaddr);
> > > + addr.iso_bdaddr_type = BDADDR_LE_PUBLIC;
> > > +
> > > +Broadcast example:
> > > +
> > > +.. code-block::
> > > +
> > > + struct sockaddr_iso *addr;
> > > + size_t addr_len;
> > > +
> > > + addr_len = sizeof(*addr) + sizeof(*addr->iso_bc);
> > > +
> > > + memset(addr, 0, addr_len);
> > > + addr->iso_family = AF_BLUETOOTH;
> > > + bacpy(&addr->iso_bdaddr, bdaddr);
> > > + addr->iso_bdaddr_type = BDADDR_LE_PUBLIC;
> > > +
> > > +Broadcast Source (Broadcaster) example:
> > > +
> > > +.. code-block::
> > > +
> > > + struct sockaddr_iso *addr;
> > > + size_t addr_len;
> > > +
> > > + addr_len = sizeof(*addr) + sizeof(*addr->iso_bc);
> > > +
> > > + memset(addr, 0, addr_len);
> > > + addr->iso_family = AF_BLUETOOTH;
> > > +
> > > + /* Set address to BDADR_ANY(00:00:00:00:00:00) */
> > > + bacpy(&addr->iso_bdaddr, BADDR_ANY);
> > > + addr->iso_bdaddr_type = BDADDR_LE_PUBLIC;
> > > +
> > > + /* Connect to Broadcast address */
> > > + connect(iso_socket, (struct sockaddr *)addr, addr_len);
> > > +
> > > +Broadcast Sink (Receiver) example:
> > > +
> > > +.. code-block::
> > > +
> > > + struct sockaddr_iso *addr;
> > > + size_t addr_len;
> > > +
> > > + addr_len = sizeof(*addr) + sizeof(*addr->iso_bc);
> > > +
> > > + memset(addr, 0, addr_len);
> > > + addr->iso_family = AF_BLUETOOTH;
> > > +
> > > + /* Set destination to Broadcaster address */
> > > + bacpy(&addr->iso_bdaddr, bdaddr);
> > > + addr->iso_bdaddr_type = BDADDR_LE_PUBLIC;
> > > +
> > > + /* Bind to Broadcaster address */
> > > + bind(iso_socket, (struct sockaddr *)addr, addr_len);
> > > +
> > > +SOCKET OPTIONS (SOL_BLUETOOTH)
> > > +==============================
> > > +
> > > +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
> > > +-----------
> > > +
> > > +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::
> > > +
> > > + int level = BT_SECURITY_HIGH;
> > > + int err = setsockopt(iso_socket, SOL_BLUETOOTH, BT_SECURITY, &level,
> > > + sizeof(level));
> > > + if (err == -1) {
> > > + perror("setsockopt");
> > > + return 1;
> > > + }
> > > +
> > > +BT_DEFER_SETUP
> > > +--------------
> > > +
> > > +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::
> > > +
> > > + int defer_setup = 1;
> > > + int err = setsockopt(iso_socket, SOL_BLUETOOTH, BT_DEFER_SETUP,
> > > + &defer_setup, sizeof(defer_setup));
> > > + if (err == -1) {
> > > + perror("setsockopt");
> > > + return err;
> > > + }
> > > +
> > > + err = listen(iso_socket, 5);
> > > + if (err) {
> > > + perror("listen");
> > > + return err;
> > > + }
> > > +
> > > + struct sockaddr_iso remote_addr = {0};
> > > + socklen_t addr_len = sizeof(remote_addr);
> > > + int new_socket = accept(iso_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_PKT_STATUS
> > > +-------------
> > > +
> > > +Enable reporting packet status via `BT_SCM_PKT_STATUS` CMSG on
> > > +received packets. Possible values:
> > > +
> > > +.. csv-table::
> > > + :header: "Value", "Description"
> > > + :widths: auto
> > > +
> > > + **0**, Disable (default)
> > > + **1**, Enable
> > > +
> > > +
> > > +:BT_SCM_PKT_STATUS:
> > > +
> > > + Level ``SOL_BLUETOOTH`` CMSG with data::
> > > +
> > > + uint8_t pkt_status;
> > > +
> > > + The values are equal to the "Packet_Status_Flag" defined in
> > > + Core Specification v6.1, 5.4.5. HCI ISO Data packets:
> > > +
> > > + https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-61/out/en/host-controller-interface/host-controller-interface-functional-specification.html#UUID-9b5fb085-278b-5084-ac33-bee2839abe6b
> > > +
> > > + .. csv-table::
> > > + :header: "pkt_status", "Description"
> > > + :widths: auto
> > > +
> > > + **0x0**, Valid data. The complete SDU was received correctly.
> > > + **0x1**, Possibly invalid data. The contents of the ISO_SDU_Fragment
> > > + , may contain errors or part of the SDU may be missing.
> > > + , This is reported as "data with possible errors".
> > > + **0x2**, Part(s) of the SDU were not received correctly.
> > > + , This is reported as "lost data".
> > > +
> > > +SOCKET OPTIONS (SOL_SOCKET)
> > > +===========================
> > > +
> > > +``SOL_SOCKET`` level socket options that modify generic socket
> > > +features (``SO_SNDBUF``, ``SO_RCVBUF``, etc.) have their usual
> > > +meaning, see **socket(7)**.
> > > +
> > > +The ``SOL_SOCKET`` level ISO socket options that have
> > > +Bluetooth-specific handling in kernel are listed below.
> > > +
> > > +SO_TIMESTAMPING, SO_TIMESTAMP, SO_TIMESTAMPNS
> > > +---------------------------------------------
> > > +
> > > +See https://docs.kernel.org/networking/timestamping.html
> > > +
> > > +For ISO sockets, software RX timestamps are supported. Software TX
> > > +timestamps (SOF_TIMESTAMPING_TX_SOFTWARE) are supported since
> > > +Linux 6.15.
> > > +
> > > +The software RX timestamp is the time when the kernel received the
> > > +packet from the controller driver.
> > > +
> > > +The ``SCM_TSTAMP_SND`` timestamp is emitted when packet is sent to the
> > > +controller driver.
> > > +
> > > +The ``SCM_TSTAMP_COMPLETION`` timestamp is emitted when controller
> > > +reports the packet completed. Completion timestamps are only
> > > +supported on controllers that have ISO flow control.
> > >
>
> Completion timestamps are always available for ISO, as currently kernel
> only does flow-controlled ISO.
>
> > > Other TX
> > > +timestamp types are not supported.
> > > +
> > > +You can use ``SIOCETHTOOL`` to query supported flags.
> > > +
> > > +The timestamps are in ``CLOCK_REALTIME`` time.
> > > +
> > > +Example (Enable RX timestamping):
> > > +
> > > +.. code-block::
> > > +
> > > + int flags = SOF_TIMESTAMPING_SOFTWARE |
> > > + SOF_TIMESTAMPING_RX_SOFTWARE;
> > > + setsockopt(fd, SOL_SOCKET, SO_TIMESTAMPING, &flags, sizeof(flags));
> > > +
> > > +Example (Read packet and its RX timestamp):
> > > +
> > > +.. code-block::
> > > +
> > > + char data_buf[256];
> > > + union {
> > > + char buf[CMSG_SPACE(sizeof(struct scm_timestamping))];
> > > + struct cmsghdr align;
> > > + } control;
> > > + struct iovec data = {
> > > + .iov_base = data_buf,
> > > + .iov_len = sizeof(data_buf),
> > > + };
> > > + struct msghdr msg = {
> > > + .msg_iov = &data,
> > > + .msg_iovlen = 1,
> > > + .msg_control = control.buf,
> > > + .msg_controllen = sizeof(control.buf),
> > > + };
> > > + struct scm_timestamping tss;
> > > +
> > > + res = recvmsg(fd, &msg, MSG_ERRQUEUE | MSG_DONTWAIT);
> > > + if (res < 0)
> > > + goto error;
> > > +
> > > + for (cmsg = CMSG_FIRSTHDR(&msg); cmsg; cmsg = CMSG_NXTHDR(&msg, cmsg)) {
> > > + if (cmsg->cmsg_level == SOL_SOCKET && cmsg->cmsg_type == SCM_TIMESTAMPING)
> > > + memcpy(&tss, CMSG_DATA(cmsg), sizeof(tss));
> > > + }
> > > +
> > > + tstamp_clock_realtime = tss.ts[0];
> > > +
> > > +Example (Enable TX timestamping):
> > > +
> > > +.. code-block::
> > > +
> > > + int flags = SOF_TIMESTAMPING_SOFTWARE |
> > > + SOF_TIMESTAMPING_TX_SOFTWARE |
> > > + SOF_TIMESTAMPING_OPT_ID;
> > > + setsockopt(fd, SOL_SOCKET, SO_TIMESTAMPING, &flags, sizeof(flags));
> > > +
> > > +Example (Read TX timestamps):
> > > +
> > > +.. code-block::
> > > +
> > > + union {
> > > + char buf[CMSG_SPACE(sizeof(struct scm_timestamping))];
> > > + struct cmsghdr align;
> > > + } control;
> > > + struct iovec data = {
> > > + .iov_base = NULL,
> > > + .iov_len = 0
> > > + };
> > > + struct msghdr msg = {
> > > + .msg_iov = &data,
> > > + .msg_iovlen = 1,
> > > + .msg_control = control.buf,
> > > + .msg_controllen = sizeof(control.buf),
> > > + };
> > > + struct cmsghdr *cmsg;
> > > + struct scm_timestamping tss;
> > > + struct sock_extended_err serr;
> > > + int res;
> > > +
> > > + res = recvmsg(fd, &msg, MSG_ERRQUEUE | MSG_DONTWAIT);
> > > + if (res < 0)
> > > + goto error;
> > > +
> > > + for (cmsg = CMSG_FIRSTHDR(&msg); cmsg; cmsg = CMSG_NXTHDR(&msg, cmsg)) {
> > > + if (cmsg->cmsg_level == SOL_SOCKET && cmsg->cmsg_type == SCM_TIMESTAMPING)
> > > + memcpy(&tss, CMSG_DATA(cmsg), sizeof(tss));
> > > + else if (cmsg->cmsg_level == SOL_BLUETOOTH && cmsg->cmsg_type == BT_SCM_ERROR)
> > > + memcpy(&serr, CMSG_DATA(cmsg), sizeof(serr));
> > > + }
> > > +
> > > + tstamp_clock_realtime = tss.ts[0];
> > > + tstamp_type = serr->ee_info; /* SCM_TSTAMP_SND or SCM_TSTAMP_COMPLETION */
> > > + tstamp_seqnum = serr->ee_data;
> > > +
> > > +
> > > +IOCTLS
> > > +======
> > > +
> > > +The following ioctls with operation specific for ISO sockets are
> > > +available.
> > > +
> > > +SIOCETHTOOL (since Linux 6.16-rc1)
> > > +----------------------------------
> > > +
> > > +Supports only command `ETHTOOL_GET_TS_INFO`, which may be used to
> > > +query supported `SOF_TIMESTAMPING_*` flags. The
> > > +`SOF_TIMESTAMPING_OPT_*` flags are always available as applicable.
> > > +
> > > +Example:
> > > +
> > > +.. code-block::
> > > +
> > > + #include <linux/ethtool.h>
> > > + #include <linux/sockios.h>
> > > + #include <net/if.h>
> > > + #include <sys/socket.h>
> > > + #include <sys/ioctl.h>
> > > +
> > > + ...
> > > +
> > > + struct ifreq ifr = {};
> > > + struct ethtool_ts_info cmd = {};
> > > + int sk;
> > > +
> > > + snprintf(ifr.ifr_name, sizeof(ifr.ifr_name), "hci0");
> > > + ifr.ifr_data = (void *)&cmd;
> > > + cmd.cmd = ETHTOOL_GET_TS_INFO;
> > > +
> > > + sk = socket(PF_BLUETOOTH, SOCK_SEQPACKET, BTPROTO_ISO);
> > > + if (sk < 0)
> > > + goto error;
> > > + if (ioctl(sk, SIOCETHTOOL, &ifr))
> > > + goto error;
> > > +
> > > + sof_available = cmd.so_timestamping;
> > > +
> > > +RESOURCES
> > > +=========
> > > +
> > > +http://www.bluez.org
> > > +
> > > +REPORTING BUGS
> > > +==============
> > > +
> > > +linux-bluetooth@vger.kernel.org
> > > +
> > > +SEE ALSO
> > > +========
> > > +
> > > +socket(7), isotest(1)
> > > --
> > > 2.50.0
> > >
> >
> > Have a look if the above makes sense, I didn't include BT_PKT_SEQNUM
> > since that is sort of new, but if you feel that should be included
> > from the start I just need an example to go with it.
>
> Looks right to me. BT_PKT_SEQNUM if added would be like
Thanks for looking into it.
> BT_PKT_SEQNUM
> -------------
>
> Enable reporting packet ISO sequence number via `BT_SCM_PKT_SEQNUM`
> CMSG on received packets. Possible values:
>
> .. csv-table::
> :header: "Value", "Description"
> :widths: auto
>
> **0**, Disable (default)
> **1**, Enable
>
>
> :BT_SCM_PKT_SEQNUM:
>
> Level ``SOL_BLUETOOTH`` CMSG with data::
>
> uint16_t pkt_seqnum;
>
> The values are equal to the "Packet_Sequence_Number" defined in
> Core Specification v6.1, 5.4.5. HCI ISO Data packets:
>
> https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-61/out/en/host-controller-interface/host-controller-interface-functional-specification.html#UUID-9b5fb085-278b-5084-ac33-bee2839abe6b
>
> Example (Enable sequence numbers):
>
> .. code-block::
>
> uint32_t opt = 1;
> if (setsockopt(fd, SOL_BLUETOOTH, BT_PKT_SEQNUM, &opt, sizeof(opt)) < 0)
> goto error;
>
> Example (Read packet and its sequence number):
>
> .. code-block::
>
> char data_buf[256];
> uint16_t seqnum;
> union {
> char buf[CMSG_SPACE(sizeof(uint16_t))];
> struct cmsghdr align;
> } control;
> struct iovec data = {
> .iov_base = data_buf,
> .iov_len = sizeof(data_buf),
> };
> struct msghdr msg = {
> .msg_iov = &data,
> .msg_iovlen = 1,
> .msg_control = control.buf,
> .msg_controllen = sizeof(control.buf),
> };
> struct scm_timestamping tss;
>
> res = recvmsg(fd, &msg, 0);
> if (res < 0)
> goto error;
>
> for (cmsg = CMSG_FIRSTHDR(&msg); cmsg; cmsg = CMSG_NXTHDR(&msg, cmsg)) {
> if (cmsg->cmsg_level == SOL_BLUETOOTH && cmsg->cmsg_type == BT_PKT_SEQNUM)
> memcpy(&seqnum, CMSG_DATA(cmsg), sizeof(seqnum));
> }
I think I will wait until it has made it into Linus tree in the next
merge window, so we avoid having to remove it later if there is
something that blocks it for some reason since we already experienced
something like that before.
> --
> Pauli Virtanen
--
Luiz Augusto von Dentz
^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2025-07-15 20:00 UTC | newest]
Thread overview: 5+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2025-07-15 18:07 [PATCH BlueZ v1] doc: Add initial ISO(7) documentation Luiz Augusto von Dentz
2025-07-15 18:17 ` Luiz Augusto von Dentz
2025-07-15 19:49 ` Pauli Virtanen
2025-07-15 19:59 ` Luiz Augusto von Dentz
2025-07-15 19:48 ` [BlueZ,v1] " bluez.test.bot
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox