* [PATCH BlueZ v1 1/6] doc/btmon: Split Advertising and Scanning into btmon-advertising.rst
@ 2026-03-12 17:15 Luiz Augusto von Dentz
2026-03-12 17:15 ` [PATCH BlueZ v1 2/6] doc/btmon: Split LE Audio Protocol Flow into btmon-le-audio.rst Luiz Augusto von Dentz
` (5 more replies)
0 siblings, 6 replies; 7+ messages in thread
From: Luiz Augusto von Dentz @ 2026-03-12 17:15 UTC (permalink / raw)
To: linux-bluetooth
From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
Move the ADVERTISING AND SCANNING section into a standalone file and
replace it with an RST include directive. This allows the
btsnoop-analyzer to load only the relevant documentation for
advertising/scanning focus-area analysis instead of the full btmon.rst.
---
doc/btmon-advertising.rst | 159 ++++++++++++++++++++++++++++++++++++++
doc/btmon.rst | 154 +-----------------------------------
2 files changed, 160 insertions(+), 153 deletions(-)
create mode 100644 doc/btmon-advertising.rst
diff --git a/doc/btmon-advertising.rst b/doc/btmon-advertising.rst
new file mode 100644
index 000000000000..46350f002b5f
--- /dev/null
+++ b/doc/btmon-advertising.rst
@@ -0,0 +1,159 @@
+===================================
+btmon: Advertising and Scanning
+===================================
+
+.. This file is included by btmon.rst.
+
+ADVERTISING AND SCANNING
+==========================
+
+btmon decodes advertising data structures automatically. Advertising
+and scan response data appears in HCI LE advertising report events
+and in advertising command parameters.
+
+Advertising Reports
+--------------------
+
+When the controller reports received advertisements::
+
+ > HCI Event: LE Meta Event (0x3e) plen 43 #120 [hci0] 0.500003
+ LE Extended Advertising Report (0x0d)
+ Event type: 0x0013
+ Props: 0x0013
+ Connectable
+ Scannable
+ Complete
+ Address type: Random (0x01)
+ Address: 00:11:22:33:44:55
+ Primary PHY: LE 1M
+ Secondary PHY: LE 2M
+ SID: 0x01
+ TX power: 0 dBm
+ RSSI: -55 dBm (0xc9)
+ Data length: 18
+
+The advertising data (AD) structures within the report are decoded
+as typed fields:
+
+**Common AD types btmon decodes**:
+
+.. list-table::
+ :header-rows: 1
+ :widths: 10 30 60
+
+ * - AD Type
+ - Name
+ - Example in btmon output
+ * - 0x01
+ - Flags
+ - ``Flags: 0x06`` with decoded bits (LE General Discoverable,
+ BR/EDR Not Supported)
+ * - 0x02/0x03
+ - Incomplete/Complete 16-bit UUIDs
+ - ``16-bit Service UUIDs (complete): 2 entries``
+ followed by UUID list
+ * - 0x06/0x07
+ - Incomplete/Complete 128-bit UUIDs
+ - ``128-bit Service UUIDs (complete): 1 entry``
+ * - 0x08/0x09
+ - Shortened/Complete Local Name
+ - ``Name (complete): MyDevice``
+ * - 0x0a
+ - TX Power Level
+ - ``TX power: 4 dBm``
+ * - 0x16
+ - Service Data (16-bit UUID)
+ - ``Service Data (UUID 0x184e): ...`` with protocol-specific
+ decoding
+ * - 0xff
+ - Manufacturer Specific Data
+ - ``Company: Apple, Inc. (76)`` followed by hex data
+
+**Typical advertising report**::
+
+ > HCI Event: LE Meta Event (0x3e) plen 38 #120 [hci0] 0.500003
+ LE Extended Advertising Report (0x0d)
+ Address: 00:11:22:33:44:55
+ RSSI: -62 dBm (0xc2)
+ Flags: 0x06
+ LE General Discoverable Mode
+ BR/EDR Not Supported
+ Name (complete): LE-Audio-Left
+ 16-bit Service UUIDs (complete): 3 entries
+ Published Audio Capabilities (0x1850)
+ Audio Stream Control (0x184e)
+ Common Audio (0x1853)
+ Service Data (UUID 0x1852): 01a2b3
+ Appearance: Earbud (0x0941)
+
+Extended Advertising
+---------------------
+
+Modern controllers use extended advertising commands and events.
+The setup sequence in btmon::
+
+ < HCI Command: LE Set Extended Adv Parameters (0x08|0x0036) plen 25 #50 [hci0] 0.100003
+ Handle: 0x01
+ Properties: 0x0000
+ Min advertising interval: 160.000 msec (0x0100)
+ Max advertising interval: 160.000 msec (0x0100)
+ Channel map: 37, 38, 39 (0x07)
+ Own address type: Random (0x01)
+ Peer address type: Public (0x00)
+ PHY: LE 1M, LE 2M
+ SID: 0x01
+ TX power: 7 dBm
+
+ < HCI Command: LE Set Extended Adv Data (0x08|0x0037) plen 35 #52 [hci0] 0.101003
+ Handle: 0x01
+ Operation: Complete extended advertising data (0x01)
+ Fragment preference: No fragmentation (0x01)
+
+Periodic Advertising (LE Audio)
+--------------------------------
+
+LE Audio broadcast sources use periodic advertising to transmit
+BASE announcements containing codec configuration::
+
+ > HCI Event: LE Meta Event (0x3e) plen 80 #200 [hci0] 0.500003
+ LE Periodic Advertising Report (0x0f)
+ Sync handle: 0x0001
+ TX power: 0 dBm
+ RSSI: -45 dBm
+ CTE Type: No CTE (0xff)
+ Data status: Complete (0x00)
+ Data length: 60
+ Service Data: Basic Audio Announcement (0x1851)
+ Presentation Delay: 40000 us
+ Number of Subgroups: 1
+ Codec: LC3 (0x06)
+ Sampling Frequency: 48000 Hz
+ Frame Duration: 10 ms
+ Frame Length: 120
+
+Automating Advertising Analysis
+---------------------------------
+
+**Find all advertising reports** (devices seen)::
+
+ grep -n "Advertising Report\|Address:.*RSSI:" output.txt
+
+**Extract device names**::
+
+ grep -n "Name (complete):\|Name (short):" output.txt
+
+**Find LE Audio devices** (by service UUIDs in advertising)::
+
+ grep -n "Audio Stream Control\|Published Audio Capabilities\|Common Audio\|Basic Audio Announcement\|Broadcast Audio" output.txt
+
+**Track advertising setup** (local device configuring advertising)::
+
+ grep -n "Set Extended Adv\|Set Advertising\|Set Scan Response\|Adv Enable" output.txt
+
+**Find periodic advertising** (broadcast audio)::
+
+ grep -n "Periodic Advertising\|PA Sync\|PA Report\|Basic Audio Announcement\|Broadcast.*Announcement" output.txt
+
+**Identify devices by appearance**::
+
+ grep -n "Appearance:" output.txt
diff --git a/doc/btmon.rst b/doc/btmon.rst
index 2299c13ca16c..974e8e1ef002 100644
--- a/doc/btmon.rst
+++ b/doc/btmon.rst
@@ -2402,159 +2402,7 @@ Errors often cascade across layers. Common patterns:
4. L2CAP ``Connection refused - security block`` → triggers SMP
pairing
-ADVERTISING AND SCANNING
-==========================
-
-btmon decodes advertising data structures automatically. Advertising
-and scan response data appears in HCI LE advertising report events
-and in advertising command parameters.
-
-Advertising Reports
---------------------
-
-When the controller reports received advertisements::
-
- > HCI Event: LE Meta Event (0x3e) plen 43 #120 [hci0] 0.500003
- LE Extended Advertising Report (0x0d)
- Event type: 0x0013
- Props: 0x0013
- Connectable
- Scannable
- Complete
- Address type: Random (0x01)
- Address: 00:11:22:33:44:55
- Primary PHY: LE 1M
- Secondary PHY: LE 2M
- SID: 0x01
- TX power: 0 dBm
- RSSI: -55 dBm (0xc9)
- Data length: 18
-
-The advertising data (AD) structures within the report are decoded
-as typed fields:
-
-**Common AD types btmon decodes**:
-
-.. list-table::
- :header-rows: 1
- :widths: 10 30 60
-
- * - AD Type
- - Name
- - Example in btmon output
- * - 0x01
- - Flags
- - ``Flags: 0x06`` with decoded bits (LE General Discoverable,
- BR/EDR Not Supported)
- * - 0x02/0x03
- - Incomplete/Complete 16-bit UUIDs
- - ``16-bit Service UUIDs (complete): 2 entries``
- followed by UUID list
- * - 0x06/0x07
- - Incomplete/Complete 128-bit UUIDs
- - ``128-bit Service UUIDs (complete): 1 entry``
- * - 0x08/0x09
- - Shortened/Complete Local Name
- - ``Name (complete): MyDevice``
- * - 0x0a
- - TX Power Level
- - ``TX power: 4 dBm``
- * - 0x16
- - Service Data (16-bit UUID)
- - ``Service Data (UUID 0x184e): ...`` with protocol-specific
- decoding
- * - 0xff
- - Manufacturer Specific Data
- - ``Company: Apple, Inc. (76)`` followed by hex data
-
-**Typical advertising report**::
-
- > HCI Event: LE Meta Event (0x3e) plen 38 #120 [hci0] 0.500003
- LE Extended Advertising Report (0x0d)
- Address: 00:11:22:33:44:55
- RSSI: -62 dBm (0xc2)
- Flags: 0x06
- LE General Discoverable Mode
- BR/EDR Not Supported
- Name (complete): LE-Audio-Left
- 16-bit Service UUIDs (complete): 3 entries
- Published Audio Capabilities (0x1850)
- Audio Stream Control (0x184e)
- Common Audio (0x1853)
- Service Data (UUID 0x1852): 01a2b3
- Appearance: Earbud (0x0941)
-
-Extended Advertising
----------------------
-
-Modern controllers use extended advertising commands and events.
-The setup sequence in btmon::
-
- < HCI Command: LE Set Extended Adv Parameters (0x08|0x0036) plen 25 #50 [hci0] 0.100003
- Handle: 0x01
- Properties: 0x0000
- Min advertising interval: 160.000 msec (0x0100)
- Max advertising interval: 160.000 msec (0x0100)
- Channel map: 37, 38, 39 (0x07)
- Own address type: Random (0x01)
- Peer address type: Public (0x00)
- PHY: LE 1M, LE 2M
- SID: 0x01
- TX power: 7 dBm
-
- < HCI Command: LE Set Extended Adv Data (0x08|0x0037) plen 35 #52 [hci0] 0.101003
- Handle: 0x01
- Operation: Complete extended advertising data (0x01)
- Fragment preference: No fragmentation (0x01)
-
-Periodic Advertising (LE Audio)
---------------------------------
-
-LE Audio broadcast sources use periodic advertising to transmit
-BASE announcements containing codec configuration::
-
- > HCI Event: LE Meta Event (0x3e) plen 80 #200 [hci0] 0.500003
- LE Periodic Advertising Report (0x0f)
- Sync handle: 0x0001
- TX power: 0 dBm
- RSSI: -45 dBm
- CTE Type: No CTE (0xff)
- Data status: Complete (0x00)
- Data length: 60
- Service Data: Basic Audio Announcement (0x1851)
- Presentation Delay: 40000 us
- Number of Subgroups: 1
- Codec: LC3 (0x06)
- Sampling Frequency: 48000 Hz
- Frame Duration: 10 ms
- Frame Length: 120
-
-Automating Advertising Analysis
----------------------------------
-
-**Find all advertising reports** (devices seen)::
-
- grep -n "Advertising Report\|Address:.*RSSI:" output.txt
-
-**Extract device names**::
-
- grep -n "Name (complete):\|Name (short):" output.txt
-
-**Find LE Audio devices** (by service UUIDs in advertising)::
-
- grep -n "Audio Stream Control\|Published Audio Capabilities\|Common Audio\|Basic Audio Announcement\|Broadcast Audio" output.txt
-
-**Track advertising setup** (local device configuring advertising)::
-
- grep -n "Set Extended Adv\|Set Advertising\|Set Scan Response\|Adv Enable" output.txt
-
-**Find periodic advertising** (broadcast audio)::
-
- grep -n "Periodic Advertising\|PA Sync\|PA Report\|Basic Audio Announcement\|Broadcast.*Announcement" output.txt
-
-**Identify devices by appearance**::
-
- grep -n "Appearance:" output.txt
+.. include:: btmon-advertising.rst
EXAMPLES
========
--
2.53.0
^ permalink raw reply related [flat|nested] 7+ messages in thread
* [PATCH BlueZ v1 2/6] doc/btmon: Split LE Audio Protocol Flow into btmon-le-audio.rst
2026-03-12 17:15 [PATCH BlueZ v1 1/6] doc/btmon: Split Advertising and Scanning into btmon-advertising.rst Luiz Augusto von Dentz
@ 2026-03-12 17:15 ` Luiz Augusto von Dentz
2026-03-12 17:15 ` [PATCH BlueZ v1 3/6] doc/btmon: Split L2CAP Channel Tracking into btmon-l2cap.rst Luiz Augusto von Dentz
` (4 subsequent siblings)
5 siblings, 0 replies; 7+ messages in thread
From: Luiz Augusto von Dentz @ 2026-03-12 17:15 UTC (permalink / raw)
To: linux-bluetooth
From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
Move the LE AUDIO PROTOCOL FLOW section (including CIS unicast,
BIS broadcast, and BIG sync flows) into a standalone file and
replace it with an RST include directive. This is the largest
split section (660 lines) and was being truncated away in
context-limited analysis.
---
doc/btmon-le-audio.rst | 659 +++++++++++++++++++++++++++++++++++++++++
doc/btmon.rst | 654 +---------------------------------------
2 files changed, 660 insertions(+), 653 deletions(-)
create mode 100644 doc/btmon-le-audio.rst
diff --git a/doc/btmon-le-audio.rst b/doc/btmon-le-audio.rst
new file mode 100644
index 000000000000..62800520e1bf
--- /dev/null
+++ b/doc/btmon-le-audio.rst
@@ -0,0 +1,659 @@
+=================================
+btmon: LE Audio Protocol Flow
+=================================
+
+.. This file is included by btmon.rst.
+
+LE AUDIO PROTOCOL FLOW
+=======================
+
+LE Audio uses a multi-layer protocol stack visible in btmon traces.
+The setup sequence involves ATT operations on specific GATT
+characteristics (PACS, ASCS) followed by HCI-level CIS/BIG
+management. btmon fully decodes all layers.
+
+PACS: Published Audio Capabilities
+------------------------------------
+
+Before audio streaming begins, devices exchange codec capabilities
+via the Published Audio Capabilities Service (PACS). The client reads
+PACS characteristics to learn what the remote device supports.
+
+**Sink PAC read** (remote device's receive capabilities)::
+
+ < ACL Data TX: Handle 2048 flags 0x00 dlen 7 #550 [hci0] 0.824003
+ ATT: Read Request (0x0a) len 2
+ Handle: 0x0075
+
+ > ACL Data RX: Handle 2048 flags 0x02 dlen 30 #552 [hci0] 0.886556
+ ATT: Read Response (0x0b) len 25
+ Handle: 0x0075
+ Number of PAC(s): 1
+ Codec: LC3 (0x06)
+ Codec Specific Capabilities: #0
+ Sampling Frequency: 8000 Hz 16000 Hz 24000 Hz 32000 Hz 48000 Hz
+ Frame Duration: 7.5 ms 10 ms
+ Audio Channel Counts: 1
+ Frame Length: 26 - 240
+
+The PAC record shows codec capabilities using LTV (Length-Type-Value)
+encoding. Key fields:
+
+- **Codec** -- ``LC3 (0x06)`` is the mandatory LE Audio codec
+- **Sampling Frequency** -- Supported sample rates (bitmask)
+- **Frame Duration** -- Supported frame durations (7.5 ms and/or 10 ms)
+- **Audio Channel Counts** -- Supported channel counts
+- **Frame Length** -- Min and max octets per codec frame
+
+**Audio Locations** (channel assignment)::
+
+ > ACL Data RX: Handle 2048 flags 0x02 dlen 9 #554 [hci0] 0.948003
+ ATT: Read Response (0x0b) len 4
+ Handle: 0x0077
+ Location: Front Left
+
+**Available Audio Contexts** (current use cases)::
+
+ > ACL Data RX: Handle 2048 flags 0x02 dlen 9 #558 [hci0] 1.012556
+ ATT: Read Response (0x0b) len 4
+ Handle: 0x007b
+ Sink Context: Media Conversational
+ Source Context: Unspecified
+
+ASCS: Audio Stream Control
+----------------------------
+
+The Audio Stream Control Service (ASCS) manages the ASE (Audio Stream
+Endpoint) state machine. Each ASE transitions through a defined set
+of states as streaming is set up and torn down.
+
+**ASE State Machine**::
+
+ Idle ──► Codec Configured ──► QoS Configured ──► Enabling ──► Streaming
+ │
+ Idle ◄── Releasing ◄──────── Disabling ◄─────────────────────────┘
+
+**ASE Status notification** (state change)::
+
+ > ACL Data RX: Handle 2048 flags 0x02 dlen 20 #580 [hci0] 1.456003
+ ATT: Handle Value Notification (0x1b) len 15
+ Handle: 0x0088
+ ASE ID: 0x01
+ State: Codec Configured (0x01)
+ Framing: Unframed PDUs supported (0x00)
+ PHY: 0x02
+ LE 2M PHY (0x02)
+ RTN: 2
+ Max Transport Latency: 10
+ Presentation Delay Min: 20000 us
+ Presentation Delay Max: 40000 us
+ Preferred Presentation Delay Min: 20000 us
+ Preferred Presentation Delay Max: 40000 us
+ Codec: LC3 (0x06)
+ Sampling Frequency: 48000 Hz
+ Frame Duration: 10 ms
+ Audio Channel Allocation: Front Left
+ Frame Length: 120
+
+**ASE Control Point operations** drive state transitions. The client
+writes to the ASE Control Point characteristic to issue commands::
+
+ < ACL Data TX: Handle 2048 flags 0x00 dlen 25 #582 [hci0] 1.518003
+ ATT: Write Request (0x12) len 20
+ Handle: 0x008b
+ ASE Control Point: Config Codec (0x01)
+ ASE ID: 0x01
+ Target Latency: Low Latency (0x01)
+ PHY: LE 2M PHY
+ Codec: LC3 (0x06)
+ Sampling Frequency: 48000 Hz
+ Frame Duration: 10 ms
+ Audio Channel Allocation: Front Left
+ Frame Length: 120
+
+ASE Control Point commands:
+
+.. list-table::
+ :header-rows: 1
+ :widths: 10 25 65
+
+ * - Opcode
+ - Command
+ - Purpose
+ * - 0x01
+ - Config Codec
+ - Select codec and parameters (Idle → Codec Configured)
+ * - 0x02
+ - Config QoS
+ - Set CIG/CIS IDs and QoS params (Codec Configured → QoS Configured)
+ * - 0x03
+ - Enable
+ - Start ASE with metadata (QoS Configured → Enabling)
+ * - 0x04
+ - Receiver Start Ready
+ - Signal receiver readiness (Enabling → Streaming, server-side)
+ * - 0x05
+ - Disable
+ - Stop streaming (Streaming → Disabling)
+ * - 0x06
+ - Receiver Stop Ready
+ - Signal receiver stopped
+ * - 0x07
+ - Update Metadata
+ - Change metadata during streaming
+ * - 0x08
+ - Release
+ - Tear down ASE (any → Releasing → Idle)
+
+CIS Setup and Teardown
+------------------------
+
+After ASE QoS Configuration, the host creates Connected Isochronous
+Streams (CIS) at the HCI level.
+
+**CIG Parameters** (configure the CIS group)::
+
+ < HCI Command: LE Set CIG Parameters (0x08|0x0062) plen 26 #590 [hci0] 1.624003
+ CIG ID: 0x00
+ Central to Peripheral SDU Interval: 10000 us
+ Peripheral to Central SDU Interval: 10000 us
+ SCA: 0x00
+ Packing: Sequential (0x00)
+ Framing: Unframed (0x00)
+ Central to Peripheral Max Latency: 10 ms
+ Peripheral to Central Max Latency: 10 ms
+ Number of CIS: 1
+ CIS ID: 0x00
+ Central to Peripheral Max SDU: 120
+ Peripheral to Central Max SDU: 0
+ Central to Peripheral PHY: LE 2M PHY
+ Peripheral to Central PHY: LE 2M PHY
+ Central to Peripheral RTN: 2
+ Peripheral to Central RTN: 2
+
+ > HCI Event: Command Complete (0x0e) plen 8 #592 [hci0] 1.624556
+ LE Set CIG Parameters (0x08|0x0062) ncmd 1
+ Status: Success (0x00)
+ CIG ID: 0x00
+ Number of Handles: 1
+ Connection Handle: 2064
+
+**CIS Creation**::
+
+ < HCI Command: LE Create CIS (0x08|0x0064) plen 9 #594 [hci0] 1.688003
+ Number of CIS: 1
+ CIS Handle: 2064
+ ACL Handle: 2048
+
+ > HCI Event: LE Meta Event (0x3e) plen 29 #596 [hci0] 1.756556
+ LE CIS Established (0x19)
+ Status: Success (0x00)
+ Connection Handle: 2064
+ CIG Sync Delay: 5000 us
+ CIS Sync Delay: 5000 us
+ Central to Peripheral Latency: 10000 us
+ Peripheral to Central Latency: 10000 us
+ Central to Peripheral PHY: LE 2M PHY
+ Peripheral to Central PHY: LE 2M PHY
+ NSE: 3
+ Central to Peripheral BN: 1
+ Peripheral to Central BN: 0
+ Central to Peripheral FT: 2
+ Peripheral to Central FT: 2
+ Max PDU C to P: 120
+ Max PDU P to C: 0
+ ISO Interval: 10.00 msec (0x0008)
+
+Note that the CIS Handle (2064) is different from the ACL Handle
+(2048). CIS data packets use the CIS handle.
+
+**ISO Data Path Setup**::
+
+ < HCI Command: LE Setup ISO Data Path (0x08|0x006e) plen 13 #598 [hci0] 1.820003
+ Handle: 2064
+ Data Path Direction: Input (Host to Controller) (0x00)
+ Data Path ID: HCI (0x00)
+ Coding Format: LC3 (0x06)
+ Company ID: 0x0000
+ Vendor Codec ID: 0x0000
+ Controller Delay: 0 us
+
+After this, ISO data packets flow on the CIS handle::
+
+ < ISO Data TS: Handle 2064 flags 0x02 dlen 124 #600 [hci0] 1.884003
+
+Broadcast Audio (BIG)
+----------------------
+
+Broadcast Isochronous Streams use BIG (Broadcast Isochronous Group)
+instead of CIS. The setup involves periodic advertising with BASE
+(Broadcast Audio Source Endpoint) announcements.
+
+**BASE announcement** (in periodic advertising data)::
+
+ > HCI Event: LE Meta Event (0x3e) plen 80 #200 [hci0] 0.500003
+ LE Periodic Advertising Report (0x0f)
+ ...
+ Service Data: Basic Audio Announcement (0x1851)
+ Presentation Delay: 40000 us
+ Number of Subgroups: 1
+ Number of BIS: 2
+ Codec: LC3 (0x06)
+ Sampling Frequency: 48000 Hz
+ Frame Duration: 10 ms
+ Frame Length: 120
+ BIS #1
+ Audio Channel Allocation: Front Left
+ BIS #2
+ Audio Channel Allocation: Front Right
+
+**BIG creation** (source side)::
+
+ < HCI Command: LE Create BIG (0x08|0x0068) plen 31 #210 [hci0] 0.600003
+ BIG Handle: 0x00
+ Advertising Handle: 0x01
+ Number of BIS: 2
+ SDU Interval: 10000 us
+ Max SDU: 120
+ Max Latency: 10 ms
+ RTN: 2
+ PHY: LE 2M PHY
+ Packing: Sequential (0x00)
+ Framing: Unframed (0x00)
+ Encryption: Unencrypted (0x00)
+
+**BIG sync** (receiver side)::
+
+ < HCI Command: LE BIG Create Sync (0x08|0x006b) plen 15 #220 [hci0] 0.700003
+ BIG Handle: 0x00
+ Sync Handle: 0x0001
+ Encryption: Unencrypted (0x00)
+ Number of BIS: 2
+ BIS: 0x01
+ BIS: 0x02
+
+BIG Sync Receiver Flow
+~~~~~~~~~~~~~~~~~~~~~~
+
+A receiver must complete a specific sequence of steps before it can
+receive broadcast audio. The critical prerequisite chain is:
+
+1. **Synchronize to periodic advertising** -- the receiver must first
+ discover and sync to the broadcaster's periodic advertising train.
+2. **Receive PA Reports with BASE** -- the periodic advertising data
+ contains the BASE (Broadcast Audio Source Endpoint) structure
+ describing the broadcast's codec configuration.
+3. **Receive BIG Info Advertising Report** -- this event tells the
+ receiver that a BIG exists on the periodic advertising train and
+ provides its parameters (number of BIS, encryption, SDU interval,
+ etc.). **This is the critical gate**: without receiving BIG Info,
+ the receiver cannot issue ``LE BIG Create Sync``.
+4. **Issue LE BIG Create Sync** -- using the sync handle from step 1
+ and parameters from step 3.
+5. **Receive BIG Sync Established** -- the controller confirms sync
+ with BIS connection handles.
+6. **Setup ISO Data Path** -- configure the data path for each BIS.
+7. **ISO Data flows** -- broadcast audio packets arrive.
+
+If any step fails or is missing, the subsequent steps cannot proceed.
+The most common failure pattern is that **BIG Info is never received**
+(e.g., the periodic advertising data does not contain a BIG, or PA
+sync was lost before BIG Info arrived), which means ``LE BIG Create
+Sync`` is never sent.
+
+Without PAST (Direct PA Sync)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When the receiver scans for and syncs to periodic advertising
+directly (without assistance from a Broadcast Assistant):
+
+**Step 1 -- Create PA sync**::
+
+ < HCI Command: LE Periodic Advertising Create Sync (0x08|0x0044) plen 14 #100 [hci0] 0.100003
+ Options: 0x0000
+ SID: 0x01
+ Adv Address Type: Public (0x00)
+ Adv Address: XX:XX:XX:XX:XX:XX
+ Skip: 0x0000
+ Sync Timeout: 2000 msec (0x00c8)
+ Sync CTE Type: 0x0000
+
+**Step 2 -- PA Sync Established** (sync handle assigned)::
+
+ > HCI Event: LE Meta Event (0x3e) plen 16 #105 [hci0] 0.150003
+ LE Periodic Advertising Sync Established (0x0e)
+ Status: Success (0x00)
+ Sync Handle: 0x0001
+ Advertising SID: 0x01
+ Advertiser Address Type: Public (0x00)
+ Advertiser Address: XX:XX:XX:XX:XX:XX
+ Advertiser PHY: LE 2M PHY (0x02)
+ Periodic Advertising Interval: 10.000 msec (0x0008)
+ Advertiser Clock Accuracy: 0x05
+
+**Step 3 -- PA Reports** (contain BASE data)::
+
+ > HCI Event: LE Meta Event (0x3e) plen 80 #110 [hci0] 0.200003
+ LE Periodic Advertising Report (0x0f)
+ Sync Handle: 0x0001
+ ...
+ Service Data: Basic Audio Announcement (0x1851)
+
+**Step 4 -- BIG Info Advertising Report** (critical gate)::
+
+ > HCI Event: LE Meta Event (0x3e) plen 24 #120 [hci0] 0.300003
+ LE BIG Info Advertising Report (0x22)
+ Sync Handle: 0x0001
+ Number BIS: 2
+ NSE: 4
+ ISO Interval: 10.000 msec (0x0008)
+ BN: 2
+ PTO: 1
+ IRC: 2
+ Maximum PDU: 120
+ SDU Interval: 10000 us
+ Maximum SDU: 120
+ PHY: LE 2M PHY (0x02)
+ Framing: Unframed (0x00)
+ Encryption: 0x00
+
+This event is generated by the controller each time it receives a
+periodic advertising packet that contains BIG Info. It provides all
+parameters the receiver needs to decide whether to sync to the BIG.
+Key fields:
+
+- ``Number BIS`` -- how many BIS streams are available.
+- ``SDU Interval`` and ``Maximum SDU`` -- audio frame timing and size.
+- ``Encryption`` -- whether a Broadcast Code is required (0x01) or
+ not (0x00). If encrypted, the receiver must supply the correct
+ Broadcast Code in ``LE BIG Create Sync``.
+- ``Sync Handle`` -- must match a currently active PA sync.
+
+**Step 5 -- BIG Create Sync** (using sync handle + BIG Info)::
+
+ < HCI Command: LE BIG Create Sync (0x08|0x006b) plen 15 #130 [hci0] 0.400003
+ BIG Handle: 0x00
+ BIG Sync Handle: 0x0001
+ Encryption: Unencrypted (0x00)
+ Broadcast Code: 00000000000000000000000000000000
+ Maximum Number Subevents: 0x00
+ Timeout: 2000 ms (0x00c8)
+ Number of BIS: 2
+ BIS: 0x01
+ BIS: 0x02
+
+**Step 6 -- BIG Sync Established**::
+
+ > HCI Event: LE Meta Event (0x3e) plen 20 #135 [hci0] 0.450003
+ LE BIG Sync Established (0x1d)
+ Status: Success (0x00)
+ BIG Handle: 0x00
+ Transport Latency: 10000 us
+ NSE: 4
+ BN: 2
+ PTO: 1
+ IRC: 2
+ Maximum PDU: 120
+ ISO Interval: 10.000 msec (0x0008)
+ Connection Handle: 0x0010
+ Connection Handle: 0x0011
+
+On success, the controller assigns BIS connection handles (0x0010,
+0x0011 above). A non-zero Status indicates failure -- common errors:
+
+- ``0x3e`` (Connection Failed to be Established) -- BIG parameters
+ do not match or the BIG is no longer present.
+- ``0x3f`` (Limit Reached) -- controller resources exhausted.
+
+**Step 7 -- Setup ISO Data Path** (for each BIS)::
+
+ < HCI Command: LE Setup ISO Data Path (0x08|0x006e) plen 13 #140 [hci0] 0.500003
+ Connection Handle: 0x0010
+ Data Path Direction: Output (Host to Controller) (0x01)
+ Data Path ID: HCI (0x00)
+
+ < HCI Command: LE Setup ISO Data Path (0x08|0x006e) plen 13 #145 [hci0] 0.550003
+ Connection Handle: 0x0011
+ Data Path Direction: Output (Host to Controller) (0x01)
+ Data Path ID: HCI (0x00)
+
+**Step 8 -- ISO Data flows** on BIS handles::
+
+ > ISO Data: Handle 0x0010 flags 0x02 dlen 124 #150 [hci0] 0.600003
+ > ISO Data: Handle 0x0011 flags 0x02 dlen 124 #151 [hci0] 0.600003
+
+With PAST (Periodic Advertising Sync Transfer)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When a Broadcast Assistant (e.g., a phone) helps a Scan Delegator
+(e.g., a hearing aid) sync to a broadcast, it can transfer the PA
+sync via PAST over an existing ACL connection. This avoids the
+delegator having to scan for and sync to the PA train itself.
+
+The BASS (Broadcast Audio Scan Service) protocol coordinates this:
+
+1. The assistant writes an **Add Source** operation to the delegator's
+ BASS control point with ``PA Sync`` set to ``0x01``
+ (Synchronize via PAST).
+2. The delegator prepares to receive the transfer by setting PAST
+ parameters.
+3. The assistant transfers its PA sync to the delegator.
+4. The delegator receives the PAST event with a sync handle.
+5. From here, the flow continues as in the non-PAST case (PA Reports
+ → BIG Info → BIG Create Sync → etc.).
+
+**BASS Add Source** (assistant writes to delegator, seen in ATT)::
+
+ < ACL Data TX: Handle 64 flags 0x00 dlen 27 #300 [hci0] 1.000003
+ ATT: Write Command (0x52) len 22
+ Handle: 0x0025
+ Data: 04...
+ Opcode: Add Source (0x04)
+ Advertiser Address Type: Public (0x00)
+ Advertiser Address: XX:XX:XX:XX:XX:XX
+ Advertising SID: 0x01
+ PA Sync: Synchronize to PA - PAST (0x01)
+ PA Interval: 0x0008
+ Number of Subgroups: 1
+ BIS Sync: 0x00000003
+ Metadata Length: 0
+
+PA Sync values in the Add Source operation:
+
+- ``0x00`` -- Do not synchronize to PA
+- ``0x01`` -- Synchronize to PA, PAST available
+- ``0x02`` -- Synchronize to PA, PAST not available (delegator
+ must scan and sync directly)
+
+**PAST Parameters** (delegator prepares to receive transfer)::
+
+ < HCI Command: LE Periodic Advertising Sync Transfer Parameters (0x08|0x005c) plen 8 #310 [hci0] 1.100003
+ Connection handle: 64
+ Mode: Enabled with report events enabled (0x02)
+ Skip: 0x00
+ Sync timeout: 2000 msec (0x00c8)
+ Sync CTE Type: 0x0000
+
+**PAST Transfer** (assistant sends its PA sync)::
+
+ < HCI Command: LE Periodic Advertising Sync Transfer (0x08|0x005a) plen 6 #320 [hci0] 1.200003
+ Connection handle: 64
+ Service data: 0x0001
+ Sync handle: 1
+
+**PAST Received** (delegator gets the sync handle)::
+
+ > HCI Event: LE Meta Event (0x3e) plen 19 #325 [hci0] 1.250003
+ LE Periodic Advertising Sync Transfer Received (0x18)
+ Status: Success (0x00)
+ Handle: 64
+ Connection handle: 64
+ Service data: 0x0001
+ Sync handle: 1
+ SID: 0x01
+ Address type: Public (0x00)
+ Address: XX:XX:XX:XX:XX:XX
+ PHY: LE 2M PHY (0x02)
+ Periodic advertising Interval: 10.000
+ Clock Accuracy: 0x05
+
+On success, the delegator now has a PA sync (``Sync handle: 1``) and
+will begin receiving PA Reports and BIG Info events, continuing from
+step 3 of the non-PAST flow above.
+
+.. note::
+
+ **Race condition**: The PAST Parameters command must be sent
+ **before** the assistant sends the PAST Transfer. In BlueZ, the
+ PA sync state in BASS is set after probing completes to avoid
+ the remote sending PAST before the kernel has enabled PAST
+ Parameters on the HCI level.
+
+BIG Sync Teardown
+^^^^^^^^^^^^^^^^^
+
+**Receiver-initiated teardown** -- the receiver terminates its BIG
+sync::
+
+ < HCI Command: LE BIG Terminate Sync (0x08|0x006c) plen 1 #500 [hci0] 5.000003
+ BIG Handle: 0x00
+
+ > HCI Event: Command Complete (0x0e) plen 5 #501 [hci0] 5.001003
+ LE BIG Terminate Sync (0x08|0x006c) ncmd 1
+ Status: Success (0x00)
+ BIG Handle: 0x00
+
+**Broadcaster-initiated teardown** -- the broadcaster terminates its
+BIG, and the receiver gets a BIG Sync Lost event::
+
+ > HCI Event: LE Meta Event (0x3e) plen 2 #510 [hci0] 6.000003
+ LE BIG Sync Lost (0x1e)
+ BIG Handle: 0x00
+ Reason: Connection Terminated By Local Host (0x16)
+
+The ``Reason`` field indicates why sync was lost:
+
+- ``0x08`` (Connection Timeout) -- BIG packets not received within
+ the sync timeout.
+- ``0x13`` (Remote User Terminated Connection) -- broadcaster stopped
+ the BIG intentionally.
+- ``0x16`` (Connection Terminated By Local Host) -- local controller
+ terminated.
+- ``0x3e`` (Connection Failed to be Established) -- could not
+ establish sync initially.
+
+**Source-side BIG termination** (broadcaster tears down)::
+
+ < HCI Command: LE Terminate BIG (0x08|0x006a) plen 2 #520 [hci0] 7.000003
+ BIG Handle: 0x00
+ Reason: Connection Terminated By Local Host (0x16)
+
+ > HCI Event: LE Meta Event (0x3e) plen 2 #521 [hci0] 7.001003
+ LE BIG Terminate (0x1c)
+ BIG Handle: 0x00
+ Reason: Connection Terminated By Local Host (0x16)
+
+BIG Sync Failure Diagnosis
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When analyzing a trace where BIG sync fails, check the following in
+order:
+
+1. **Is PA sync established?** -- Look for ``LE Periodic Advertising
+ Sync Established`` with ``Status: Success``. If missing, the
+ receiver never synced to the PA train.
+2. **Are PA Reports arriving?** -- Look for ``LE Periodic Advertising
+ Report`` events. If absent after PA sync, the PA train may have
+ been lost.
+3. **Is BIG Info received?** -- Look for ``LE BIG Info Advertising
+ Report``. **If this event never appears, the BIG does not exist
+ on this PA train**, or the broadcaster has not yet started it.
+ Without BIG Info, ``LE BIG Create Sync`` cannot be sent.
+4. **Is BIG Create Sync sent?** -- If BIG Info was received but
+ ``LE BIG Create Sync`` was never sent, the host-side logic failed
+ to act on the BIG Info (e.g., mismatched codec, encryption
+ mismatch, application-level issue).
+5. **Does BIG Sync Established succeed?** -- Check the ``Status``
+ field. A non-zero status means the controller could not sync to
+ the BIG.
+6. **Is ISO Data Path set up?** -- Look for ``LE Setup ISO Data Path``
+ for each BIS handle from BIG Sync Established.
+7. **Is ISO Data flowing?** -- Look for ``ISO Data`` packets on the
+ BIS handles.
+
+Automating LE Audio Analysis
+------------------------------
+
+**Identify LE Audio activity**::
+
+ grep -n "ASE Control Point\|ASE ID\|State:.*Codec Configured\|State:.*QoS Configured\|State:.*Enabling\|State:.*Streaming\|State:.*Releasing" output.txt
+
+**Track ASE state transitions** for a specific ASE::
+
+ grep -n "ASE ID:" output.txt
+
+Then examine the ``State:`` line following each ASE ID match.
+
+**Check codec configuration**::
+
+ grep -n "Codec: LC3\|Sampling Frequency:\|Frame Duration:\|Frame Length:\|Audio Channel" output.txt
+
+**Verify CIS establishment**::
+
+ grep -n "Set CIG Parameters\|Create CIS\|CIS Established\|Setup ISO Data Path" output.txt
+
+**Detect CIS failures** -- check the Status field after
+``CIS Established``::
+
+ grep -n "CIS Established" output.txt
+
+Then examine the following line for ``Status:``.
+
+**Detect broadcast audio**::
+
+ grep -n "Basic Audio Announcement\|Create BIG\|BIG Complete\|BIG Create Sync\|BIG Sync\|BIG Info\|BIG Terminate\|BIG Sync Lost" output.txt
+
+**Trace BIG Sync receiver flow** -- verify each prerequisite step::
+
+ grep -n "Periodic Advertising Create Sync\|Periodic Advertising Sync Established\|BIG Info Advertising Report\|BIG Create Sync\|BIG Sync Established\|BIG Sync Lost\|BIG Terminate" output.txt
+
+**Detect PAST-based sync** -- check for Periodic Advertising Sync
+Transfer::
+
+ grep -n "Sync Transfer Parameters\|Sync Transfer (0x08\|PAST Received\|PA Sync:.*PAST\|Add Source" output.txt
+
+**Check BIG Info arrival** -- the critical gate for BIG sync. If this
+is absent, the receiver has no BIG to sync to::
+
+ grep -n "BIG Info Advertising Report" output.txt
+
+**Full LE Audio diagnosis pattern**:
+
+*Unicast (CIS) flow:*
+
+1. Find PACS reads -- verify codec compatibility between devices
+2. Find ASE Control Point writes -- trace the Config Codec → Config
+ QoS → Enable sequence
+3. Find ASE state notifications -- verify each transition succeeds
+4. Find CIG Parameters and CIS creation -- verify HCI-level setup
+5. Find ``CIS Established`` -- check Status for success
+6. Find ``Setup ISO Data Path`` -- verify data path configuration
+7. Find ISO Data packets -- confirm audio is flowing
+8. On failure, check ASE Control Point notification responses for
+ error codes (Response Code and Response Reason fields)
+
+*Broadcast (BIG) receiver flow:*
+
+1. Find ``Periodic Advertising Create Sync`` or ``PAST Received`` --
+ how did PA sync start?
+2. Find ``Periodic Advertising Sync Established`` or
+ ``PAST Received`` with ``Status: Success`` -- is PA synced?
+3. Find ``Periodic Advertising Report`` with
+ ``Basic Audio Announcement`` -- is BASE data arriving?
+4. Find ``BIG Info Advertising Report`` -- **critical**: does the BIG
+ exist? If missing, the BIG cannot be synced.
+5. Find ``BIG Create Sync`` -- did the host request BIG sync?
+6. Find ``BIG Sync Established`` -- check ``Status`` for success.
+7. Find ``Setup ISO Data Path`` for each BIS handle.
+8. Find ``ISO Data`` on BIS handles -- confirm audio is flowing.
+9. On failure, check for ``BIG Sync Lost`` and examine ``Reason``.
diff --git a/doc/btmon.rst b/doc/btmon.rst
index 974e8e1ef002..9e33c46ae8db 100644
--- a/doc/btmon.rst
+++ b/doc/btmon.rst
@@ -1567,659 +1567,7 @@ channel, note the Source CID and Destination CID from the Connection
Request/Response pair. Then search for those CIDs in subsequent data
frames.
-LE AUDIO PROTOCOL FLOW
-=======================
-
-LE Audio uses a multi-layer protocol stack visible in btmon traces.
-The setup sequence involves ATT operations on specific GATT
-characteristics (PACS, ASCS) followed by HCI-level CIS/BIG
-management. btmon fully decodes all layers.
-
-PACS: Published Audio Capabilities
-------------------------------------
-
-Before audio streaming begins, devices exchange codec capabilities
-via the Published Audio Capabilities Service (PACS). The client reads
-PACS characteristics to learn what the remote device supports.
-
-**Sink PAC read** (remote device's receive capabilities)::
-
- < ACL Data TX: Handle 2048 flags 0x00 dlen 7 #550 [hci0] 0.824003
- ATT: Read Request (0x0a) len 2
- Handle: 0x0075
-
- > ACL Data RX: Handle 2048 flags 0x02 dlen 30 #552 [hci0] 0.886556
- ATT: Read Response (0x0b) len 25
- Handle: 0x0075
- Number of PAC(s): 1
- Codec: LC3 (0x06)
- Codec Specific Capabilities: #0
- Sampling Frequency: 8000 Hz 16000 Hz 24000 Hz 32000 Hz 48000 Hz
- Frame Duration: 7.5 ms 10 ms
- Audio Channel Counts: 1
- Frame Length: 26 - 240
-
-The PAC record shows codec capabilities using LTV (Length-Type-Value)
-encoding. Key fields:
-
-- **Codec** -- ``LC3 (0x06)`` is the mandatory LE Audio codec
-- **Sampling Frequency** -- Supported sample rates (bitmask)
-- **Frame Duration** -- Supported frame durations (7.5 ms and/or 10 ms)
-- **Audio Channel Counts** -- Supported channel counts
-- **Frame Length** -- Min and max octets per codec frame
-
-**Audio Locations** (channel assignment)::
-
- > ACL Data RX: Handle 2048 flags 0x02 dlen 9 #554 [hci0] 0.948003
- ATT: Read Response (0x0b) len 4
- Handle: 0x0077
- Location: Front Left
-
-**Available Audio Contexts** (current use cases)::
-
- > ACL Data RX: Handle 2048 flags 0x02 dlen 9 #558 [hci0] 1.012556
- ATT: Read Response (0x0b) len 4
- Handle: 0x007b
- Sink Context: Media Conversational
- Source Context: Unspecified
-
-ASCS: Audio Stream Control
-----------------------------
-
-The Audio Stream Control Service (ASCS) manages the ASE (Audio Stream
-Endpoint) state machine. Each ASE transitions through a defined set
-of states as streaming is set up and torn down.
-
-**ASE State Machine**::
-
- Idle ──► Codec Configured ──► QoS Configured ──► Enabling ──► Streaming
- │
- Idle ◄── Releasing ◄──────── Disabling ◄─────────────────────────┘
-
-**ASE Status notification** (state change)::
-
- > ACL Data RX: Handle 2048 flags 0x02 dlen 20 #580 [hci0] 1.456003
- ATT: Handle Value Notification (0x1b) len 15
- Handle: 0x0088
- ASE ID: 0x01
- State: Codec Configured (0x01)
- Framing: Unframed PDUs supported (0x00)
- PHY: 0x02
- LE 2M PHY (0x02)
- RTN: 2
- Max Transport Latency: 10
- Presentation Delay Min: 20000 us
- Presentation Delay Max: 40000 us
- Preferred Presentation Delay Min: 20000 us
- Preferred Presentation Delay Max: 40000 us
- Codec: LC3 (0x06)
- Sampling Frequency: 48000 Hz
- Frame Duration: 10 ms
- Audio Channel Allocation: Front Left
- Frame Length: 120
-
-**ASE Control Point operations** drive state transitions. The client
-writes to the ASE Control Point characteristic to issue commands::
-
- < ACL Data TX: Handle 2048 flags 0x00 dlen 25 #582 [hci0] 1.518003
- ATT: Write Request (0x12) len 20
- Handle: 0x008b
- ASE Control Point: Config Codec (0x01)
- ASE ID: 0x01
- Target Latency: Low Latency (0x01)
- PHY: LE 2M PHY
- Codec: LC3 (0x06)
- Sampling Frequency: 48000 Hz
- Frame Duration: 10 ms
- Audio Channel Allocation: Front Left
- Frame Length: 120
-
-ASE Control Point commands:
-
-.. list-table::
- :header-rows: 1
- :widths: 10 25 65
-
- * - Opcode
- - Command
- - Purpose
- * - 0x01
- - Config Codec
- - Select codec and parameters (Idle → Codec Configured)
- * - 0x02
- - Config QoS
- - Set CIG/CIS IDs and QoS params (Codec Configured → QoS Configured)
- * - 0x03
- - Enable
- - Start ASE with metadata (QoS Configured → Enabling)
- * - 0x04
- - Receiver Start Ready
- - Signal receiver readiness (Enabling → Streaming, server-side)
- * - 0x05
- - Disable
- - Stop streaming (Streaming → Disabling)
- * - 0x06
- - Receiver Stop Ready
- - Signal receiver stopped
- * - 0x07
- - Update Metadata
- - Change metadata during streaming
- * - 0x08
- - Release
- - Tear down ASE (any → Releasing → Idle)
-
-CIS Setup and Teardown
-------------------------
-
-After ASE QoS Configuration, the host creates Connected Isochronous
-Streams (CIS) at the HCI level.
-
-**CIG Parameters** (configure the CIS group)::
-
- < HCI Command: LE Set CIG Parameters (0x08|0x0062) plen 26 #590 [hci0] 1.624003
- CIG ID: 0x00
- Central to Peripheral SDU Interval: 10000 us
- Peripheral to Central SDU Interval: 10000 us
- SCA: 0x00
- Packing: Sequential (0x00)
- Framing: Unframed (0x00)
- Central to Peripheral Max Latency: 10 ms
- Peripheral to Central Max Latency: 10 ms
- Number of CIS: 1
- CIS ID: 0x00
- Central to Peripheral Max SDU: 120
- Peripheral to Central Max SDU: 0
- Central to Peripheral PHY: LE 2M PHY
- Peripheral to Central PHY: LE 2M PHY
- Central to Peripheral RTN: 2
- Peripheral to Central RTN: 2
-
- > HCI Event: Command Complete (0x0e) plen 8 #592 [hci0] 1.624556
- LE Set CIG Parameters (0x08|0x0062) ncmd 1
- Status: Success (0x00)
- CIG ID: 0x00
- Number of Handles: 1
- Connection Handle: 2064
-
-**CIS Creation**::
-
- < HCI Command: LE Create CIS (0x08|0x0064) plen 9 #594 [hci0] 1.688003
- Number of CIS: 1
- CIS Handle: 2064
- ACL Handle: 2048
-
- > HCI Event: LE Meta Event (0x3e) plen 29 #596 [hci0] 1.756556
- LE CIS Established (0x19)
- Status: Success (0x00)
- Connection Handle: 2064
- CIG Sync Delay: 5000 us
- CIS Sync Delay: 5000 us
- Central to Peripheral Latency: 10000 us
- Peripheral to Central Latency: 10000 us
- Central to Peripheral PHY: LE 2M PHY
- Peripheral to Central PHY: LE 2M PHY
- NSE: 3
- Central to Peripheral BN: 1
- Peripheral to Central BN: 0
- Central to Peripheral FT: 2
- Peripheral to Central FT: 2
- Max PDU C to P: 120
- Max PDU P to C: 0
- ISO Interval: 10.00 msec (0x0008)
-
-Note that the CIS Handle (2064) is different from the ACL Handle
-(2048). CIS data packets use the CIS handle.
-
-**ISO Data Path Setup**::
-
- < HCI Command: LE Setup ISO Data Path (0x08|0x006e) plen 13 #598 [hci0] 1.820003
- Handle: 2064
- Data Path Direction: Input (Host to Controller) (0x00)
- Data Path ID: HCI (0x00)
- Coding Format: LC3 (0x06)
- Company ID: 0x0000
- Vendor Codec ID: 0x0000
- Controller Delay: 0 us
-
-After this, ISO data packets flow on the CIS handle::
-
- < ISO Data TS: Handle 2064 flags 0x02 dlen 124 #600 [hci0] 1.884003
-
-Broadcast Audio (BIG)
-----------------------
-
-Broadcast Isochronous Streams use BIG (Broadcast Isochronous Group)
-instead of CIS. The setup involves periodic advertising with BASE
-(Broadcast Audio Source Endpoint) announcements.
-
-**BASE announcement** (in periodic advertising data)::
-
- > HCI Event: LE Meta Event (0x3e) plen 80 #200 [hci0] 0.500003
- LE Periodic Advertising Report (0x0f)
- ...
- Service Data: Basic Audio Announcement (0x1851)
- Presentation Delay: 40000 us
- Number of Subgroups: 1
- Number of BIS: 2
- Codec: LC3 (0x06)
- Sampling Frequency: 48000 Hz
- Frame Duration: 10 ms
- Frame Length: 120
- BIS #1
- Audio Channel Allocation: Front Left
- BIS #2
- Audio Channel Allocation: Front Right
-
-**BIG creation** (source side)::
-
- < HCI Command: LE Create BIG (0x08|0x0068) plen 31 #210 [hci0] 0.600003
- BIG Handle: 0x00
- Advertising Handle: 0x01
- Number of BIS: 2
- SDU Interval: 10000 us
- Max SDU: 120
- Max Latency: 10 ms
- RTN: 2
- PHY: LE 2M PHY
- Packing: Sequential (0x00)
- Framing: Unframed (0x00)
- Encryption: Unencrypted (0x00)
-
-**BIG sync** (receiver side)::
-
- < HCI Command: LE BIG Create Sync (0x08|0x006b) plen 15 #220 [hci0] 0.700003
- BIG Handle: 0x00
- Sync Handle: 0x0001
- Encryption: Unencrypted (0x00)
- Number of BIS: 2
- BIS: 0x01
- BIS: 0x02
-
-BIG Sync Receiver Flow
-~~~~~~~~~~~~~~~~~~~~~~
-
-A receiver must complete a specific sequence of steps before it can
-receive broadcast audio. The critical prerequisite chain is:
-
-1. **Synchronize to periodic advertising** -- the receiver must first
- discover and sync to the broadcaster's periodic advertising train.
-2. **Receive PA Reports with BASE** -- the periodic advertising data
- contains the BASE (Broadcast Audio Source Endpoint) structure
- describing the broadcast's codec configuration.
-3. **Receive BIG Info Advertising Report** -- this event tells the
- receiver that a BIG exists on the periodic advertising train and
- provides its parameters (number of BIS, encryption, SDU interval,
- etc.). **This is the critical gate**: without receiving BIG Info,
- the receiver cannot issue ``LE BIG Create Sync``.
-4. **Issue LE BIG Create Sync** -- using the sync handle from step 1
- and parameters from step 3.
-5. **Receive BIG Sync Established** -- the controller confirms sync
- with BIS connection handles.
-6. **Setup ISO Data Path** -- configure the data path for each BIS.
-7. **ISO Data flows** -- broadcast audio packets arrive.
-
-If any step fails or is missing, the subsequent steps cannot proceed.
-The most common failure pattern is that **BIG Info is never received**
-(e.g., the periodic advertising data does not contain a BIG, or PA
-sync was lost before BIG Info arrived), which means ``LE BIG Create
-Sync`` is never sent.
-
-Without PAST (Direct PA Sync)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-When the receiver scans for and syncs to periodic advertising
-directly (without assistance from a Broadcast Assistant):
-
-**Step 1 -- Create PA sync**::
-
- < HCI Command: LE Periodic Advertising Create Sync (0x08|0x0044) plen 14 #100 [hci0] 0.100003
- Options: 0x0000
- SID: 0x01
- Adv Address Type: Public (0x00)
- Adv Address: XX:XX:XX:XX:XX:XX
- Skip: 0x0000
- Sync Timeout: 2000 msec (0x00c8)
- Sync CTE Type: 0x0000
-
-**Step 2 -- PA Sync Established** (sync handle assigned)::
-
- > HCI Event: LE Meta Event (0x3e) plen 16 #105 [hci0] 0.150003
- LE Periodic Advertising Sync Established (0x0e)
- Status: Success (0x00)
- Sync Handle: 0x0001
- Advertising SID: 0x01
- Advertiser Address Type: Public (0x00)
- Advertiser Address: XX:XX:XX:XX:XX:XX
- Advertiser PHY: LE 2M PHY (0x02)
- Periodic Advertising Interval: 10.000 msec (0x0008)
- Advertiser Clock Accuracy: 0x05
-
-**Step 3 -- PA Reports** (contain BASE data)::
-
- > HCI Event: LE Meta Event (0x3e) plen 80 #110 [hci0] 0.200003
- LE Periodic Advertising Report (0x0f)
- Sync Handle: 0x0001
- ...
- Service Data: Basic Audio Announcement (0x1851)
-
-**Step 4 -- BIG Info Advertising Report** (critical gate)::
-
- > HCI Event: LE Meta Event (0x3e) plen 24 #120 [hci0] 0.300003
- LE BIG Info Advertising Report (0x22)
- Sync Handle: 0x0001
- Number BIS: 2
- NSE: 4
- ISO Interval: 10.000 msec (0x0008)
- BN: 2
- PTO: 1
- IRC: 2
- Maximum PDU: 120
- SDU Interval: 10000 us
- Maximum SDU: 120
- PHY: LE 2M PHY (0x02)
- Framing: Unframed (0x00)
- Encryption: 0x00
-
-This event is generated by the controller each time it receives a
-periodic advertising packet that contains BIG Info. It provides all
-parameters the receiver needs to decide whether to sync to the BIG.
-Key fields:
-
-- ``Number BIS`` -- how many BIS streams are available.
-- ``SDU Interval`` and ``Maximum SDU`` -- audio frame timing and size.
-- ``Encryption`` -- whether a Broadcast Code is required (0x01) or
- not (0x00). If encrypted, the receiver must supply the correct
- Broadcast Code in ``LE BIG Create Sync``.
-- ``Sync Handle`` -- must match a currently active PA sync.
-
-**Step 5 -- BIG Create Sync** (using sync handle + BIG Info)::
-
- < HCI Command: LE BIG Create Sync (0x08|0x006b) plen 15 #130 [hci0] 0.400003
- BIG Handle: 0x00
- BIG Sync Handle: 0x0001
- Encryption: Unencrypted (0x00)
- Broadcast Code: 00000000000000000000000000000000
- Maximum Number Subevents: 0x00
- Timeout: 2000 ms (0x00c8)
- Number of BIS: 2
- BIS: 0x01
- BIS: 0x02
-
-**Step 6 -- BIG Sync Established**::
-
- > HCI Event: LE Meta Event (0x3e) plen 20 #135 [hci0] 0.450003
- LE BIG Sync Established (0x1d)
- Status: Success (0x00)
- BIG Handle: 0x00
- Transport Latency: 10000 us
- NSE: 4
- BN: 2
- PTO: 1
- IRC: 2
- Maximum PDU: 120
- ISO Interval: 10.000 msec (0x0008)
- Connection Handle: 0x0010
- Connection Handle: 0x0011
-
-On success, the controller assigns BIS connection handles (0x0010,
-0x0011 above). A non-zero Status indicates failure -- common errors:
-
-- ``0x3e`` (Connection Failed to be Established) -- BIG parameters
- do not match or the BIG is no longer present.
-- ``0x3f`` (Limit Reached) -- controller resources exhausted.
-
-**Step 7 -- Setup ISO Data Path** (for each BIS)::
-
- < HCI Command: LE Setup ISO Data Path (0x08|0x006e) plen 13 #140 [hci0] 0.500003
- Connection Handle: 0x0010
- Data Path Direction: Output (Host to Controller) (0x01)
- Data Path ID: HCI (0x00)
-
- < HCI Command: LE Setup ISO Data Path (0x08|0x006e) plen 13 #145 [hci0] 0.550003
- Connection Handle: 0x0011
- Data Path Direction: Output (Host to Controller) (0x01)
- Data Path ID: HCI (0x00)
-
-**Step 8 -- ISO Data flows** on BIS handles::
-
- > ISO Data: Handle 0x0010 flags 0x02 dlen 124 #150 [hci0] 0.600003
- > ISO Data: Handle 0x0011 flags 0x02 dlen 124 #151 [hci0] 0.600003
-
-With PAST (Periodic Advertising Sync Transfer)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-When a Broadcast Assistant (e.g., a phone) helps a Scan Delegator
-(e.g., a hearing aid) sync to a broadcast, it can transfer the PA
-sync via PAST over an existing ACL connection. This avoids the
-delegator having to scan for and sync to the PA train itself.
-
-The BASS (Broadcast Audio Scan Service) protocol coordinates this:
-
-1. The assistant writes an **Add Source** operation to the delegator's
- BASS control point with ``PA Sync`` set to ``0x01``
- (Synchronize via PAST).
-2. The delegator prepares to receive the transfer by setting PAST
- parameters.
-3. The assistant transfers its PA sync to the delegator.
-4. The delegator receives the PAST event with a sync handle.
-5. From here, the flow continues as in the non-PAST case (PA Reports
- → BIG Info → BIG Create Sync → etc.).
-
-**BASS Add Source** (assistant writes to delegator, seen in ATT)::
-
- < ACL Data TX: Handle 64 flags 0x00 dlen 27 #300 [hci0] 1.000003
- ATT: Write Command (0x52) len 22
- Handle: 0x0025
- Data: 04...
- Opcode: Add Source (0x04)
- Advertiser Address Type: Public (0x00)
- Advertiser Address: XX:XX:XX:XX:XX:XX
- Advertising SID: 0x01
- PA Sync: Synchronize to PA - PAST (0x01)
- PA Interval: 0x0008
- Number of Subgroups: 1
- BIS Sync: 0x00000003
- Metadata Length: 0
-
-PA Sync values in the Add Source operation:
-
-- ``0x00`` -- Do not synchronize to PA
-- ``0x01`` -- Synchronize to PA, PAST available
-- ``0x02`` -- Synchronize to PA, PAST not available (delegator
- must scan and sync directly)
-
-**PAST Parameters** (delegator prepares to receive transfer)::
-
- < HCI Command: LE Periodic Advertising Sync Transfer Parameters (0x08|0x005c) plen 8 #310 [hci0] 1.100003
- Connection handle: 64
- Mode: Enabled with report events enabled (0x02)
- Skip: 0x00
- Sync timeout: 2000 msec (0x00c8)
- Sync CTE Type: 0x0000
-
-**PAST Transfer** (assistant sends its PA sync)::
-
- < HCI Command: LE Periodic Advertising Sync Transfer (0x08|0x005a) plen 6 #320 [hci0] 1.200003
- Connection handle: 64
- Service data: 0x0001
- Sync handle: 1
-
-**PAST Received** (delegator gets the sync handle)::
-
- > HCI Event: LE Meta Event (0x3e) plen 19 #325 [hci0] 1.250003
- LE Periodic Advertising Sync Transfer Received (0x18)
- Status: Success (0x00)
- Handle: 64
- Connection handle: 64
- Service data: 0x0001
- Sync handle: 1
- SID: 0x01
- Address type: Public (0x00)
- Address: XX:XX:XX:XX:XX:XX
- PHY: LE 2M PHY (0x02)
- Periodic advertising Interval: 10.000
- Clock Accuracy: 0x05
-
-On success, the delegator now has a PA sync (``Sync handle: 1``) and
-will begin receiving PA Reports and BIG Info events, continuing from
-step 3 of the non-PAST flow above.
-
-.. note::
-
- **Race condition**: The PAST Parameters command must be sent
- **before** the assistant sends the PAST Transfer. In BlueZ, the
- PA sync state in BASS is set after probing completes to avoid
- the remote sending PAST before the kernel has enabled PAST
- Parameters on the HCI level.
-
-BIG Sync Teardown
-^^^^^^^^^^^^^^^^^
-
-**Receiver-initiated teardown** -- the receiver terminates its BIG
-sync::
-
- < HCI Command: LE BIG Terminate Sync (0x08|0x006c) plen 1 #500 [hci0] 5.000003
- BIG Handle: 0x00
-
- > HCI Event: Command Complete (0x0e) plen 5 #501 [hci0] 5.001003
- LE BIG Terminate Sync (0x08|0x006c) ncmd 1
- Status: Success (0x00)
- BIG Handle: 0x00
-
-**Broadcaster-initiated teardown** -- the broadcaster terminates its
-BIG, and the receiver gets a BIG Sync Lost event::
-
- > HCI Event: LE Meta Event (0x3e) plen 2 #510 [hci0] 6.000003
- LE BIG Sync Lost (0x1e)
- BIG Handle: 0x00
- Reason: Connection Terminated By Local Host (0x16)
-
-The ``Reason`` field indicates why sync was lost:
-
-- ``0x08`` (Connection Timeout) -- BIG packets not received within
- the sync timeout.
-- ``0x13`` (Remote User Terminated Connection) -- broadcaster stopped
- the BIG intentionally.
-- ``0x16`` (Connection Terminated By Local Host) -- local controller
- terminated.
-- ``0x3e`` (Connection Failed to be Established) -- could not
- establish sync initially.
-
-**Source-side BIG termination** (broadcaster tears down)::
-
- < HCI Command: LE Terminate BIG (0x08|0x006a) plen 2 #520 [hci0] 7.000003
- BIG Handle: 0x00
- Reason: Connection Terminated By Local Host (0x16)
-
- > HCI Event: LE Meta Event (0x3e) plen 2 #521 [hci0] 7.001003
- LE BIG Terminate (0x1c)
- BIG Handle: 0x00
- Reason: Connection Terminated By Local Host (0x16)
-
-BIG Sync Failure Diagnosis
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-When analyzing a trace where BIG sync fails, check the following in
-order:
-
-1. **Is PA sync established?** -- Look for ``LE Periodic Advertising
- Sync Established`` with ``Status: Success``. If missing, the
- receiver never synced to the PA train.
-2. **Are PA Reports arriving?** -- Look for ``LE Periodic Advertising
- Report`` events. If absent after PA sync, the PA train may have
- been lost.
-3. **Is BIG Info received?** -- Look for ``LE BIG Info Advertising
- Report``. **If this event never appears, the BIG does not exist
- on this PA train**, or the broadcaster has not yet started it.
- Without BIG Info, ``LE BIG Create Sync`` cannot be sent.
-4. **Is BIG Create Sync sent?** -- If BIG Info was received but
- ``LE BIG Create Sync`` was never sent, the host-side logic failed
- to act on the BIG Info (e.g., mismatched codec, encryption
- mismatch, application-level issue).
-5. **Does BIG Sync Established succeed?** -- Check the ``Status``
- field. A non-zero status means the controller could not sync to
- the BIG.
-6. **Is ISO Data Path set up?** -- Look for ``LE Setup ISO Data Path``
- for each BIS handle from BIG Sync Established.
-7. **Is ISO Data flowing?** -- Look for ``ISO Data`` packets on the
- BIS handles.
-
-Automating LE Audio Analysis
-------------------------------
-
-**Identify LE Audio activity**::
-
- grep -n "ASE Control Point\|ASE ID\|State:.*Codec Configured\|State:.*QoS Configured\|State:.*Enabling\|State:.*Streaming\|State:.*Releasing" output.txt
-
-**Track ASE state transitions** for a specific ASE::
-
- grep -n "ASE ID:" output.txt
-
-Then examine the ``State:`` line following each ASE ID match.
-
-**Check codec configuration**::
-
- grep -n "Codec: LC3\|Sampling Frequency:\|Frame Duration:\|Frame Length:\|Audio Channel" output.txt
-
-**Verify CIS establishment**::
-
- grep -n "Set CIG Parameters\|Create CIS\|CIS Established\|Setup ISO Data Path" output.txt
-
-**Detect CIS failures** -- check the Status field after
-``CIS Established``::
-
- grep -n "CIS Established" output.txt
-
-Then examine the following line for ``Status:``.
-
-**Detect broadcast audio**::
-
- grep -n "Basic Audio Announcement\|Create BIG\|BIG Complete\|BIG Create Sync\|BIG Sync\|BIG Info\|BIG Terminate\|BIG Sync Lost" output.txt
-
-**Trace BIG Sync receiver flow** -- verify each prerequisite step::
-
- grep -n "Periodic Advertising Create Sync\|Periodic Advertising Sync Established\|BIG Info Advertising Report\|BIG Create Sync\|BIG Sync Established\|BIG Sync Lost\|BIG Terminate" output.txt
-
-**Detect PAST-based sync** -- check for Periodic Advertising Sync
-Transfer::
-
- grep -n "Sync Transfer Parameters\|Sync Transfer (0x08\|PAST Received\|PA Sync:.*PAST\|Add Source" output.txt
-
-**Check BIG Info arrival** -- the critical gate for BIG sync. If this
-is absent, the receiver has no BIG to sync to::
-
- grep -n "BIG Info Advertising Report" output.txt
-
-**Full LE Audio diagnosis pattern**:
-
-*Unicast (CIS) flow:*
-
-1. Find PACS reads -- verify codec compatibility between devices
-2. Find ASE Control Point writes -- trace the Config Codec → Config
- QoS → Enable sequence
-3. Find ASE state notifications -- verify each transition succeeds
-4. Find CIG Parameters and CIS creation -- verify HCI-level setup
-5. Find ``CIS Established`` -- check Status for success
-6. Find ``Setup ISO Data Path`` -- verify data path configuration
-7. Find ISO Data packets -- confirm audio is flowing
-8. On failure, check ASE Control Point notification responses for
- error codes (Response Code and Response Reason fields)
-
-*Broadcast (BIG) receiver flow:*
-
-1. Find ``Periodic Advertising Create Sync`` or ``PAST Received`` --
- how did PA sync start?
-2. Find ``Periodic Advertising Sync Established`` or
- ``PAST Received`` with ``Status: Success`` -- is PA synced?
-3. Find ``Periodic Advertising Report`` with
- ``Basic Audio Announcement`` -- is BASE data arriving?
-4. Find ``BIG Info Advertising Report`` -- **critical**: does the BIG
- exist? If missing, the BIG cannot be synced.
-5. Find ``BIG Create Sync`` -- did the host request BIG sync?
-6. Find ``BIG Sync Established`` -- check ``Status`` for success.
-7. Find ``Setup ISO Data Path`` for each BIS handle.
-8. Find ``ISO Data`` on BIS handles -- confirm audio is flowing.
-9. On failure, check for ``BIG Sync Lost`` and examine ``Reason``.
+.. include:: btmon-le-audio.rst
PROTOCOL ERROR CODES
=====================
--
2.53.0
^ permalink raw reply related [flat|nested] 7+ messages in thread
* [PATCH BlueZ v1 3/6] doc/btmon: Split L2CAP Channel Tracking into btmon-l2cap.rst
2026-03-12 17:15 [PATCH BlueZ v1 1/6] doc/btmon: Split Advertising and Scanning into btmon-advertising.rst Luiz Augusto von Dentz
2026-03-12 17:15 ` [PATCH BlueZ v1 2/6] doc/btmon: Split LE Audio Protocol Flow into btmon-le-audio.rst Luiz Augusto von Dentz
@ 2026-03-12 17:15 ` Luiz Augusto von Dentz
2026-03-12 17:15 ` [PATCH BlueZ v1 4/6] doc/btmon: Split SMP Pairing Flow into btmon-smp.rst Luiz Augusto von Dentz
` (3 subsequent siblings)
5 siblings, 0 replies; 7+ messages in thread
From: Luiz Augusto von Dentz @ 2026-03-12 17:15 UTC (permalink / raw)
To: linux-bluetooth
From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
Move the L2CAP CHANNEL TRACKING section into a standalone file and
replace it with an RST include directive.
---
doc/btmon-l2cap.rst | 196 ++++++++++++++++++++++++++++++++++++++++++++
doc/btmon.rst | 191 +-----------------------------------------
2 files changed, 197 insertions(+), 190 deletions(-)
create mode 100644 doc/btmon-l2cap.rst
diff --git a/doc/btmon-l2cap.rst b/doc/btmon-l2cap.rst
new file mode 100644
index 000000000000..7154898c00f4
--- /dev/null
+++ b/doc/btmon-l2cap.rst
@@ -0,0 +1,196 @@
+=================================
+btmon: L2CAP Channel Tracking
+=================================
+
+.. This file is included by btmon.rst.
+
+L2CAP CHANNEL TRACKING
+=======================
+
+L2CAP (Logical Link Control and Adaptation Protocol) multiplexes
+multiple logical channels over a single ACL connection. btmon decodes
+L2CAP signaling automatically and routes data to higher-layer protocol
+decoders based on the channel.
+
+Fixed Channels
+--------------
+
+Fixed channels have pre-assigned Channel Identifiers (CIDs) and do
+not require signaling to establish:
+
+.. list-table::
+ :header-rows: 1
+ :widths: 10 30 60
+
+ * - CID
+ - Protocol
+ - Description
+ * - 0x0001
+ - L2CAP Signaling (BR/EDR)
+ - Channel management for classic connections
+ * - 0x0002
+ - Connectionless Reception
+ - Connectionless L2CAP data
+ * - 0x0003
+ - AMP Manager
+ - AMP (Alternate MAC/PHY) control
+ * - 0x0004
+ - ATT
+ - Attribute Protocol (GATT operations)
+ * - 0x0005
+ - L2CAP Signaling (LE)
+ - Channel management for LE connections
+ * - 0x0006
+ - SMP (LE)
+ - Security Manager Protocol
+ * - 0x0007
+ - SMP (BR/EDR)
+ - Security Manager over classic transport
+
+In btmon output, fixed channel traffic is decoded directly without
+any L2CAP signaling preamble. For example, ATT on CID 0x0004 appears
+as::
+
+ < ACL Data TX: Handle 2048 flags 0x00 dlen 7 #494 [hci0] 0.004488
+ ATT: Exchange MTU Request (0x02) len 2
+ Client RX MTU: 517
+
+Dynamic Channels (BR/EDR)
+--------------------------
+
+Classic Bluetooth uses L2CAP signaling on CID 0x0001 to establish
+dynamic channels. Each channel is identified by a PSM (Protocol/Service
+Multiplexer) that determines which protocol runs on it.
+
+**Channel establishment**::
+
+ > ACL Data RX: Handle 256 flags 0x02 dlen 16 #142 [hci0] 2.034556
+ L2CAP: Connection Request (0x02) ident 3 len 4
+ PSM: 25 (0x0019)
+ Source CID: 0x0040
+
+ < ACL Data TX: Handle 256 flags 0x00 dlen 20 #144 [hci0] 2.035002
+ L2CAP: Connection Response (0x03) ident 3 len 8
+ Destination CID: 0x0041
+ Source CID: 0x0040
+ Result: Connection successful (0x0000)
+ Status: No further information available (0x0000)
+
+After connection, configuration is exchanged::
+
+ > ACL Data RX: Handle 256 flags 0x02 dlen 20 #146 [hci0] 2.035556
+ L2CAP: Configure Request (0x04) ident 4 len 8
+ Destination CID: 0x0041
+ Flags: 0x0000
+ Option: MTU (0x01) [2]
+ MTU: 1024
+
+ < ACL Data TX: Handle 256 flags 0x00 dlen 18 #148 [hci0] 2.036003
+ L2CAP: Configure Response (0x05) ident 4 len 6
+ Source CID: 0x0040
+ Flags: 0x0000
+ Result: Success (0x0000)
+
+Common PSM-to-protocol mappings:
+
+.. list-table::
+ :header-rows: 1
+ :widths: 12 25 63
+
+ * - PSM
+ - Protocol
+ - Description
+ * - 0x0001
+ - SDP
+ - Service Discovery Protocol
+ * - 0x0003
+ - RFCOMM
+ - Serial port emulation (SPP, HFP, etc.)
+ * - 0x000f
+ - BNEP
+ - Bluetooth Network Encapsulation Protocol
+ * - 0x0017
+ - AVCTP
+ - Audio/Video Control Transport (AVRCP)
+ * - 0x0019
+ - AVDTP
+ - Audio/Video Distribution Transport (A2DP)
+ * - 0x001b
+ - AVCTP Browsing
+ - AVRCP browsing channel
+ * - 0x001f
+ - ATT (BR/EDR)
+ - Attribute Protocol over classic transport
+ * - 0x0027
+ - EATT
+ - Enhanced Attribute Protocol
+
+LE Credit-Based Channels
+--------------------------
+
+LE connections use L2CAP signaling on CID 0x0005 for dynamic
+channels. The LE Credit Based Connection mechanism provides flow
+control::
+
+ < ACL Data TX: Handle 2048 flags 0x00 dlen 18 #600 [hci0] 1.824003
+ LE L2CAP: LE Connection Request (0x14) ident 1 len 10
+ PSM: 39 (0x0027)
+ Source CID: 0x0040
+ MTU: 517
+ MPS: 251
+ Credits: 10
+
+ > ACL Data RX: Handle 2048 flags 0x02 dlen 18 #602 [hci0] 1.886556
+ LE L2CAP: LE Connection Response (0x15) ident 1 len 10
+ Destination CID: 0x0041
+ MTU: 517
+ MPS: 251
+ Credits: 10
+ Result: Connection successful (0x0000)
+
+EATT (Enhanced ATT) uses PSM 0x0027 over LE Credit-Based channels to
+provide multiple parallel ATT bearers.
+
+Connection Parameter Updates
+-----------------------------
+
+LE peripherals frequently request connection parameter changes via
+L2CAP signaling::
+
+ < ACL Data TX: Handle 2048 flags 0x00 dlen 16 #493 [hci0] 0.003915
+ LE L2CAP: Connection Parameter Update Request (0x12) ident 1 len 8
+ Min interval: 24
+ Max interval: 40
+ Peripheral latency: 0
+ Timeout multiplier: 256
+
+ > ACL Data RX: Handle 2048 flags 0x02 dlen 10 #495 [hci0] 0.066003
+ LE L2CAP: Connection Parameter Update Response (0x13) ident 1 len 2
+ Result: Connection Parameters accepted (0x0000)
+
+A result of ``Connection Parameters rejected (0x0001)`` means the
+central denied the request.
+
+Automating L2CAP Analysis
+--------------------------
+
+**Find all L2CAP channel establishments**::
+
+ grep -n "Connection Request\|Connection Response\|LE Connection Request\|LE Connection Response" output.txt
+
+**Track PSM usage** (identifies which protocols are active)::
+
+ grep -n "PSM:" output.txt
+
+**Find connection parameter update issues**::
+
+ grep -n "Parameter Update Request\|Parameter Update Response\|Parameters rejected" output.txt
+
+**Find EATT channel setup**::
+
+ grep -n "PSM: 39\|Enhanced Credit" output.txt
+
+**Trace a specific L2CAP channel**: To follow traffic on a dynamic
+channel, note the Source CID and Destination CID from the Connection
+Request/Response pair. Then search for those CIDs in subsequent data
+frames.
diff --git a/doc/btmon.rst b/doc/btmon.rst
index 9e33c46ae8db..84b9f29df95d 100644
--- a/doc/btmon.rst
+++ b/doc/btmon.rst
@@ -1376,196 +1376,7 @@ appears on reconnection, the bond was lost on one side.
5. Check for ``Identity Address Information`` -- reveals the device's
true address
-L2CAP CHANNEL TRACKING
-=======================
-
-L2CAP (Logical Link Control and Adaptation Protocol) multiplexes
-multiple logical channels over a single ACL connection. btmon decodes
-L2CAP signaling automatically and routes data to higher-layer protocol
-decoders based on the channel.
-
-Fixed Channels
---------------
-
-Fixed channels have pre-assigned Channel Identifiers (CIDs) and do
-not require signaling to establish:
-
-.. list-table::
- :header-rows: 1
- :widths: 10 30 60
-
- * - CID
- - Protocol
- - Description
- * - 0x0001
- - L2CAP Signaling (BR/EDR)
- - Channel management for classic connections
- * - 0x0002
- - Connectionless Reception
- - Connectionless L2CAP data
- * - 0x0003
- - AMP Manager
- - AMP (Alternate MAC/PHY) control
- * - 0x0004
- - ATT
- - Attribute Protocol (GATT operations)
- * - 0x0005
- - L2CAP Signaling (LE)
- - Channel management for LE connections
- * - 0x0006
- - SMP (LE)
- - Security Manager Protocol
- * - 0x0007
- - SMP (BR/EDR)
- - Security Manager over classic transport
-
-In btmon output, fixed channel traffic is decoded directly without
-any L2CAP signaling preamble. For example, ATT on CID 0x0004 appears
-as::
-
- < ACL Data TX: Handle 2048 flags 0x00 dlen 7 #494 [hci0] 0.004488
- ATT: Exchange MTU Request (0x02) len 2
- Client RX MTU: 517
-
-Dynamic Channels (BR/EDR)
---------------------------
-
-Classic Bluetooth uses L2CAP signaling on CID 0x0001 to establish
-dynamic channels. Each channel is identified by a PSM (Protocol/Service
-Multiplexer) that determines which protocol runs on it.
-
-**Channel establishment**::
-
- > ACL Data RX: Handle 256 flags 0x02 dlen 16 #142 [hci0] 2.034556
- L2CAP: Connection Request (0x02) ident 3 len 4
- PSM: 25 (0x0019)
- Source CID: 0x0040
-
- < ACL Data TX: Handle 256 flags 0x00 dlen 20 #144 [hci0] 2.035002
- L2CAP: Connection Response (0x03) ident 3 len 8
- Destination CID: 0x0041
- Source CID: 0x0040
- Result: Connection successful (0x0000)
- Status: No further information available (0x0000)
-
-After connection, configuration is exchanged::
-
- > ACL Data RX: Handle 256 flags 0x02 dlen 20 #146 [hci0] 2.035556
- L2CAP: Configure Request (0x04) ident 4 len 8
- Destination CID: 0x0041
- Flags: 0x0000
- Option: MTU (0x01) [2]
- MTU: 1024
-
- < ACL Data TX: Handle 256 flags 0x00 dlen 18 #148 [hci0] 2.036003
- L2CAP: Configure Response (0x05) ident 4 len 6
- Source CID: 0x0040
- Flags: 0x0000
- Result: Success (0x0000)
-
-Common PSM-to-protocol mappings:
-
-.. list-table::
- :header-rows: 1
- :widths: 12 25 63
-
- * - PSM
- - Protocol
- - Description
- * - 0x0001
- - SDP
- - Service Discovery Protocol
- * - 0x0003
- - RFCOMM
- - Serial port emulation (SPP, HFP, etc.)
- * - 0x000f
- - BNEP
- - Bluetooth Network Encapsulation Protocol
- * - 0x0017
- - AVCTP
- - Audio/Video Control Transport (AVRCP)
- * - 0x0019
- - AVDTP
- - Audio/Video Distribution Transport (A2DP)
- * - 0x001b
- - AVCTP Browsing
- - AVRCP browsing channel
- * - 0x001f
- - ATT (BR/EDR)
- - Attribute Protocol over classic transport
- * - 0x0027
- - EATT
- - Enhanced Attribute Protocol
-
-LE Credit-Based Channels
---------------------------
-
-LE connections use L2CAP signaling on CID 0x0005 for dynamic
-channels. The LE Credit Based Connection mechanism provides flow
-control::
-
- < ACL Data TX: Handle 2048 flags 0x00 dlen 18 #600 [hci0] 1.824003
- LE L2CAP: LE Connection Request (0x14) ident 1 len 10
- PSM: 39 (0x0027)
- Source CID: 0x0040
- MTU: 517
- MPS: 251
- Credits: 10
-
- > ACL Data RX: Handle 2048 flags 0x02 dlen 18 #602 [hci0] 1.886556
- LE L2CAP: LE Connection Response (0x15) ident 1 len 10
- Destination CID: 0x0041
- MTU: 517
- MPS: 251
- Credits: 10
- Result: Connection successful (0x0000)
-
-EATT (Enhanced ATT) uses PSM 0x0027 over LE Credit-Based channels to
-provide multiple parallel ATT bearers.
-
-Connection Parameter Updates
------------------------------
-
-LE peripherals frequently request connection parameter changes via
-L2CAP signaling::
-
- < ACL Data TX: Handle 2048 flags 0x00 dlen 16 #493 [hci0] 0.003915
- LE L2CAP: Connection Parameter Update Request (0x12) ident 1 len 8
- Min interval: 24
- Max interval: 40
- Peripheral latency: 0
- Timeout multiplier: 256
-
- > ACL Data RX: Handle 2048 flags 0x02 dlen 10 #495 [hci0] 0.066003
- LE L2CAP: Connection Parameter Update Response (0x13) ident 1 len 2
- Result: Connection Parameters accepted (0x0000)
-
-A result of ``Connection Parameters rejected (0x0001)`` means the
-central denied the request.
-
-Automating L2CAP Analysis
---------------------------
-
-**Find all L2CAP channel establishments**::
-
- grep -n "Connection Request\|Connection Response\|LE Connection Request\|LE Connection Response" output.txt
-
-**Track PSM usage** (identifies which protocols are active)::
-
- grep -n "PSM:" output.txt
-
-**Find connection parameter update issues**::
-
- grep -n "Parameter Update Request\|Parameter Update Response\|Parameters rejected" output.txt
-
-**Find EATT channel setup**::
-
- grep -n "PSM: 39\|Enhanced Credit" output.txt
-
-**Trace a specific L2CAP channel**: To follow traffic on a dynamic
-channel, note the Source CID and Destination CID from the Connection
-Request/Response pair. Then search for those CIDs in subsequent data
-frames.
+.. include:: btmon-l2cap.rst
.. include:: btmon-le-audio.rst
--
2.53.0
^ permalink raw reply related [flat|nested] 7+ messages in thread
* [PATCH BlueZ v1 4/6] doc/btmon: Split SMP Pairing Flow into btmon-smp.rst
2026-03-12 17:15 [PATCH BlueZ v1 1/6] doc/btmon: Split Advertising and Scanning into btmon-advertising.rst Luiz Augusto von Dentz
2026-03-12 17:15 ` [PATCH BlueZ v1 2/6] doc/btmon: Split LE Audio Protocol Flow into btmon-le-audio.rst Luiz Augusto von Dentz
2026-03-12 17:15 ` [PATCH BlueZ v1 3/6] doc/btmon: Split L2CAP Channel Tracking into btmon-l2cap.rst Luiz Augusto von Dentz
@ 2026-03-12 17:15 ` Luiz Augusto von Dentz
2026-03-12 17:15 ` [PATCH BlueZ v1 5/6] doc/btmon: Split GATT Database Reconstruction into btmon-gatt.rst Luiz Augusto von Dentz
` (2 subsequent siblings)
5 siblings, 0 replies; 7+ messages in thread
From: Luiz Augusto von Dentz @ 2026-03-12 17:15 UTC (permalink / raw)
To: linux-bluetooth
From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
Move the SMP PAIRING FLOW section into a standalone file and replace
it with an RST include directive.
---
doc/btmon-smp.rst | 252 ++++++++++++++++++++++++++++++++++++++++++++++
doc/btmon.rst | 247 +--------------------------------------------
2 files changed, 253 insertions(+), 246 deletions(-)
create mode 100644 doc/btmon-smp.rst
diff --git a/doc/btmon-smp.rst b/doc/btmon-smp.rst
new file mode 100644
index 000000000000..403032fbfc74
--- /dev/null
+++ b/doc/btmon-smp.rst
@@ -0,0 +1,252 @@
+===========================
+btmon: SMP Pairing Flow
+===========================
+
+.. This file is included by btmon.rst.
+
+SMP PAIRING FLOW
+================
+
+The Security Manager Protocol (SMP) handles pairing, key generation,
+and key distribution between Bluetooth devices. SMP traffic appears
+inside L2CAP on fixed CID 0x0006 (LE) or CID 0x0007 (BR/EDR). btmon
+decodes all SMP operations automatically.
+
+Pairing Phases
+--------------
+
+SMP pairing proceeds in three phases. Each phase produces a distinct
+pattern in the btmon output.
+
+**Phase 1: Feature Exchange**
+
+Pairing begins when one device sends a Security Request (peripheral)
+or the host initiates pairing directly. The initiator sends a Pairing
+Request and the responder replies with a Pairing Response::
+
+ > ACL Data RX: Handle 2048 flags 0x02 dlen 11 #497 [hci0] 0.026107
+ SMP: Pairing Request (0x01) len 6
+ IO capability: NoInputNoOutput (0x03)
+ OOB data: Authentication data not present (0x00)
+ Authentication requirement: Bonding, MITM, SC, CT2 (0x2d)
+ Max encryption key size: 16
+ Initiator key distribution: IdKey Sign (0x06)
+ Responder key distribution: IdKey Sign (0x06)
+
+ < ACL Data TX: Handle 2048 flags 0x00 dlen 11 #499 [hci0] 0.026894
+ SMP: Pairing Response (0x02) len 6
+ IO capability: KeyboardDisplay (0x04)
+ OOB data: Authentication data not present (0x00)
+ Authentication requirement: Bonding, SC, CT2 (0x29)
+ Max encryption key size: 16
+ Initiator key distribution: IdKey (0x02)
+ Responder key distribution: IdKey (0x02)
+
+Key fields to check:
+
+- **Authentication requirement** -- The ``SC`` flag indicates Secure
+ Connections. Its absence means Legacy Pairing.
+- **IO capability** -- Determines the association model (Just Works,
+ Passkey Entry, Numeric Comparison, OOB).
+- **Key distribution** -- Which keys each side will send after
+ encryption is established. ``IdKey`` = Identity Resolving Key (IRK),
+ ``EncKey`` = Long Term Key (legacy only), ``Sign`` = CSRK.
+
+**Phase 2: Authentication (Secure Connections)**
+
+For Secure Connections pairing (``SC`` flag set), both devices exchange
+public keys, then perform confirm/random value exchange::
+
+ > ACL Data RX: Handle 2048 flags 0x02 dlen 69 #501 [hci0] 0.098224
+ SMP: Pairing Public Key (0x0c) len 64
+ X: 1a2b3c4d...
+ Y: 5e6f7a8b...
+
+ < ACL Data TX: Handle 2048 flags 0x00 dlen 69 #503 [hci0] 0.148556
+ SMP: Pairing Public Key (0x0c) len 64
+ X: 9c8d7e6f...
+ Y: 0a1b2c3d...
+
+ < ACL Data TX: Handle 2048 flags 0x00 dlen 21 #505 [hci0] 0.149003
+ SMP: Pairing Confirm (0x03) len 16
+ Confirm value: a1b2c3d4e5f6...
+
+ > ACL Data RX: Handle 2048 flags 0x02 dlen 21 #507 [hci0] 0.212884
+ SMP: Pairing Random (0x04) len 16
+ Random value: 1122334455...
+
+ < ACL Data TX: Handle 2048 flags 0x00 dlen 21 #509 [hci0] 0.213100
+ SMP: Pairing Random (0x04) len 16
+ Random value: 6677889900...
+
+ > ACL Data RX: Handle 2048 flags 0x02 dlen 21 #511 [hci0] 0.278003
+ SMP: Pairing DHKey Check (0x0d) len 16
+ E: aabbccddee...
+
+ < ACL Data TX: Handle 2048 flags 0x00 dlen 21 #513 [hci0] 0.278450
+ SMP: Pairing DHKey Check (0x0d) len 16
+ E: ffeeddccbb...
+
+After DHKey Check, the initiator starts encryption at the HCI level::
+
+ < HCI Command: LE Start Encryption (0x08|0x0019) plen 28 #515 [hci0] 0.279002
+ > HCI Event: Encryption Change (0x08) plen 4 #517 [hci0] 0.342556
+ Status: Success (0x00)
+ Handle: 2048
+ Encryption: Enabled with AES-CCM (0x01)
+
+**Phase 2: Authentication (Legacy Pairing)**
+
+Legacy pairing (no ``SC`` flag) skips the Public Key and DHKey Check
+exchanges. Only Confirm and Random values are exchanged::
+
+ < ACL Data TX: Handle 2048 flags 0x00 dlen 21 #501 [hci0] 0.098224
+ SMP: Pairing Confirm (0x03) len 16
+ Confirm value: ...
+
+ > ACL Data RX: Handle 2048 flags 0x02 dlen 21 #503 [hci0] 0.162556
+ SMP: Pairing Confirm (0x03) len 16
+ Confirm value: ...
+
+ < ACL Data TX: Handle 2048 flags 0x00 dlen 21 #505 [hci0] 0.163003
+ SMP: Pairing Random (0x04) len 16
+ Random value: ...
+
+ > ACL Data RX: Handle 2048 flags 0x02 dlen 21 #507 [hci0] 0.228884
+ SMP: Pairing Random (0x04) len 16
+ Random value: ...
+
+**Phase 3: Key Distribution**
+
+After encryption is established, each device distributes keys as
+negotiated in Phase 1::
+
+ > ACL Data RX: Handle 2048 flags 0x02 dlen 21 #519 [hci0] 0.343002
+ SMP: Identity Information (0x08) len 16
+ Identity resolving key: 00112233445566778899aabbccddeeff
+
+ > ACL Data RX: Handle 2048 flags 0x02 dlen 12 #521 [hci0] 0.343556
+ SMP: Identity Address Information (0x09) len 7
+ Address type: Public (0x00)
+ Address: 00:11:22:33:44:55
+
+The Identity Address Information reveals the device's true public or
+static random address (as opposed to a Resolvable Private Address used
+during connection).
+
+For Legacy Pairing, LTK distribution also appears::
+
+ > ACL Data RX: Handle 2048 flags 0x02 dlen 21 #519 [hci0] 0.343002
+ SMP: Encryption Information (0x06) len 16
+ Long term key: 00112233...
+
+ > ACL Data RX: Handle 2048 flags 0x02 dlen 15 #521 [hci0] 0.343556
+ SMP: Central Identification (0x07) len 10
+ EDIV: 0x1234
+ Rand: 0x0123456789abcdef
+
+Pairing Failure
+---------------
+
+When pairing fails, one device sends a Pairing Failed PDU::
+
+ > ACL Data RX: Handle 2048 flags 0x02 dlen 6 #505 [hci0] 0.213002
+ SMP: Pairing Failed (0x05) len 1
+ Reason: Authentication requirements (0x03)
+
+SMP failure reasons:
+
+.. list-table::
+ :header-rows: 1
+ :widths: 8 35 57
+
+ * - Code
+ - Reason
+ - Diagnostic Meaning
+ * - 0x01
+ - Passkey Entry Failed
+ - User cancelled or entered wrong passkey
+ * - 0x02
+ - OOB Not Available
+ - OOB data expected but not provided
+ * - 0x03
+ - Authentication Requirements
+ - Devices cannot agree on security level (e.g.,
+ one requires MITM but IO caps only allow Just Works)
+ * - 0x04
+ - Confirm Value Failed
+ - Cryptographic check failed; possible MITM attack
+ * - 0x05
+ - Pairing Not Supported
+ - Remote does not support pairing
+ * - 0x06
+ - Encryption Key Size
+ - Cannot agree on key size
+ * - 0x07
+ - Command Not Supported
+ - Received unrecognized SMP command
+ * - 0x08
+ - Unspecified Reason
+ - Generic failure
+ * - 0x09
+ - Repeated Attempts
+ - Pairing rate-limited; wait before retry
+ * - 0x0a
+ - Invalid Parameters
+ - Invalid fields in SMP command
+ * - 0x0b
+ - DHKey Check Failed
+ - ECDH key agreement failed (SC only)
+ * - 0x0c
+ - Numeric Comparison Failed
+ - User rejected numeric comparison
+ * - 0x0d
+ - BR/EDR Pairing In Progress
+ - Classic pairing already active
+ * - 0x0e
+ - Cross-Transport Key Derivation Not Allowed
+ - CTKD rejected by policy
+
+Automating Pairing Analysis
+----------------------------
+
+**Identify all pairing attempts**::
+
+ grep -n "Pairing Request\|Pairing Response\|Pairing Failed\|Pairing Public Key\|DHKey Check" output.txt
+
+**Check pairing method (Secure Connections vs Legacy)**:
+
+- If ``Pairing Public Key`` appears between Request/Response and
+ Confirm: Secure Connections.
+- If only Confirm/Random follow Request/Response: Legacy Pairing.
+- Check the ``Authentication requirement`` line for the ``SC`` flag.
+
+**Detect pairing failures**::
+
+ grep -n "Pairing Failed" output.txt
+
+**Correlate pairing with encryption**:
+
+After successful pairing, expect ``Encryption Change`` with
+``Status: Success``. Search for::
+
+ grep -n "Encryption Change\|Encryption:" output.txt
+
+**Identify re-pairing on reconnect**:
+
+Reconnections to a bonded device should show ``Encryption Change``
+without SMP traffic (using stored keys). If SMP Pairing Request
+appears on reconnection, the bond was lost on one side.
+
+**Full pairing diagnosis pattern**:
+
+1. Find ``Pairing Request`` -- note the handle, IO capabilities,
+ auth requirements
+2. Find ``Pairing Response`` -- compare IO capabilities to determine
+ association model
+3. Check for ``Pairing Failed`` -- if present, the reason code
+ identifies the failure
+4. Check for ``Encryption Change`` with ``Status: Success`` -- confirms
+ pairing completed
+5. Check for ``Identity Address Information`` -- reveals the device's
+ true address
diff --git a/doc/btmon.rst b/doc/btmon.rst
index 84b9f29df95d..799066e83e74 100644
--- a/doc/btmon.rst
+++ b/doc/btmon.rst
@@ -1129,252 +1129,7 @@ The CCC descriptor at handle 0x000d belongs to the Service Changed
characteristic (0x000c), because it falls between that value handle
and the next characteristic declaration at 0x000e.
-SMP PAIRING FLOW
-================
-
-The Security Manager Protocol (SMP) handles pairing, key generation,
-and key distribution between Bluetooth devices. SMP traffic appears
-inside L2CAP on fixed CID 0x0006 (LE) or CID 0x0007 (BR/EDR). btmon
-decodes all SMP operations automatically.
-
-Pairing Phases
---------------
-
-SMP pairing proceeds in three phases. Each phase produces a distinct
-pattern in the btmon output.
-
-**Phase 1: Feature Exchange**
-
-Pairing begins when one device sends a Security Request (peripheral)
-or the host initiates pairing directly. The initiator sends a Pairing
-Request and the responder replies with a Pairing Response::
-
- > ACL Data RX: Handle 2048 flags 0x02 dlen 11 #497 [hci0] 0.026107
- SMP: Pairing Request (0x01) len 6
- IO capability: NoInputNoOutput (0x03)
- OOB data: Authentication data not present (0x00)
- Authentication requirement: Bonding, MITM, SC, CT2 (0x2d)
- Max encryption key size: 16
- Initiator key distribution: IdKey Sign (0x06)
- Responder key distribution: IdKey Sign (0x06)
-
- < ACL Data TX: Handle 2048 flags 0x00 dlen 11 #499 [hci0] 0.026894
- SMP: Pairing Response (0x02) len 6
- IO capability: KeyboardDisplay (0x04)
- OOB data: Authentication data not present (0x00)
- Authentication requirement: Bonding, SC, CT2 (0x29)
- Max encryption key size: 16
- Initiator key distribution: IdKey (0x02)
- Responder key distribution: IdKey (0x02)
-
-Key fields to check:
-
-- **Authentication requirement** -- The ``SC`` flag indicates Secure
- Connections. Its absence means Legacy Pairing.
-- **IO capability** -- Determines the association model (Just Works,
- Passkey Entry, Numeric Comparison, OOB).
-- **Key distribution** -- Which keys each side will send after
- encryption is established. ``IdKey`` = Identity Resolving Key (IRK),
- ``EncKey`` = Long Term Key (legacy only), ``Sign`` = CSRK.
-
-**Phase 2: Authentication (Secure Connections)**
-
-For Secure Connections pairing (``SC`` flag set), both devices exchange
-public keys, then perform confirm/random value exchange::
-
- > ACL Data RX: Handle 2048 flags 0x02 dlen 69 #501 [hci0] 0.098224
- SMP: Pairing Public Key (0x0c) len 64
- X: 1a2b3c4d...
- Y: 5e6f7a8b...
-
- < ACL Data TX: Handle 2048 flags 0x00 dlen 69 #503 [hci0] 0.148556
- SMP: Pairing Public Key (0x0c) len 64
- X: 9c8d7e6f...
- Y: 0a1b2c3d...
-
- < ACL Data TX: Handle 2048 flags 0x00 dlen 21 #505 [hci0] 0.149003
- SMP: Pairing Confirm (0x03) len 16
- Confirm value: a1b2c3d4e5f6...
-
- > ACL Data RX: Handle 2048 flags 0x02 dlen 21 #507 [hci0] 0.212884
- SMP: Pairing Random (0x04) len 16
- Random value: 1122334455...
-
- < ACL Data TX: Handle 2048 flags 0x00 dlen 21 #509 [hci0] 0.213100
- SMP: Pairing Random (0x04) len 16
- Random value: 6677889900...
-
- > ACL Data RX: Handle 2048 flags 0x02 dlen 21 #511 [hci0] 0.278003
- SMP: Pairing DHKey Check (0x0d) len 16
- E: aabbccddee...
-
- < ACL Data TX: Handle 2048 flags 0x00 dlen 21 #513 [hci0] 0.278450
- SMP: Pairing DHKey Check (0x0d) len 16
- E: ffeeddccbb...
-
-After DHKey Check, the initiator starts encryption at the HCI level::
-
- < HCI Command: LE Start Encryption (0x08|0x0019) plen 28 #515 [hci0] 0.279002
- > HCI Event: Encryption Change (0x08) plen 4 #517 [hci0] 0.342556
- Status: Success (0x00)
- Handle: 2048
- Encryption: Enabled with AES-CCM (0x01)
-
-**Phase 2: Authentication (Legacy Pairing)**
-
-Legacy pairing (no ``SC`` flag) skips the Public Key and DHKey Check
-exchanges. Only Confirm and Random values are exchanged::
-
- < ACL Data TX: Handle 2048 flags 0x00 dlen 21 #501 [hci0] 0.098224
- SMP: Pairing Confirm (0x03) len 16
- Confirm value: ...
-
- > ACL Data RX: Handle 2048 flags 0x02 dlen 21 #503 [hci0] 0.162556
- SMP: Pairing Confirm (0x03) len 16
- Confirm value: ...
-
- < ACL Data TX: Handle 2048 flags 0x00 dlen 21 #505 [hci0] 0.163003
- SMP: Pairing Random (0x04) len 16
- Random value: ...
-
- > ACL Data RX: Handle 2048 flags 0x02 dlen 21 #507 [hci0] 0.228884
- SMP: Pairing Random (0x04) len 16
- Random value: ...
-
-**Phase 3: Key Distribution**
-
-After encryption is established, each device distributes keys as
-negotiated in Phase 1::
-
- > ACL Data RX: Handle 2048 flags 0x02 dlen 21 #519 [hci0] 0.343002
- SMP: Identity Information (0x08) len 16
- Identity resolving key: 00112233445566778899aabbccddeeff
-
- > ACL Data RX: Handle 2048 flags 0x02 dlen 12 #521 [hci0] 0.343556
- SMP: Identity Address Information (0x09) len 7
- Address type: Public (0x00)
- Address: 00:11:22:33:44:55
-
-The Identity Address Information reveals the device's true public or
-static random address (as opposed to a Resolvable Private Address used
-during connection).
-
-For Legacy Pairing, LTK distribution also appears::
-
- > ACL Data RX: Handle 2048 flags 0x02 dlen 21 #519 [hci0] 0.343002
- SMP: Encryption Information (0x06) len 16
- Long term key: 00112233...
-
- > ACL Data RX: Handle 2048 flags 0x02 dlen 15 #521 [hci0] 0.343556
- SMP: Central Identification (0x07) len 10
- EDIV: 0x1234
- Rand: 0x0123456789abcdef
-
-Pairing Failure
----------------
-
-When pairing fails, one device sends a Pairing Failed PDU::
-
- > ACL Data RX: Handle 2048 flags 0x02 dlen 6 #505 [hci0] 0.213002
- SMP: Pairing Failed (0x05) len 1
- Reason: Authentication requirements (0x03)
-
-SMP failure reasons:
-
-.. list-table::
- :header-rows: 1
- :widths: 8 35 57
-
- * - Code
- - Reason
- - Diagnostic Meaning
- * - 0x01
- - Passkey Entry Failed
- - User cancelled or entered wrong passkey
- * - 0x02
- - OOB Not Available
- - OOB data expected but not provided
- * - 0x03
- - Authentication Requirements
- - Devices cannot agree on security level (e.g.,
- one requires MITM but IO caps only allow Just Works)
- * - 0x04
- - Confirm Value Failed
- - Cryptographic check failed; possible MITM attack
- * - 0x05
- - Pairing Not Supported
- - Remote does not support pairing
- * - 0x06
- - Encryption Key Size
- - Cannot agree on key size
- * - 0x07
- - Command Not Supported
- - Received unrecognized SMP command
- * - 0x08
- - Unspecified Reason
- - Generic failure
- * - 0x09
- - Repeated Attempts
- - Pairing rate-limited; wait before retry
- * - 0x0a
- - Invalid Parameters
- - Invalid fields in SMP command
- * - 0x0b
- - DHKey Check Failed
- - ECDH key agreement failed (SC only)
- * - 0x0c
- - Numeric Comparison Failed
- - User rejected numeric comparison
- * - 0x0d
- - BR/EDR Pairing In Progress
- - Classic pairing already active
- * - 0x0e
- - Cross-Transport Key Derivation Not Allowed
- - CTKD rejected by policy
-
-Automating Pairing Analysis
-----------------------------
-
-**Identify all pairing attempts**::
-
- grep -n "Pairing Request\|Pairing Response\|Pairing Failed\|Pairing Public Key\|DHKey Check" output.txt
-
-**Check pairing method (Secure Connections vs Legacy)**:
-
-- If ``Pairing Public Key`` appears between Request/Response and
- Confirm: Secure Connections.
-- If only Confirm/Random follow Request/Response: Legacy Pairing.
-- Check the ``Authentication requirement`` line for the ``SC`` flag.
-
-**Detect pairing failures**::
-
- grep -n "Pairing Failed" output.txt
-
-**Correlate pairing with encryption**:
-
-After successful pairing, expect ``Encryption Change`` with
-``Status: Success``. Search for::
-
- grep -n "Encryption Change\|Encryption:" output.txt
-
-**Identify re-pairing on reconnect**:
-
-Reconnections to a bonded device should show ``Encryption Change``
-without SMP traffic (using stored keys). If SMP Pairing Request
-appears on reconnection, the bond was lost on one side.
-
-**Full pairing diagnosis pattern**:
-
-1. Find ``Pairing Request`` -- note the handle, IO capabilities,
- auth requirements
-2. Find ``Pairing Response`` -- compare IO capabilities to determine
- association model
-3. Check for ``Pairing Failed`` -- if present, the reason code
- identifies the failure
-4. Check for ``Encryption Change`` with ``Status: Success`` -- confirms
- pairing completed
-5. Check for ``Identity Address Information`` -- reveals the device's
- true address
+.. include:: btmon-smp.rst
.. include:: btmon-l2cap.rst
--
2.53.0
^ permalink raw reply related [flat|nested] 7+ messages in thread
* [PATCH BlueZ v1 5/6] doc/btmon: Split GATT Database Reconstruction into btmon-gatt.rst
2026-03-12 17:15 [PATCH BlueZ v1 1/6] doc/btmon: Split Advertising and Scanning into btmon-advertising.rst Luiz Augusto von Dentz
` (2 preceding siblings ...)
2026-03-12 17:15 ` [PATCH BlueZ v1 4/6] doc/btmon: Split SMP Pairing Flow into btmon-smp.rst Luiz Augusto von Dentz
@ 2026-03-12 17:15 ` Luiz Augusto von Dentz
2026-03-12 17:15 ` [PATCH BlueZ v1 6/6] doc/btmon: Split Connection Tracking into btmon-connections.rst Luiz Augusto von Dentz
2026-03-12 18:00 ` [BlueZ,v1,1/6] doc/btmon: Split Advertising and Scanning into btmon-advertising.rst bluez.test.bot
5 siblings, 0 replies; 7+ messages in thread
From: Luiz Augusto von Dentz @ 2026-03-12 17:15 UTC (permalink / raw)
To: linux-bluetooth
From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
Move the RECONSTRUCTING A GATT DATABASE FROM SNOOP TRACES section
into a standalone file and replace it with an RST include directive.
---
doc/btmon-gatt.rst | 423 +++++++++++++++++++++++++++++++++++++++++++++
doc/btmon.rst | 417 +-------------------------------------------
2 files changed, 424 insertions(+), 416 deletions(-)
create mode 100644 doc/btmon-gatt.rst
diff --git a/doc/btmon-gatt.rst b/doc/btmon-gatt.rst
new file mode 100644
index 000000000000..cbd6b7acf543
--- /dev/null
+++ b/doc/btmon-gatt.rst
@@ -0,0 +1,423 @@
+=======================================
+btmon: GATT Database Reconstruction
+=======================================
+
+.. This file is included by btmon.rst.
+
+RECONSTRUCTING A GATT DATABASE FROM SNOOP TRACES
+=================================================
+
+A btsnoop trace contains the complete ATT protocol exchange used by
+GATT clients and servers to discover each other's services. By reading
+the discovery requests and responses, it is possible to reconstruct the
+full GATT database of a remote device -- even without access to the
+device itself.
+
+This section explains the GATT discovery procedure and how each ATT
+operation appears in ``btmon`` output.
+
+Overview of GATT Discovery
+---------------------------
+
+GATT discovery is a multi-phase process where a client queries the
+server's attribute database using ATT protocol operations. The phases
+are:
+
+1. **Primary Service Discovery** -- Find all primary services and their
+ handle ranges.
+2. **Secondary Service Discovery** -- Find any secondary (included-only)
+ services.
+3. **Included Service Discovery** -- Find which services include other
+ services.
+4. **Characteristic Discovery** -- Find all characteristics within each
+ service.
+5. **Descriptor Discovery** -- Find all descriptors for each
+ characteristic.
+6. **Characteristic Value Reading** -- Read the values of readable
+ characteristics.
+
+Each phase uses a specific ATT operation and produces a
+request/response pattern in the trace. The client repeats each request
+with advancing handle ranges until the server responds with
+``Attribute Not Found``, indicating the end of that phase.
+
+Phase 1: Primary Service Discovery (Read By Group Type)
+--------------------------------------------------------
+
+The client discovers primary services using ``Read By Group Type
+Request`` with the ``Primary Service`` UUID (0x2800) as the group type.
+
+**Request**::
+
+ < ACL Data TX: Handle 2048 flags 0x00 dlen 11 #516 [hci0] 0.124726
+ ATT: Read By Group Type Request (0x10) len 6
+ Handle range: 0x0001-0xffff
+ Attribute group type: Primary Service (0x2800)
+
+The first request always starts at handle 0x0001 and searches through
+0xffff (the entire handle space).
+
+**Response**::
+
+ > ACL Data RX: Handle 2048 flags 0x02 dlen 42 #523 [hci0] 0.240151
+ ATT: Read By Group Type Response (0x11) len 37
+ Attribute data length: 6
+ Attribute group list: 6 entries
+ Handle range: 0x0001-0x0009
+ UUID: Generic Access Profile (0x1800)
+ Handle range: 0x000a-0x0011
+ UUID: Generic Attribute Profile (0x1801)
+ Handle range: 0x0012-0x0014
+ UUID: Device Information (0x180a)
+ Handle range: 0x0015-0x0039
+ UUID: Generic Telephony Bearer (0x184c)
+ Handle range: 0x003a-0x0059
+ UUID: Generic Media Control (0x1849)
+ Handle range: 0x005a-0x005c
+ UUID: Telephony and Media Audio (0x1855)
+
+Each entry provides:
+
+- **Handle range** -- The start and end handle of the service. All
+ attributes belonging to this service (characteristics, descriptors)
+ have handles within this range.
+- **UUID** -- The service UUID. Standard 16-bit UUIDs are shown with
+ their name (e.g., ``Generic Access Profile``). 128-bit vendor-specific
+ UUIDs appear as full UUID strings.
+
+The client continues by sending another request starting after the last
+handle in the response::
+
+ < ACL Data TX: Handle 2048 flags 0x00 dlen 11 #525 [hci0] 0.240641
+ ATT: Read By Group Type Request (0x10) len 6
+ Handle range: 0x005d-0xffff
+ Attribute group type: Primary Service (0x2800)
+
+This continues until the server responds with ``Attribute Not Found``::
+
+ > ACL Data RX: Handle 2048 flags 0x02 dlen 9 #532 [hci0] 0.360069
+ ATT: Error Response (0x01) len 4
+ Read By Group Type Request (0x10)
+ Handle: 0x005d
+ Error: Attribute Not Found (0x0a)
+
+This error indicates that no more primary services exist beyond handle
+0x005d. The client now has the complete list of primary services.
+
+.. note::
+
+ The ``Attribute data length`` field indicates the size of each entry
+ in the response. A value of 6 means 16-bit UUIDs (2 bytes start
+ handle + 2 bytes end handle + 2 bytes UUID). A value of 20 means
+ 128-bit UUIDs (2 + 2 + 16). If the server has both 16-bit and
+ 128-bit service UUIDs, they are returned in separate responses
+ because all entries in a single response must have the same length.
+
+Phase 2: Secondary Service Discovery
+--------------------------------------
+
+After primary services, the client may discover secondary services
+using the same ``Read By Group Type Request`` but with the ``Secondary
+Service`` UUID (0x2801)::
+
+ < ACL Data TX: Handle 2048 flags 0x00 dlen 11 #534 [hci0] 0.360752
+ ATT: Read By Group Type Request (0x10) len 6
+ Handle range: 0x0001-0xffff
+ Attribute group type: Secondary Service (0x2801)
+
+If no secondary services exist, the server responds with
+``Attribute Not Found``. Secondary services are not directly accessible
+to clients -- they are only reachable via include references from
+primary services.
+
+Phase 3: Included Service Discovery (Read By Type)
+----------------------------------------------------
+
+To discover which services include other services, the client uses
+``Read By Type Request`` with the ``Include`` UUID (0x2802)::
+
+ < ACL Data TX: Handle 2048 flags 0x00 dlen 11 #540 [hci0] 0.480731
+ ATT: Read By Type Request (0x08) len 6
+ Handle range: 0x0001-0x005c
+ Attribute type: Include (0x2802)
+
+The handle range typically spans the entire discovered database. Each
+include declaration in the response identifies a service that is
+included by the service containing that handle.
+
+Phase 4: Characteristic Discovery (Read By Type)
+--------------------------------------------------
+
+For each service, the client discovers its characteristics using
+``Read By Type Request`` with the ``Characteristic`` UUID (0x2803).
+The handle range is limited to the service's handle range.
+
+**Request**::
+
+ > ACL Data RX: Handle 2048 flags 0x02 dlen 11 #531 [hci0] 0.360063
+ ATT: Read By Type Request (0x08) len 6
+ Handle range: 0x0008-0x0011
+ Attribute type: Characteristic (0x2803)
+
+**Response**::
+
+ < ACL Data TX: Handle 2048 flags 0x00 dlen 27 #533 [hci0] 0.360714
+ ATT: Read By Type Response (0x09) len 22
+ Attribute data length: 7
+ Attribute data list: 3 entries
+ Handle: 0x0009
+ Value[5]: 200a00052a
+ Properties: 0x20
+ Indicate (0x20)
+ Value Handle: 0x000a
+ Value UUID: Service Changed (0x2a05)
+ Handle: 0x000c
+ Value[5]: 0a0d00292b
+ Properties: 0x0a
+ Read (0x02)
+ Write (0x08)
+ Value Handle: 0x000d
+ Value UUID: Client Supported Features (0x2b29)
+ Handle: 0x000e
+ Value[5]: 020f002a2b
+ Properties: 0x02
+ Read (0x02)
+ Value Handle: 0x000f
+ Value UUID: Database Hash (0x2b2a)
+
+Each characteristic entry provides:
+
+- **Handle** -- The handle of the characteristic declaration attribute.
+- **Properties** -- A bitmask indicating supported operations:
+
+ .. list-table::
+ :header-rows: 1
+ :widths: 10 30 60
+
+ * - Bit
+ - Property
+ - Description
+ * - 0x01
+ - Broadcast
+ - Can be broadcast in advertising data
+ * - 0x02
+ - Read
+ - Can be read
+ * - 0x04
+ - Write Without Response
+ - Can be written without acknowledgment
+ * - 0x08
+ - Write
+ - Can be written with acknowledgment
+ * - 0x10
+ - Notify
+ - Server can send notifications
+ * - 0x20
+ - Indicate
+ - Server can send indications
+ * - 0x40
+ - Authenticated Signed Writes
+ - Supports signed write commands
+ * - 0x80
+ - Extended Properties
+ - Has extended properties descriptor
+
+- **Value Handle** -- The handle where the characteristic's value is
+ stored (always declaration handle + 1).
+- **Value UUID** -- The UUID identifying the characteristic type.
+
+The client continues with advancing handle ranges until it receives
+``Attribute Not Found``::
+
+ > ACL Data RX: Handle 2048 flags 0x02 dlen 9 #572 [hci0] 1.200228
+ ATT: Error Response (0x01) len 4
+ Read By Type Request (0x08)
+ Handle: 0x005c
+ Error: Attribute Not Found (0x0a)
+
+Phase 5: Descriptor Discovery (Find Information)
+--------------------------------------------------
+
+Descriptors occupy the handles between a characteristic's value handle
+and the next characteristic declaration (or end of service). The client
+discovers them using ``Find Information Request``.
+
+**Request**::
+
+ > ACL Data RX: Handle 2048 flags 0x02 dlen 9 #556 [hci0] 0.959965
+ ATT: Find Information Request (0x04) len 4
+ Handle range: 0x000b-0x000b
+
+The handle range covers the gap between the characteristic value handle
+and the next characteristic declaration handle.
+
+**Response**::
+
+ < ACL Data TX: Handle 2048 flags 0x00 dlen 10 #561 [hci0] 0.961049
+ ATT: Find Information Response (0x05) len 5
+ Format: UUID-16 (0x01)
+ Handle: 0x000b
+ UUID: Client Characteristic Configuration (0x2902)
+
+Common descriptor UUIDs:
+
+.. list-table::
+ :header-rows: 1
+ :widths: 15 40 45
+
+ * - UUID
+ - Name
+ - Purpose
+ * - 0x2900
+ - Characteristic Extended Properties
+ - Additional property bits
+ * - 0x2901
+ - Characteristic User Description
+ - Human-readable description string
+ * - 0x2902
+ - Client Characteristic Configuration (CCC)
+ - Enable/disable notifications or indications
+ * - 0x2903
+ - Server Characteristic Configuration
+ - Server-side broadcast configuration
+ * - 0x2904
+ - Characteristic Presentation Format
+ - Data format, exponent, unit
+
+Phase 6: Reading Characteristic Values
+----------------------------------------
+
+After discovery, the client may read characteristic values using
+``Read Request``::
+
+ > ACL Data RX: Handle 2048 flags 0x02 dlen 7 #577 [hci0] 1.380203
+ ATT: Read Request (0x0a) len 2
+ Handle: 0x000f
+
+ < ACL Data TX: Handle 2048 flags 0x00 dlen 21 #579 [hci0] 1.380774
+ ATT: Read Response (0x0b) len 16
+ Value[16]: a470d508da8751a2a50b79da0250bfda
+
+The ``Handle`` in the request corresponds to a characteristic value
+handle from the discovery phase. btmon shows the raw value bytes; the
+interpretation depends on the characteristic UUID.
+
+Find By Type Value (Targeted Service Search)
+----------------------------------------------
+
+In addition to discovering all services, a client can search for a
+specific service UUID using ``Find By Type Value Request``::
+
+ > ACL Data RX: Handle 2048 flags 0x02 dlen 13 #513 [hci0] 0.124195
+ ATT: Find By Type Value Request (0x06) len 8
+ Handle range: 0x0001-0xffff
+ Attribute type: Primary Service (0x2800)
+ UUID: Generic Attribute Profile (0x1801)
+
+ < ACL Data TX: Handle 2048 flags 0x00 dlen 9 #515 [hci0] 0.124684
+ ATT: Find By Type Value Response (0x07) len 4
+ Handle range: 0x0008-0x0011
+
+This returns only the handle range for the matching service, without
+iterating through all services. If the service is not found::
+
+ < ACL Data TX: Handle 2048 flags 0x00 dlen 9 #524 [hci0] 0.240607
+ ATT: Error Response (0x01) len 4
+ Find By Type Value Request (0x06)
+ Handle: 0x0012
+ Error: Attribute Not Found (0x0a)
+
+Bidirectional Discovery
+------------------------
+
+Both devices in a connection can act as GATT client and server
+simultaneously. In a btsnoop trace, you may see interleaved discovery
+in both directions:
+
+- **TX (``<``) requests + RX (``>``) responses** -- The local device
+ (whose trace this is) is acting as a GATT client, discovering the
+ remote device's services.
+- **RX (``>``) requests + TX (``<``) responses** -- The remote device
+ is acting as a GATT client, discovering the local device's services.
+
+For example, the local server responding to the remote's discovery::
+
+ > ACL Data RX: Handle 2048 flags 0x02 dlen 11 #584 [hci0] 1.512006
+ ATT: Read By Group Type Request (0x10) len 6
+ Handle range: 0x0001-0xffff
+ Attribute group type: Primary Service (0x2800)
+
+ < ACL Data TX: Handle 2048 flags 0x00 dlen 66 #586 [hci0] 1.518778
+ ATT: Read By Group Type Response (0x11) len 61
+ Attribute data length: 6
+ Attribute group list: 10 entries
+ Handle range: 0x0001-0x0007
+ UUID: Generic Access Profile (0x1800)
+ Handle range: 0x0008-0x0011
+ UUID: Generic Attribute Profile (0x1801)
+ Handle range: 0x0012-0x0014
+ UUID: Device Information (0x180a)
+ Handle range: 0x0015-0x001e
+ UUID: Coordinated Set Identification (0x1846)
+ Handle range: 0x001f-0x0020
+ UUID: Common Audio (0x1853)
+ Handle range: 0x0021-0x0024
+ UUID: Microphone Control (0x184d)
+ Handle range: 0x0041-0x004b
+ UUID: Volume Control (0x1844)
+ Handle range: 0x006b-0x0073
+ UUID: Broadcast Audio Scan (0x184f)
+ Handle range: 0x0074-0x0086
+ UUID: Published Audio Capabilities (0x1850)
+ Handle range: 0x0087-0x0096
+ UUID: Audio Stream Control (0x184e)
+
+This shows the local device's own GATT database as seen by the remote.
+To reconstruct the remote device's database, focus on the TX requests
+and RX responses (the local device acting as client).
+
+Building the Attribute Table
+-----------------------------
+
+To reconstruct the GATT database, extract the discovery responses and
+organize them into a table. Using the trace above as an example, the
+remote device at address 00:11:22:33:44:55 has:
+
+**Services** (from Read By Group Type Response)::
+
+ Handle Range UUID Service Name
+ ────────────── ────────────────────────────── ────────────────────────────
+ 0x0001-0x0009 0x1800 Generic Access Profile
+ 0x000a-0x0011 0x1801 Generic Attribute Profile
+ 0x0012-0x0014 0x180a Device Information
+ 0x0015-0x0039 0x184c Generic Telephony Bearer
+ 0x003a-0x0059 0x1849 Generic Media Control
+ 0x005a-0x005c 0x1855 Telephony and Media Audio
+
+**Characteristics** (from Read By Type Response, within GAP 0x0001-0x0009)::
+
+ Handle Value Handle Properties UUID Name
+ ────── ──────────── ────────── ────── ────────────────────────────────
+ 0x0002 0x0003 Read 0x2a00 Device Name
+ 0x0004 0x0005 Read 0x2a01 Appearance
+ 0x0006 0x0007 Read 0x2a04 Peripheral Preferred Conn Params
+ 0x0008 0x0009 Read 0x2aa6 Central Address Resolution
+
+**Characteristics** (within GATT 0x000a-0x0011)::
+
+ Handle Value Handle Properties UUID Name
+ ────── ──────────── ─────────────── ────── ────────────────────────────
+ 0x000b 0x000c Indicate 0x2a05 Service Changed
+ 0x000e 0x000f Read, Write 0x2b29 Client Supported Features
+ 0x0010 0x0011 Read 0x2b2a Database Hash
+
+**Descriptors** (from Find Information Response)::
+
+ Handle UUID Name
+ ────── ────── ────────────────────────────────────
+ 0x000d 0x2902 Client Characteristic Configuration
+
+The CCC descriptor at handle 0x000d belongs to the Service Changed
+characteristic (0x000c), because it falls between that value handle
+and the next characteristic declaration at 0x000e.
+
diff --git a/doc/btmon.rst b/doc/btmon.rst
index 799066e83e74..c9e13c839026 100644
--- a/doc/btmon.rst
+++ b/doc/btmon.rst
@@ -712,422 +712,7 @@ Analyze mode reports, for each controller found in the trace:
- **Latency plots**: If ``gnuplot`` is installed, ASCII-art latency
distribution plots are rendered in the terminal.
-RECONSTRUCTING A GATT DATABASE FROM SNOOP TRACES
-=================================================
-
-A btsnoop trace contains the complete ATT protocol exchange used by
-GATT clients and servers to discover each other's services. By reading
-the discovery requests and responses, it is possible to reconstruct the
-full GATT database of a remote device -- even without access to the
-device itself.
-
-This section explains the GATT discovery procedure and how each ATT
-operation appears in ``btmon`` output.
-
-Overview of GATT Discovery
----------------------------
-
-GATT discovery is a multi-phase process where a client queries the
-server's attribute database using ATT protocol operations. The phases
-are:
-
-1. **Primary Service Discovery** -- Find all primary services and their
- handle ranges.
-2. **Secondary Service Discovery** -- Find any secondary (included-only)
- services.
-3. **Included Service Discovery** -- Find which services include other
- services.
-4. **Characteristic Discovery** -- Find all characteristics within each
- service.
-5. **Descriptor Discovery** -- Find all descriptors for each
- characteristic.
-6. **Characteristic Value Reading** -- Read the values of readable
- characteristics.
-
-Each phase uses a specific ATT operation and produces a
-request/response pattern in the trace. The client repeats each request
-with advancing handle ranges until the server responds with
-``Attribute Not Found``, indicating the end of that phase.
-
-Phase 1: Primary Service Discovery (Read By Group Type)
---------------------------------------------------------
-
-The client discovers primary services using ``Read By Group Type
-Request`` with the ``Primary Service`` UUID (0x2800) as the group type.
-
-**Request**::
-
- < ACL Data TX: Handle 2048 flags 0x00 dlen 11 #516 [hci0] 0.124726
- ATT: Read By Group Type Request (0x10) len 6
- Handle range: 0x0001-0xffff
- Attribute group type: Primary Service (0x2800)
-
-The first request always starts at handle 0x0001 and searches through
-0xffff (the entire handle space).
-
-**Response**::
-
- > ACL Data RX: Handle 2048 flags 0x02 dlen 42 #523 [hci0] 0.240151
- ATT: Read By Group Type Response (0x11) len 37
- Attribute data length: 6
- Attribute group list: 6 entries
- Handle range: 0x0001-0x0009
- UUID: Generic Access Profile (0x1800)
- Handle range: 0x000a-0x0011
- UUID: Generic Attribute Profile (0x1801)
- Handle range: 0x0012-0x0014
- UUID: Device Information (0x180a)
- Handle range: 0x0015-0x0039
- UUID: Generic Telephony Bearer (0x184c)
- Handle range: 0x003a-0x0059
- UUID: Generic Media Control (0x1849)
- Handle range: 0x005a-0x005c
- UUID: Telephony and Media Audio (0x1855)
-
-Each entry provides:
-
-- **Handle range** -- The start and end handle of the service. All
- attributes belonging to this service (characteristics, descriptors)
- have handles within this range.
-- **UUID** -- The service UUID. Standard 16-bit UUIDs are shown with
- their name (e.g., ``Generic Access Profile``). 128-bit vendor-specific
- UUIDs appear as full UUID strings.
-
-The client continues by sending another request starting after the last
-handle in the response::
-
- < ACL Data TX: Handle 2048 flags 0x00 dlen 11 #525 [hci0] 0.240641
- ATT: Read By Group Type Request (0x10) len 6
- Handle range: 0x005d-0xffff
- Attribute group type: Primary Service (0x2800)
-
-This continues until the server responds with ``Attribute Not Found``::
-
- > ACL Data RX: Handle 2048 flags 0x02 dlen 9 #532 [hci0] 0.360069
- ATT: Error Response (0x01) len 4
- Read By Group Type Request (0x10)
- Handle: 0x005d
- Error: Attribute Not Found (0x0a)
-
-This error indicates that no more primary services exist beyond handle
-0x005d. The client now has the complete list of primary services.
-
-.. note::
-
- The ``Attribute data length`` field indicates the size of each entry
- in the response. A value of 6 means 16-bit UUIDs (2 bytes start
- handle + 2 bytes end handle + 2 bytes UUID). A value of 20 means
- 128-bit UUIDs (2 + 2 + 16). If the server has both 16-bit and
- 128-bit service UUIDs, they are returned in separate responses
- because all entries in a single response must have the same length.
-
-Phase 2: Secondary Service Discovery
---------------------------------------
-
-After primary services, the client may discover secondary services
-using the same ``Read By Group Type Request`` but with the ``Secondary
-Service`` UUID (0x2801)::
-
- < ACL Data TX: Handle 2048 flags 0x00 dlen 11 #534 [hci0] 0.360752
- ATT: Read By Group Type Request (0x10) len 6
- Handle range: 0x0001-0xffff
- Attribute group type: Secondary Service (0x2801)
-
-If no secondary services exist, the server responds with
-``Attribute Not Found``. Secondary services are not directly accessible
-to clients -- they are only reachable via include references from
-primary services.
-
-Phase 3: Included Service Discovery (Read By Type)
-----------------------------------------------------
-
-To discover which services include other services, the client uses
-``Read By Type Request`` with the ``Include`` UUID (0x2802)::
-
- < ACL Data TX: Handle 2048 flags 0x00 dlen 11 #540 [hci0] 0.480731
- ATT: Read By Type Request (0x08) len 6
- Handle range: 0x0001-0x005c
- Attribute type: Include (0x2802)
-
-The handle range typically spans the entire discovered database. Each
-include declaration in the response identifies a service that is
-included by the service containing that handle.
-
-Phase 4: Characteristic Discovery (Read By Type)
---------------------------------------------------
-
-For each service, the client discovers its characteristics using
-``Read By Type Request`` with the ``Characteristic`` UUID (0x2803).
-The handle range is limited to the service's handle range.
-
-**Request**::
-
- > ACL Data RX: Handle 2048 flags 0x02 dlen 11 #531 [hci0] 0.360063
- ATT: Read By Type Request (0x08) len 6
- Handle range: 0x0008-0x0011
- Attribute type: Characteristic (0x2803)
-
-**Response**::
-
- < ACL Data TX: Handle 2048 flags 0x00 dlen 27 #533 [hci0] 0.360714
- ATT: Read By Type Response (0x09) len 22
- Attribute data length: 7
- Attribute data list: 3 entries
- Handle: 0x0009
- Value[5]: 200a00052a
- Properties: 0x20
- Indicate (0x20)
- Value Handle: 0x000a
- Value UUID: Service Changed (0x2a05)
- Handle: 0x000c
- Value[5]: 0a0d00292b
- Properties: 0x0a
- Read (0x02)
- Write (0x08)
- Value Handle: 0x000d
- Value UUID: Client Supported Features (0x2b29)
- Handle: 0x000e
- Value[5]: 020f002a2b
- Properties: 0x02
- Read (0x02)
- Value Handle: 0x000f
- Value UUID: Database Hash (0x2b2a)
-
-Each characteristic entry provides:
-
-- **Handle** -- The handle of the characteristic declaration attribute.
-- **Properties** -- A bitmask indicating supported operations:
-
- .. list-table::
- :header-rows: 1
- :widths: 10 30 60
-
- * - Bit
- - Property
- - Description
- * - 0x01
- - Broadcast
- - Can be broadcast in advertising data
- * - 0x02
- - Read
- - Can be read
- * - 0x04
- - Write Without Response
- - Can be written without acknowledgment
- * - 0x08
- - Write
- - Can be written with acknowledgment
- * - 0x10
- - Notify
- - Server can send notifications
- * - 0x20
- - Indicate
- - Server can send indications
- * - 0x40
- - Authenticated Signed Writes
- - Supports signed write commands
- * - 0x80
- - Extended Properties
- - Has extended properties descriptor
-
-- **Value Handle** -- The handle where the characteristic's value is
- stored (always declaration handle + 1).
-- **Value UUID** -- The UUID identifying the characteristic type.
-
-The client continues with advancing handle ranges until it receives
-``Attribute Not Found``::
-
- > ACL Data RX: Handle 2048 flags 0x02 dlen 9 #572 [hci0] 1.200228
- ATT: Error Response (0x01) len 4
- Read By Type Request (0x08)
- Handle: 0x005c
- Error: Attribute Not Found (0x0a)
-
-Phase 5: Descriptor Discovery (Find Information)
---------------------------------------------------
-
-Descriptors occupy the handles between a characteristic's value handle
-and the next characteristic declaration (or end of service). The client
-discovers them using ``Find Information Request``.
-
-**Request**::
-
- > ACL Data RX: Handle 2048 flags 0x02 dlen 9 #556 [hci0] 0.959965
- ATT: Find Information Request (0x04) len 4
- Handle range: 0x000b-0x000b
-
-The handle range covers the gap between the characteristic value handle
-and the next characteristic declaration handle.
-
-**Response**::
-
- < ACL Data TX: Handle 2048 flags 0x00 dlen 10 #561 [hci0] 0.961049
- ATT: Find Information Response (0x05) len 5
- Format: UUID-16 (0x01)
- Handle: 0x000b
- UUID: Client Characteristic Configuration (0x2902)
-
-Common descriptor UUIDs:
-
-.. list-table::
- :header-rows: 1
- :widths: 15 40 45
-
- * - UUID
- - Name
- - Purpose
- * - 0x2900
- - Characteristic Extended Properties
- - Additional property bits
- * - 0x2901
- - Characteristic User Description
- - Human-readable description string
- * - 0x2902
- - Client Characteristic Configuration (CCC)
- - Enable/disable notifications or indications
- * - 0x2903
- - Server Characteristic Configuration
- - Server-side broadcast configuration
- * - 0x2904
- - Characteristic Presentation Format
- - Data format, exponent, unit
-
-Phase 6: Reading Characteristic Values
-----------------------------------------
-
-After discovery, the client may read characteristic values using
-``Read Request``::
-
- > ACL Data RX: Handle 2048 flags 0x02 dlen 7 #577 [hci0] 1.380203
- ATT: Read Request (0x0a) len 2
- Handle: 0x000f
-
- < ACL Data TX: Handle 2048 flags 0x00 dlen 21 #579 [hci0] 1.380774
- ATT: Read Response (0x0b) len 16
- Value[16]: a470d508da8751a2a50b79da0250bfda
-
-The ``Handle`` in the request corresponds to a characteristic value
-handle from the discovery phase. btmon shows the raw value bytes; the
-interpretation depends on the characteristic UUID.
-
-Find By Type Value (Targeted Service Search)
-----------------------------------------------
-
-In addition to discovering all services, a client can search for a
-specific service UUID using ``Find By Type Value Request``::
-
- > ACL Data RX: Handle 2048 flags 0x02 dlen 13 #513 [hci0] 0.124195
- ATT: Find By Type Value Request (0x06) len 8
- Handle range: 0x0001-0xffff
- Attribute type: Primary Service (0x2800)
- UUID: Generic Attribute Profile (0x1801)
-
- < ACL Data TX: Handle 2048 flags 0x00 dlen 9 #515 [hci0] 0.124684
- ATT: Find By Type Value Response (0x07) len 4
- Handle range: 0x0008-0x0011
-
-This returns only the handle range for the matching service, without
-iterating through all services. If the service is not found::
-
- < ACL Data TX: Handle 2048 flags 0x00 dlen 9 #524 [hci0] 0.240607
- ATT: Error Response (0x01) len 4
- Find By Type Value Request (0x06)
- Handle: 0x0012
- Error: Attribute Not Found (0x0a)
-
-Bidirectional Discovery
-------------------------
-
-Both devices in a connection can act as GATT client and server
-simultaneously. In a btsnoop trace, you may see interleaved discovery
-in both directions:
-
-- **TX (``<``) requests + RX (``>``) responses** -- The local device
- (whose trace this is) is acting as a GATT client, discovering the
- remote device's services.
-- **RX (``>``) requests + TX (``<``) responses** -- The remote device
- is acting as a GATT client, discovering the local device's services.
-
-For example, the local server responding to the remote's discovery::
-
- > ACL Data RX: Handle 2048 flags 0x02 dlen 11 #584 [hci0] 1.512006
- ATT: Read By Group Type Request (0x10) len 6
- Handle range: 0x0001-0xffff
- Attribute group type: Primary Service (0x2800)
-
- < ACL Data TX: Handle 2048 flags 0x00 dlen 66 #586 [hci0] 1.518778
- ATT: Read By Group Type Response (0x11) len 61
- Attribute data length: 6
- Attribute group list: 10 entries
- Handle range: 0x0001-0x0007
- UUID: Generic Access Profile (0x1800)
- Handle range: 0x0008-0x0011
- UUID: Generic Attribute Profile (0x1801)
- Handle range: 0x0012-0x0014
- UUID: Device Information (0x180a)
- Handle range: 0x0015-0x001e
- UUID: Coordinated Set Identification (0x1846)
- Handle range: 0x001f-0x0020
- UUID: Common Audio (0x1853)
- Handle range: 0x0021-0x0024
- UUID: Microphone Control (0x184d)
- Handle range: 0x0041-0x004b
- UUID: Volume Control (0x1844)
- Handle range: 0x006b-0x0073
- UUID: Broadcast Audio Scan (0x184f)
- Handle range: 0x0074-0x0086
- UUID: Published Audio Capabilities (0x1850)
- Handle range: 0x0087-0x0096
- UUID: Audio Stream Control (0x184e)
-
-This shows the local device's own GATT database as seen by the remote.
-To reconstruct the remote device's database, focus on the TX requests
-and RX responses (the local device acting as client).
-
-Building the Attribute Table
------------------------------
-
-To reconstruct the GATT database, extract the discovery responses and
-organize them into a table. Using the trace above as an example, the
-remote device at address 00:11:22:33:44:55 has:
-
-**Services** (from Read By Group Type Response)::
-
- Handle Range UUID Service Name
- ────────────── ────────────────────────────── ────────────────────────────
- 0x0001-0x0009 0x1800 Generic Access Profile
- 0x000a-0x0011 0x1801 Generic Attribute Profile
- 0x0012-0x0014 0x180a Device Information
- 0x0015-0x0039 0x184c Generic Telephony Bearer
- 0x003a-0x0059 0x1849 Generic Media Control
- 0x005a-0x005c 0x1855 Telephony and Media Audio
-
-**Characteristics** (from Read By Type Response, within GAP 0x0001-0x0009)::
-
- Handle Value Handle Properties UUID Name
- ────── ──────────── ────────── ────── ────────────────────────────────
- 0x0002 0x0003 Read 0x2a00 Device Name
- 0x0004 0x0005 Read 0x2a01 Appearance
- 0x0006 0x0007 Read 0x2a04 Peripheral Preferred Conn Params
- 0x0008 0x0009 Read 0x2aa6 Central Address Resolution
-
-**Characteristics** (within GATT 0x000a-0x0011)::
-
- Handle Value Handle Properties UUID Name
- ────── ──────────── ─────────────── ────── ────────────────────────────
- 0x000b 0x000c Indicate 0x2a05 Service Changed
- 0x000e 0x000f Read, Write 0x2b29 Client Supported Features
- 0x0010 0x0011 Read 0x2b2a Database Hash
-
-**Descriptors** (from Find Information Response)::
-
- Handle UUID Name
- ────── ────── ────────────────────────────────────
- 0x000d 0x2902 Client Characteristic Configuration
-
-The CCC descriptor at handle 0x000d belongs to the Service Changed
-characteristic (0x000c), because it falls between that value handle
-and the next characteristic declaration at 0x000e.
+.. include:: btmon-gatt.rst
.. include:: btmon-smp.rst
--
2.53.0
^ permalink raw reply related [flat|nested] 7+ messages in thread
* [PATCH BlueZ v1 6/6] doc/btmon: Split Connection Tracking into btmon-connections.rst
2026-03-12 17:15 [PATCH BlueZ v1 1/6] doc/btmon: Split Advertising and Scanning into btmon-advertising.rst Luiz Augusto von Dentz
` (3 preceding siblings ...)
2026-03-12 17:15 ` [PATCH BlueZ v1 5/6] doc/btmon: Split GATT Database Reconstruction into btmon-gatt.rst Luiz Augusto von Dentz
@ 2026-03-12 17:15 ` Luiz Augusto von Dentz
2026-03-12 18:00 ` [BlueZ,v1,1/6] doc/btmon: Split Advertising and Scanning into btmon-advertising.rst bluez.test.bot
5 siblings, 0 replies; 7+ messages in thread
From: Luiz Augusto von Dentz @ 2026-03-12 17:15 UTC (permalink / raw)
To: linux-bluetooth
From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
Move the CONNECTION TRACKING and HCI ERROR AND DISCONNECT REASON CODES
sections into a standalone file and replace them with an RST include
directive.
---
doc/btmon-connections.rst | 146 ++++++++++++++++++++++++++++++++++++++
doc/btmon.rst | 141 +-----------------------------------
2 files changed, 147 insertions(+), 140 deletions(-)
create mode 100644 doc/btmon-connections.rst
diff --git a/doc/btmon-connections.rst b/doc/btmon-connections.rst
new file mode 100644
index 000000000000..eb6a88ceadbd
--- /dev/null
+++ b/doc/btmon-connections.rst
@@ -0,0 +1,146 @@
+==============================
+btmon: Connection Tracking
+==============================
+
+.. This file is included by btmon.rst.
+
+CONNECTION TRACKING
+===================
+
+HCI uses **connection handles** (16-bit integers) to identify individual
+connections. Understanding how handles map to devices is essential for
+reading traces.
+
+Handle Types
+------------
+
+Different connection types use different handle ranges, but these ranges
+are controller-specific and not standardized. The connection type can be
+determined by looking at the event that created the handle:
+
+.. list-table::
+ :header-rows: 1
+ :widths: 15 25 60
+
+ * - Type
+ - Creation Event
+ - Description
+ * - BR/EDR ACL
+ - Connection Complete
+ - Classic Bluetooth data connection
+ * - LE ACL
+ - LE (Enhanced) Connection Complete
+ - Low Energy data connection
+ * - CIS
+ - LE CIS Established
+ - Connected Isochronous Stream (LE Audio)
+ * - BIS
+ - LE BIG Complete
+ - Broadcast Isochronous Stream (LE Audio)
+ * - SCO/eSCO
+ - Synchronous Connection Complete
+ - Voice/audio synchronous connection (classic)
+
+A single device may have multiple handles simultaneously. For example,
+an LE Audio device will have an LE ACL handle for control traffic and
+one or more CIS handles for audio streams. The ``LE CIS Established``
+event includes the ACL connection handle that the CIS is associated
+with.
+
+Controller Buffer Tracking
+--------------------------
+
+Buffer tracking may show a indicator in square brackets::
+
+ < ACL: Handle 2048 [1/6] flags 0x00 dlen 16
+
+The ``[1/6]`` means this is buffer slot 1 of 6 available controller
+ACL buffers. This reflects the host-side HCI flow control: the host
+tracks how many buffers the controller has available and shows the
+current usage. When the controller sends ``Number of Completed Packets``
+events, buffers are freed and the count decreases.
+
+HCI ERROR AND DISCONNECT REASON CODES
+======================================
+
+HCI status and disconnect reason codes use the same code space. These
+appear in ``Status:`` and ``Reason:`` fields throughout the trace.
+btmon decodes them automatically, but the hex values are useful for
+searching and filtering.
+
+Common Disconnect Reasons
+-------------------------
+
+.. list-table::
+ :header-rows: 1
+ :widths: 8 40 52
+
+ * - Code
+ - Name
+ - Diagnostic Meaning
+ * - 0x05
+ - Authentication Failure
+ - Pairing or encryption setup failed. Key may be
+ stale or devices have mismatched security databases.
+ * - 0x08
+ - Connection Timeout
+ - The supervision timer expired. The remote device
+ moved out of range or stopped responding. This is
+ an RF link loss.
+ * - 0x13
+ - Remote User Terminated Connection
+ - The remote device intentionally disconnected.
+ This is the normal graceful disconnect.
+ * - 0x14
+ - Remote Device Terminated due to Low Resources
+ - The remote device ran out of resources (memory,
+ connection slots).
+ * - 0x15
+ - Remote Device Terminated due to Power Off
+ - The remote device is powering down.
+ * - 0x16
+ - Connection Terminated By Local Host
+ - The local BlueZ stack intentionally disconnected.
+ Normal when bluetoothd initiates disconnect.
+ * - 0x1f
+ - Unspecified Error
+ - Generic error. Often indicates a firmware issue.
+ * - 0x22
+ - LMP/LL Response Timeout
+ - Link layer procedure timed out. The remote device
+ stopped responding to LL control PDUs.
+ * - 0x28
+ - Instant Passed
+ - A timing-critical operation missed its deadline.
+ Often seen with connection parameter updates.
+ * - 0x2f
+ - Insufficient Security
+ - The required security level (encryption, MITM
+ protection) was not met.
+ * - 0x3b
+ - Unacceptable Connection Parameters
+ - The remote rejected a connection parameter update.
+ * - 0x3d
+ - Connection Terminated due to MIC Failure
+ - Encryption integrity check failed. Possible key
+ mismatch or corruption.
+ * - 0x3e
+ - Connection Failed to be Established
+ - Connection attempt failed entirely (e.g., the
+ remote device did not respond to connection
+ requests).
+ * - 0x3f
+ - MAC Connection Failed
+ - MAC-level connection failure.
+ * - 0x44
+ - Operation Cancelled by Host
+ - The host cancelled the operation before it
+ completed.
+
+Full Error Code Table
+---------------------
+
+The complete set of HCI error codes (0x00-0x45) is defined in the
+Bluetooth Core Specification, Volume 1, Part F. btmon decodes all
+of them automatically in ``Status:`` and ``Reason:`` fields. The
+source mapping is in ``monitor/packet.c`` (``error2str_table``).
diff --git a/doc/btmon.rst b/doc/btmon.rst
index c9e13c839026..7668bcc5a9c4 100644
--- a/doc/btmon.rst
+++ b/doc/btmon.rst
@@ -534,146 +534,7 @@ The kernel forwarded this as a MGMT Device Connected event. bluetoothd
logged its ``connected_callback()``. Then data exchange began -- an L2CAP
parameter update and ATT MTU negotiation over the new ACL connection.
-CONNECTION TRACKING
-===================
-
-HCI uses **connection handles** (16-bit integers) to identify individual
-connections. Understanding how handles map to devices is essential for
-reading traces.
-
-Handle Types
-------------
-
-Different connection types use different handle ranges, but these ranges
-are controller-specific and not standardized. The connection type can be
-determined by looking at the event that created the handle:
-
-.. list-table::
- :header-rows: 1
- :widths: 15 25 60
-
- * - Type
- - Creation Event
- - Description
- * - BR/EDR ACL
- - Connection Complete
- - Classic Bluetooth data connection
- * - LE ACL
- - LE (Enhanced) Connection Complete
- - Low Energy data connection
- * - CIS
- - LE CIS Established
- - Connected Isochronous Stream (LE Audio)
- * - BIS
- - LE BIG Complete
- - Broadcast Isochronous Stream (LE Audio)
- * - SCO/eSCO
- - Synchronous Connection Complete
- - Voice/audio synchronous connection (classic)
-
-A single device may have multiple handles simultaneously. For example,
-an LE Audio device will have an LE ACL handle for control traffic and
-one or more CIS handles for audio streams. The ``LE CIS Established``
-event includes the ACL connection handle that the CIS is associated
-with.
-
-Controller Buffer Tracking
---------------------------
-
-Buffer tracking may show a indicator in square brackets::
-
- < ACL: Handle 2048 [1/6] flags 0x00 dlen 16
-
-The ``[1/6]`` means this is buffer slot 1 of 6 available controller
-ACL buffers. This reflects the host-side HCI flow control: the host
-tracks how many buffers the controller has available and shows the
-current usage. When the controller sends ``Number of Completed Packets``
-events, buffers are freed and the count decreases.
-
-HCI ERROR AND DISCONNECT REASON CODES
-======================================
-
-HCI status and disconnect reason codes use the same code space. These
-appear in ``Status:`` and ``Reason:`` fields throughout the trace.
-btmon decodes them automatically, but the hex values are useful for
-searching and filtering.
-
-Common Disconnect Reasons
--------------------------
-
-.. list-table::
- :header-rows: 1
- :widths: 8 40 52
-
- * - Code
- - Name
- - Diagnostic Meaning
- * - 0x05
- - Authentication Failure
- - Pairing or encryption setup failed. Key may be
- stale or devices have mismatched security databases.
- * - 0x08
- - Connection Timeout
- - The supervision timer expired. The remote device
- moved out of range or stopped responding. This is
- an RF link loss.
- * - 0x13
- - Remote User Terminated Connection
- - The remote device intentionally disconnected.
- This is the normal graceful disconnect.
- * - 0x14
- - Remote Device Terminated due to Low Resources
- - The remote device ran out of resources (memory,
- connection slots).
- * - 0x15
- - Remote Device Terminated due to Power Off
- - The remote device is powering down.
- * - 0x16
- - Connection Terminated By Local Host
- - The local BlueZ stack intentionally disconnected.
- Normal when bluetoothd initiates disconnect.
- * - 0x1f
- - Unspecified Error
- - Generic error. Often indicates a firmware issue.
- * - 0x22
- - LMP/LL Response Timeout
- - Link layer procedure timed out. The remote device
- stopped responding to LL control PDUs.
- * - 0x28
- - Instant Passed
- - A timing-critical operation missed its deadline.
- Often seen with connection parameter updates.
- * - 0x2f
- - Insufficient Security
- - The required security level (encryption, MITM
- protection) was not met.
- * - 0x3b
- - Unacceptable Connection Parameters
- - The remote rejected a connection parameter update.
- * - 0x3d
- - Connection Terminated due to MIC Failure
- - Encryption integrity check failed. Possible key
- mismatch or corruption.
- * - 0x3e
- - Connection Failed to be Established
- - Connection attempt failed entirely (e.g., the
- remote device did not respond to connection
- requests).
- * - 0x3f
- - MAC Connection Failed
- - MAC-level connection failure.
- * - 0x44
- - Operation Cancelled by Host
- - The host cancelled the operation before it
- completed.
-
-Full Error Code Table
----------------------
-
-The complete set of HCI error codes (0x00-0x45) is defined in the
-Bluetooth Core Specification, Volume 1, Part F. btmon decodes all
-of them automatically in ``Status:`` and ``Reason:`` fields. The
-source mapping is in ``monitor/packet.c`` (``error2str_table``).
+.. include:: btmon-connections.rst
ANALYZE MODE
============
--
2.53.0
^ permalink raw reply related [flat|nested] 7+ messages in thread
* RE: [BlueZ,v1,1/6] doc/btmon: Split Advertising and Scanning into btmon-advertising.rst
2026-03-12 17:15 [PATCH BlueZ v1 1/6] doc/btmon: Split Advertising and Scanning into btmon-advertising.rst Luiz Augusto von Dentz
` (4 preceding siblings ...)
2026-03-12 17:15 ` [PATCH BlueZ v1 6/6] doc/btmon: Split Connection Tracking into btmon-connections.rst Luiz Augusto von Dentz
@ 2026-03-12 18:00 ` bluez.test.bot
5 siblings, 0 replies; 7+ messages in thread
From: bluez.test.bot @ 2026-03-12 18:00 UTC (permalink / raw)
To: linux-bluetooth, luiz.dentz
[-- Attachment #1: Type: text/plain, Size: 35697 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=1065807
---Test result---
Test Summary:
CheckPatch PENDING 0.40 seconds
GitLint PENDING 0.39 seconds
BuildEll PASS 21.16 seconds
BluezMake FAIL 591.71 seconds
MakeCheck FAIL 208.15 seconds
MakeDistcheck FAIL 14.03 seconds
CheckValgrind FAIL 186.29 seconds
CheckSmatch FAIL 284.69 seconds
bluezmakeextell FAIL 163.58 seconds
IncrementalBuild PENDING 0.40 seconds
ScanBuild FAIL 341.97 seconds
Details
##############################
Test: CheckPatch - PENDING
Desc: Run checkpatch.pl script
Output:
##############################
Test: GitLint - PENDING
Desc: Run gitlint
Output:
##############################
Test: BluezMake - FAIL
Desc: Build BlueZ
Output:
tools/mgmt-tester.c: In function ‘main’:
tools/mgmt-tester.c:12984:5: note: variable tracking size limit exceeded with ‘-fvar-tracking-assignments’, retrying without
12984 | int main(int argc, char *argv[])
| ^~~~
unit/test-avdtp.c: In function ‘main’:
unit/test-avdtp.c:766:5: note: variable tracking size limit exceeded with ‘-fvar-tracking-assignments’, retrying without
766 | int main(int argc, char *argv[])
| ^~~~
unit/test-avrcp.c: In function ‘main’:
unit/test-avrcp.c:989:5: note: variable tracking size limit exceeded with ‘-fvar-tracking-assignments’, retrying without
989 | int main(int argc, char *argv[])
| ^~~~
doc/btmon-connections.rst:7: (SEVERE/4) Title level inconsistent:
CONNECTION TRACKING
===================
Exiting due to level-4 (SEVERE) system message.
make[1]: *** [Makefile:12381: doc/btmon.1] Error 1
make[1]: *** Waiting for unfinished jobs....
make: *** [Makefile:4227: all] Error 2
##############################
Test: MakeCheck - FAIL
Desc: Run Bluez Make Check
Output:
doc/btmon-connections.rst:7: (SEVERE/4) Title level inconsistent:
CONNECTION TRACKING
===================
Exiting due to level-4 (SEVERE) system message.
make[1]: *** [Makefile:12381: doc/btmon.1] Error 1
make: *** [Makefile:10909: check] Error 2
##############################
Test: MakeDistcheck - FAIL
Desc: Run Bluez Make Distcheck
Output:
doc/btmon-connections.rst:7: (SEVERE/4) Title level inconsistent:
CONNECTION TRACKING
===================
Exiting due to level-4 (SEVERE) system message.
make[2]: *** [Makefile:12381: doc/btmon.1] Error 1
make[2]: *** Waiting for unfinished jobs....
make[1]: *** [Makefile:10742: distdir] Error 2
make: *** [Makefile:10818: dist] Error 2
##############################
Test: CheckValgrind - FAIL
Desc: Run Bluez Make Check with Valgrind
Output:
tools/mgmt-tester.c: In function ‘main’:
tools/mgmt-tester.c:12984:5: note: variable tracking size limit exceeded with ‘-fvar-tracking-assignments’, retrying without
12984 | int main(int argc, char *argv[])
| ^~~~
doc/btmon-connections.rst:7: (SEVERE/4) Title level inconsistent:
CONNECTION TRACKING
===================
Exiting due to level-4 (SEVERE) system message.
make[1]: *** [Makefile:12381: doc/btmon.1] Error 1
make[1]: *** Waiting for unfinished jobs....
make: *** [Makefile:10909: check] Error 2
##############################
Test: CheckSmatch - FAIL
Desc: Run smatch tool with source
Output:
src/shared/crypto.c:271:21: warning: Variable length array is used.
src/shared/crypto.c:272:23: warning: Variable length array is used.
src/shared/gatt-helpers.c:768:31: warning: Variable length array is used.
src/shared/gatt-helpers.c:846:31: warning: Variable length array is used.
src/shared/gatt-helpers.c:1339:31: warning: Variable length array is used.
src/shared/gatt-helpers.c:1370:23: warning: Variable length array is used.
src/shared/gatt-server.c:278:25: warning: Variable length array is used.
src/shared/gatt-server.c:618:25: warning: Variable length array is used.
src/shared/gatt-server.c:716:25: warning: Variable length array is used.
src/shared/bap.c:312:25: warning: array of flexible structures
src/shared/bap.c: note: in included file:
./src/shared/ascs.h:88:25: warning: array of flexible structures
src/shared/shell.c: note: in included file (through /usr/include/readline/readline.h):
/usr/include/readline/rltypedefs.h:35:23: warning: non-ANSI function declaration of function 'Function'
/usr/include/readline/rltypedefs.h:36:25: warning: non-ANSI function declaration of function 'VFunction'
/usr/include/readline/rltypedefs.h:37:27: warning: non-ANSI function declaration of function 'CPFunction'
/usr/include/readline/rltypedefs.h:38:29: warning: non-ANSI function declaration of function 'CPPFunction'
src/shared/crypto.c:271:21: warning: Variable length array is used.
src/shared/crypto.c:272:23: warning: Variable length array is used.
src/shared/gatt-helpers.c:768:31: warning: Variable length array is used.
src/shared/gatt-helpers.c:846:31: warning: Variable length array is used.
src/shared/gatt-helpers.c:1339:31: warning: Variable length array is used.
src/shared/gatt-helpers.c:1370:23: warning: Variable length array is used.
src/shared/gatt-server.c:278:25: warning: Variable length array is used.
src/shared/gatt-server.c:618:25: warning: Variable length array is used.
src/shared/gatt-server.c:716:25: warning: Variable length array is used.
src/shared/bap.c:312:25: warning: array of flexible structures
src/shared/bap.c: note: in included file:
./src/shared/ascs.h:88:25: warning: array of flexible structures
src/shared/shell.c: note: in included file (through /usr/include/readline/readline.h):
/usr/include/readline/rltypedefs.h:35:23: warning: non-ANSI function declaration of function 'Function'
/usr/include/readline/rltypedefs.h:36:25: warning: non-ANSI function declaration of function 'VFunction'
/usr/include/readline/rltypedefs.h:37:27: warning: non-ANSI function declaration of function 'CPFunction'
/usr/include/readline/rltypedefs.h:38:29: warning: non-ANSI function declaration of function 'CPPFunction'
tools/mesh-cfgtest.c:1453:17: warning: unknown escape sequence: '\%'
tools/sco-tester.c: note: in included file:
./lib/bluetooth/bluetooth.h:232:15: warning: array of flexible structures
./lib/bluetooth/bluetooth.h:237:31: warning: array of flexible structures
tools/bneptest.c:634:39: warning: unknown escape sequence: '\%'
tools/seq2bseq.c:57:26: warning: Variable length array is used.
tools/obex-client-tool.c: note: in included file (through /usr/include/readline/readline.h):
/usr/include/readline/rltypedefs.h:35:23: warning: non-ANSI function declaration of function 'Function'
/usr/include/readline/rltypedefs.h:36:25: warning: non-ANSI function declaration of function 'VFunction'
/usr/include/readline/rltypedefs.h:37:27: warning: non-ANSI function declaration of function 'CPFunction'
/usr/include/readline/rltypedefs.h:38:29: warning: non-ANSI function declaration of function 'CPPFunction'
client/btpclient/gatt.c: note: in included file:
./src/shared/btp.h:309:42: warning: array of flexible structures
src/advertising.c: note: in included file:
./src/shared/mgmt.h:95:25: error: redefinition of unsigned int enum mgmt_io_capability
src/adv_monitor.c: note: in included file:
./src/shared/mgmt.h:95:25: error: redefinition of unsigned int enum mgmt_io_capability
unit/avctp.c:505:34: warning: Variable length array is used.
unit/avctp.c:556:34: warning: Variable length array is used.
unit/test-avrcp.c:373:26: warning: Variable length array is used.
unit/test-avrcp.c:398:26: warning: Variable length array is used.
unit/test-avrcp.c:414:24: warning: Variable length array is used.
unit/avrcp-lib.c:1085:34: warning: Variable length array is used.
unit/avrcp-lib.c:1583:34: warning: Variable length array is used.
unit/avrcp-lib.c:1612:34: warning: Variable length array is used.
unit/avrcp-lib.c:1638:34: warning: Variable length array is used.
src/advertising.c: note: in included file:
./src/shared/mgmt.h:95:25: error: redefinition of unsigned int enum mgmt_io_capability
src/adv_monitor.c: note: in included file:
./src/shared/mgmt.h:95:25: error: redefinition of unsigned int enum mgmt_io_capability
mesh/mesh-io-mgmt.c:525:67: warning: Variable length array is used.
doc/btmon-connections.rst:7: (SEVERE/4) Title level inconsistent:
CONNECTION TRACKING
===================
Exiting due to level-4 (SEVERE) system message.
make[1]: *** [Makefile:12381: doc/btmon.1] Error 1
make[1]: *** Waiting for unfinished jobs....
make: *** [Makefile:4227: all] Error 2
##############################
Test: bluezmakeextell - FAIL
Desc: Build Bluez with External ELL
Output:
doc/btmon-connections.rst:7: (SEVERE/4) Title level inconsistent:
CONNECTION TRACKING
===================
Exiting due to level-4 (SEVERE) system message.
make[1]: *** [Makefile:12381: doc/btmon.1] Error 1
make[1]: *** Waiting for unfinished jobs....
make: *** [Makefile:4227: all] Error 2
##############################
Test: IncrementalBuild - PENDING
Desc: Incremental build with the patches in the series
Output:
##############################
Test: ScanBuild - FAIL
Desc: Run Scan Build
Output:
src/shared/gatt-client.c:455:21: warning: Use of memory after it is freed
gatt_db_unregister(op->client->db, op->db_id);
^~~~~~~~~~
src/shared/gatt-client.c:700:2: warning: Use of memory after it is freed
discovery_op_complete(op, false, att_ecode);
^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
src/shared/gatt-client.c:1000:2: warning: Use of memory after it is freed
discovery_op_complete(op, success, att_ecode);
^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
src/shared/gatt-client.c:1106:2: warning: Use of memory after it is freed
discovery_op_complete(op, success, att_ecode);
^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
src/shared/gatt-client.c:1300:2: warning: Use of memory after it is freed
discovery_op_complete(op, success, att_ecode);
^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
src/shared/gatt-client.c:1365:2: warning: Use of memory after it is freed
discovery_op_complete(op, success, att_ecode);
^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
src/shared/gatt-client.c:1640:6: warning: Use of memory after it is freed
if (read_db_hash(op)) {
^~~~~~~~~~~~~~~~
src/shared/gatt-client.c:1645:2: warning: Use of memory after it is freed
discover_all(op);
^~~~~~~~~~~~~~~~
src/shared/gatt-client.c:1701:56: warning: Use of memory after it is freed
notify_data->chrc->ccc_write_id = notify_data->att_id = att_id;
~~~~~~~~~~~~~~~~~~~ ^
src/shared/gatt-client.c:2154:6: warning: Use of memory after it is freed
if (read_db_hash(op)) {
^~~~~~~~~~~~~~~~
src/shared/gatt-client.c:2162:8: warning: Use of memory after it is freed
discovery_op_ref(op),
^~~~~~~~~~~~~~~~~~~~
src/shared/gatt-client.c:3340:2: warning: Use of memory after it is freed
complete_write_long_op(req, success, 0, false);
^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
src/shared/gatt-client.c:3362:2: warning: Use of memory after it is freed
request_unref(req);
^~~~~~~~~~~~~~~~~~
13 warnings generated.
src/shared/bap.c:1529:8: warning: Use of memory after it is freed
bap = bt_bap_ref_safe(bap);
^~~~~~~~~~~~~~~~~~~~
src/shared/bap.c:2340:20: warning: Use of memory after it is freed
return queue_find(stream->bap->streams, NULL, stream);
^~~~~~~~~~~~~~~~~~~~
2 warnings generated.
src/shared/gatt-client.c:455:21: warning: Use of memory after it is freed
gatt_db_unregister(op->client->db, op->db_id);
^~~~~~~~~~
src/shared/gatt-client.c:700:2: warning: Use of memory after it is freed
discovery_op_complete(op, false, att_ecode);
^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
src/shared/gatt-client.c:1000:2: warning: Use of memory after it is freed
discovery_op_complete(op, success, att_ecode);
^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
src/shared/gatt-client.c:1106:2: warning: Use of memory after it is freed
discovery_op_complete(op, success, att_ecode);
^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
src/shared/gatt-client.c:1300:2: warning: Use of memory after it is freed
discovery_op_complete(op, success, att_ecode);
^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
src/shared/gatt-client.c:1365:2: warning: Use of memory after it is freed
discovery_op_complete(op, success, att_ecode);
^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
src/shared/gatt-client.c:1640:6: warning: Use of memory after it is freed
if (read_db_hash(op)) {
^~~~~~~~~~~~~~~~
src/shared/gatt-client.c:1645:2: warning: Use of memory after it is freed
discover_all(op);
^~~~~~~~~~~~~~~~
src/shared/gatt-client.c:1701:56: warning: Use of memory after it is freed
notify_data->chrc->ccc_write_id = notify_data->att_id = att_id;
~~~~~~~~~~~~~~~~~~~ ^
src/shared/gatt-client.c:2154:6: warning: Use of memory after it is freed
if (read_db_hash(op)) {
^~~~~~~~~~~~~~~~
src/shared/gatt-client.c:2162:8: warning: Use of memory after it is freed
discovery_op_ref(op),
^~~~~~~~~~~~~~~~~~~~
src/shared/gatt-client.c:3340:2: warning: Use of memory after it is freed
complete_write_long_op(req, success, 0, false);
^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
src/shared/gatt-client.c:3362:2: warning: Use of memory after it is freed
request_unref(req);
^~~~~~~~~~~~~~~~~~
13 warnings generated.
tools/hciattach.c:817:7: warning: Although the value stored to 'n' is used in the enclosing expression, the value is never actually read from 'n'
if ((n = read_hci_event(fd, resp, 10)) < 0) {
^ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
tools/hciattach.c:865:7: warning: Although the value stored to 'n' is used in the enclosing expression, the value is never actually read from 'n'
if ((n = read_hci_event(fd, resp, 4)) < 0) {
^ ~~~~~~~~~~~~~~~~~~~~~~~~~~~
tools/hciattach.c:887:8: warning: Although the value stored to 'n' is used in the enclosing expression, the value is never actually read from 'n'
if ((n = read_hci_event(fd, resp, 10)) < 0) {
^ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
tools/hciattach.c:909:7: warning: Although the value stored to 'n' is used in the enclosing expression, the value is never actually read from 'n'
if ((n = read_hci_event(fd, resp, 4)) < 0) {
^ ~~~~~~~~~~~~~~~~~~~~~~~~~~~
tools/hciattach.c:930:7: warning: Although the value stored to 'n' is used in the enclosing expression, the value is never actually read from 'n'
if ((n = read_hci_event(fd, resp, 4)) < 0) {
^ ~~~~~~~~~~~~~~~~~~~~~~~~~~~
tools/hciattach.c:974:7: warning: Although the value stored to 'n' is used in the enclosing expression, the value is never actually read from 'n'
if ((n = read_hci_event(fd, resp, 6)) < 0) {
^ ~~~~~~~~~~~~~~~~~~~~~~~~~~~
6 warnings generated.
src/shared/bap.c:1529:8: warning: Use of memory after it is freed
bap = bt_bap_ref_safe(bap);
^~~~~~~~~~~~~~~~~~~~
src/shared/bap.c:2340:20: warning: Use of memory after it is freed
return queue_find(stream->bap->streams, NULL, stream);
^~~~~~~~~~~~~~~~~~~~
2 warnings generated.
src/oui.c:50:2: warning: Value stored to 'hwdb' is never read
hwdb = udev_hwdb_unref(hwdb);
^ ~~~~~~~~~~~~~~~~~~~~~
src/oui.c:53:2: warning: Value stored to 'udev' is never read
udev = udev_unref(udev);
^ ~~~~~~~~~~~~~~~~
2 warnings generated.
tools/rfcomm.c:234:3: warning: Value stored to 'i' is never read
i = execvp(cmdargv[0], cmdargv);
^ ~~~~~~~~~~~~~~~~~~~~~~~~~~~
tools/rfcomm.c:234:7: warning: Null pointer passed to 1st parameter expecting 'nonnull'
i = execvp(cmdargv[0], cmdargv);
^~~~~~~~~~~~~~~~~~~~~~~~~~~
tools/rfcomm.c:354:8: warning: Although the value stored to 'fd' is used in the enclosing expression, the value is never actually read from 'fd'
if ((fd = open(devname, O_RDONLY | O_NOCTTY)) < 0) {
^ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
tools/rfcomm.c:497:14: warning: Assigned value is garbage or undefined
req.channel = raddr.rc_channel;
^ ~~~~~~~~~~~~~~~~
tools/rfcomm.c:515:8: warning: Although the value stored to 'fd' is used in the enclosing expression, the value is never actually read from 'fd'
if ((fd = open(devname, O_RDONLY | O_NOCTTY)) < 0) {
^ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5 warnings generated.
tools/hcidump.c:180:9: warning: Potential leak of memory pointed to by 'dp'
if (fds[i].fd == sock)
^~~
tools/hcidump.c:248:17: warning: Assigned value is garbage or undefined
dh->ts_sec = htobl(frm.ts.tv_sec);
^ ~~~~~~~~~~~~~~~~~~~~
tools/hcidump.c:326:9: warning: 1st function call argument is an uninitialized value
if (be32toh(dp.flags) & 0x02) {
^~~~~~~~~~~~~~~~~
/usr/include/endian.h:46:22: note: expanded from macro 'be32toh'
# define be32toh(x) __bswap_32 (x)
^~~~~~~~~~~~~~
tools/hcidump.c:341:20: warning: 1st function call argument is an uninitialized value
frm.data_len = be32toh(dp.len);
^~~~~~~~~~~~~~~
/usr/include/endian.h:46:22: note: expanded from macro 'be32toh'
# define be32toh(x) __bswap_32 (x)
^~~~~~~~~~~~~~
tools/hcidump.c:346:14: warning: 1st function call argument is an uninitialized value
opcode = be32toh(dp.flags) & 0xffff;
^~~~~~~~~~~~~~~~~
/usr/include/endian.h:46:22: note: expanded from macro 'be32toh'
# define be32toh(x) __bswap_32 (x)
^~~~~~~~~~~~~~
tools/hcidump.c:384:17: warning: Assigned value is garbage or undefined
frm.data_len = btohs(dh.len);
^ ~~~~~~~~~~~~~
tools/hcidump.c:394:11: warning: Assigned value is garbage or undefined
frm.len = frm.data_len;
^ ~~~~~~~~~~~~
tools/hcidump.c:398:9: warning: 1st function call argument is an uninitialized value
ts = be64toh(ph.ts);
^~~~~~~~~~~~~~
/usr/include/endian.h:51:22: note: expanded from macro 'be64toh'
# define be64toh(x) __bswap_64 (x)
^~~~~~~~~~~~~~
tools/hcidump.c:403:13: warning: 1st function call argument is an uninitialized value
frm.in = be32toh(dp.flags) & 0x01;
^~~~~~~~~~~~~~~~~
/usr/include/endian.h:46:22: note: expanded from macro 'be32toh'
# define be32toh(x) __bswap_32 (x)
^~~~~~~~~~~~~~
tools/hcidump.c:408:11: warning: Assigned value is garbage or undefined
frm.in = dh.in;
^ ~~~~~
tools/hcidump.c:437:7: warning: Null pointer passed to 1st parameter expecting 'nonnull'
fd = open(file, open_flags, 0644);
^~~~~~~~~~~~~~~~~~~~~~~~~~~~
11 warnings generated.
tools/ciptool.c:351:7: warning: 5th function call argument is an uninitialized value
sk = do_connect(ctl, dev_id, &src, &dst, psm, (1 << CMTP_LOOPBACK));
^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1 warning generated.
src/sdp-xml.c:126:10: warning: Assigned value is garbage or undefined
buf[1] = data[i + 1];
^ ~~~~~~~~~~~
src/sdp-xml.c:306:11: warning: Assigned value is garbage or undefined
buf[1] = data[i + 1];
^ ~~~~~~~~~~~
src/sdp-xml.c:344:11: warning: Assigned value is garbage or undefined
buf[1] = data[i + 1];
^ ~~~~~~~~~~~
3 warnings generated.
tools/sdptool.c:941:26: warning: Result of 'malloc' is converted to a pointer of type 'uint32_t', which is incompatible with sizeof operand type 'int'
uint32_t *value_int = malloc(sizeof(int));
~~~~~~~~~~ ^~~~~~ ~~~~~~~~~~~
tools/sdptool.c:980:4: warning: 1st function call argument is an uninitialized value
free(allocArray[i]);
^~~~~~~~~~~~~~~~~~~
tools/sdptool.c:3777:2: warning: Potential leak of memory pointed to by 'si.name'
return add_service(0, &si);
^~~~~~~~~~~~~~~~~~~~~~~~~~
tools/sdptool.c:4112:4: warning: Potential leak of memory pointed to by 'context.svc'
return -1;
^~~~~~~~~
4 warnings generated.
tools/avtest.c:243:5: warning: Value stored to 'len' is never read
len = write(sk, buf, 3);
^ ~~~~~~~~~~~~~~~~~
tools/avtest.c:253:5: warning: Value stored to 'len' is never read
len = write(sk, buf, 4);
^ ~~~~~~~~~~~~~~~~~
tools/avtest.c:262:5: warning: Value stored to 'len' is never read
len = write(sk, buf, 3);
^ ~~~~~~~~~~~~~~~~~
tools/avtest.c:276:5: warning: Value stored to 'len' is never read
len = write(sk, buf,
^ ~~~~~~~~~~~~~~
tools/avtest.c:283:5: warning: Value stored to 'len' is never read
len = write(sk, buf,
^ ~~~~~~~~~~~~~~
tools/avtest.c:290:5: warning: Value stored to 'len' is never read
len = write(sk, buf,
^ ~~~~~~~~~~~~~~
tools/avtest.c:297:5: warning: Value stored to 'len' is never read
len = write(sk, buf,
^ ~~~~~~~~~~~~~~
tools/avtest.c:309:5: warning: Value stored to 'len' is never read
len = write(sk, buf, 4);
^ ~~~~~~~~~~~~~~~~~
tools/avtest.c:313:5: warning: Value stored to 'len' is never read
len = write(sk, buf, 2);
^ ~~~~~~~~~~~~~~~~~
tools/avtest.c:322:5: warning: Value stored to 'len' is never read
len = write(sk, buf, 3);
^ ~~~~~~~~~~~~~~~~~
tools/avtest.c:326:5: warning: Value stored to 'len' is never read
len = write(sk, buf, 2);
^ ~~~~~~~~~~~~~~~~~
tools/avtest.c:335:5: warning: Value stored to 'len' is never read
len = write(sk, buf, 3);
^ ~~~~~~~~~~~~~~~~~
tools/avtest.c:342:5: warning: Value stored to 'len' is never read
len = write(sk, buf, 2);
^ ~~~~~~~~~~~~~~~~~
tools/avtest.c:364:5: warning: Value stored to 'len' is never read
len = write(sk, buf, 4);
^ ~~~~~~~~~~~~~~~~~
tools/avtest.c:368:5: warning: Value stored to 'len' is never read
len = write(sk, buf, 2);
^ ~~~~~~~~~~~~~~~~~
tools/avtest.c:377:5: warning: Value stored to 'len' is never read
len = write(sk, buf, 3);
^ ~~~~~~~~~~~~~~~~~
tools/avtest.c:381:5: warning: Value stored to 'len' is never read
len = write(sk, buf, 2);
^ ~~~~~~~~~~~~~~~~~
tools/avtest.c:394:5: warning: Value stored to 'len' is never read
len = write(sk, buf, 4);
^ ~~~~~~~~~~~~~~~~~
tools/avtest.c:398:5: warning: Value stored to 'len' is never read
len = write(sk, buf, 2);
^ ~~~~~~~~~~~~~~~~~
tools/avtest.c:405:4: warning: Value stored to 'len' is never read
len = write(sk, buf, 2);
^ ~~~~~~~~~~~~~~~~~
tools/avtest.c:415:4: warning: Value stored to 'len' is never read
len = write(sk, buf, 2);
^ ~~~~~~~~~~~~~~~~~
tools/avtest.c:580:3: warning: Value stored to 'len' is never read
len = write(sk, buf, 2);
^ ~~~~~~~~~~~~~~~~~
tools/avtest.c:588:3: warning: Value stored to 'len' is never read
len = write(sk, buf, invalid ? 2 : 3);
^ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
tools/avtest.c:602:3: warning: Value stored to 'len' is never read
len = write(sk, buf, 4 + media_transport_size);
^ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
tools/avtest.c:615:3: warning: Value stored to 'len' is never read
len = write(sk, buf, 3);
^ ~~~~~~~~~~~~~~~~~
tools/avtest.c:625:3: warning: Value stored to 'len' is never read
len = write(sk, buf, 3);
^ ~~~~~~~~~~~~~~~~~
tools/avtest.c:637:3: warning: Value stored to 'len' is never read
len = write(sk, buf, 3);
^ ~~~~~~~~~~~~~~~~~
tools/avtest.c:652:3: warning: Value stored to 'len' is never read
len = write(sk, buf, 3);
^ ~~~~~~~~~~~~~~~~~
tools/avtest.c:664:3: warning: Value stored to 'len' is never read
len = write(sk, buf, 3);
^ ~~~~~~~~~~~~~~~~~
tools/avtest.c:673:3: warning: Value stored to 'len' is never read
len = write(sk, buf, 3);
^ ~~~~~~~~~~~~~~~~~
tools/avtest.c:680:3: warning: Value stored to 'len' is never read
len = write(sk, buf, 2);
^ ~~~~~~~~~~~~~~~~~
tools/avtest.c:716:2: warning: Value stored to 'len' is never read
len = write(sk, buf, AVCTP_HEADER_LENGTH + sizeof(play_pressed));
^ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
32 warnings generated.
tools/btproxy.c:836:15: warning: Null pointer passed to 1st parameter expecting 'nonnull'
tcp_port = atoi(optarg);
^~~~~~~~~~~~
tools/btproxy.c:839:8: warning: Null pointer passed to 1st parameter expecting 'nonnull'
if (strlen(optarg) > 3 && !strncmp(optarg, "hci", 3))
^~~~~~~~~~~~~~
2 warnings generated.
tools/create-image.c:76:3: warning: Value stored to 'fd' is never read
fd = -1;
^ ~~
tools/create-image.c:84:3: warning: Value stored to 'fd' is never read
fd = -1;
^ ~~
tools/create-image.c:92:3: warning: Value stored to 'fd' is never read
fd = -1;
^ ~~
tools/create-image.c:105:2: warning: Value stored to 'fd' is never read
fd = -1;
^ ~~
4 warnings generated.
tools/btgatt-client.c:1822:2: warning: Value stored to 'argv' is never read
argv += optind;
^ ~~~~~~
1 warning generated.
tools/check-selftest.c:42:3: warning: Value stored to 'ptr' is never read
ptr = fgets(result, sizeof(result), fp);
^ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1 warning generated.
tools/btgatt-server.c:1208:2: warning: Value stored to 'argv' is never read
argv -= optind;
^ ~~~~~~
1 warning generated.
tools/gatt-service.c:294:2: warning: 2nd function call argument is an uninitialized value
chr_write(chr, value, len);
^~~~~~~~~~~~~~~~~~~~~~~~~~
1 warning generated.
tools/obex-server-tool.c:133:13: warning: Null pointer passed to 1st parameter expecting 'nonnull'
data->fd = open(name, O_WRONLY | O_CREAT | O_NOCTTY, 0600);
^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
tools/obex-server-tool.c:192:13: warning: Null pointer passed to 1st parameter expecting 'nonnull'
data->fd = open(name, O_RDONLY | O_NOCTTY, 0);
^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2 warnings generated.
client/btpclient/btpclientctl.c:402:3: warning: Value stored to 'bit' is never read
bit = 0;
^ ~
client/btpclient/btpclientctl.c:1655:2: warning: Null pointer passed to 2nd parameter expecting 'nonnull'
memcpy(cp->data, ad_data, ad_len);
^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2 warnings generated.
src/sdp-client.c:353:14: warning: Access to field 'cb' results in a dereference of a null pointer
(*ctxt)->cb = cb;
~~~~~~~~~~~~^~~~
1 warning generated.
src/sdpd-request.c:211:13: warning: Result of 'malloc' is converted to a pointer of type 'char', which is incompatible with sizeof operand type 'uint16_t'
pElem = malloc(sizeof(uint16_t));
^~~~~~ ~~~~~~~~~~~~~~~~
src/sdpd-request.c:239:13: warning: Result of 'malloc' is converted to a pointer of type 'char', which is incompatible with sizeof operand type 'uint32_t'
pElem = malloc(sizeof(uint32_t));
^~~~~~ ~~~~~~~~~~~~~~~~
2 warnings generated.
src/gatt-database.c:1175:10: warning: Value stored to 'bits' during its initialization is never read
uint8_t bits[] = { BT_GATT_CHRC_CLI_FEAT_ROBUST_CACHING,
^~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1 warning generated.
src/gatt-client.c:1569:2: warning: Use of memory after it is freed
notify_client_unref(client);
^~~~~~~~~~~~~~~~~~~~~~~~~~~
1 warning generated.
unit/avrcp-lib.c:1968:3: warning: 1st function call argument is an uninitialized value
g_free(text[i]);
^~~~~~~~~~~~~~~
1 warning generated.
unit/avdtp.c:756:25: warning: Use of memory after it is freed
session->prio_queue = g_slist_remove(session->prio_queue, req);
^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
unit/avdtp.c:763:24: warning: Use of memory after it is freed
session->req_queue = g_slist_remove(session->req_queue, req);
^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2 warnings generated.
profiles/audio/avdtp.c:895:25: warning: Use of memory after it is freed
session->prio_queue = g_slist_remove(session->prio_queue, req);
^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
profiles/audio/avdtp.c:902:24: warning: Use of memory after it is freed
session->req_queue = g_slist_remove(session->req_queue, req);
^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2 warnings generated.
profiles/audio/a2dp.c:442:8: warning: Use of memory after it is freed
if (!cb->resume_cb)
^~~~~~~~~~~~~
profiles/audio/a2dp.c:3354:20: warning: Access to field 'starting' results in a dereference of a null pointer (loaded from variable 'stream')
stream->starting = TRUE;
~~~~~~ ^
profiles/audio/a2dp.c:3357:8: warning: Access to field 'suspending' results in a dereference of a null pointer (loaded from variable 'stream')
if (!stream->suspending && stream->suspend_timer) {
^~~~~~~~~~~~~~~~~~
profiles/audio/a2dp.c:3417:22: warning: Access to field 'suspending' results in a dereference of a null pointer (loaded from variable 'stream')
stream->suspending = TRUE;
~~~~~~ ^
4 warnings generated.
profiles/audio/avrcp.c:1961:2: warning: Value stored to 'operands' is never read
operands += sizeof(*pdu);
^ ~~~~~~~~~~~~
1 warning generated.
attrib/gatt.c:970:2: warning: Potential leak of memory pointed to by 'long_write'
return prepare_write(long_write);
^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1 warning generated.
src/sdpd-request.c:211:13: warning: Result of 'malloc' is converted to a pointer of type 'char', which is incompatible with sizeof operand type 'uint16_t'
pElem = malloc(sizeof(uint16_t));
^~~~~~ ~~~~~~~~~~~~~~~~
src/sdpd-request.c:239:13: warning: Result of 'malloc' is converted to a pointer of type 'char', which is incompatible with sizeof operand type 'uint32_t'
pElem = malloc(sizeof(uint32_t));
^~~~~~ ~~~~~~~~~~~~~~~~
2 warnings generated.
src/sdp-xml.c:126:10: warning: Assigned value is garbage or undefined
buf[1] = data[i + 1];
^ ~~~~~~~~~~~
src/sdp-xml.c:306:11: warning: Assigned value is garbage or undefined
buf[1] = data[i + 1];
^ ~~~~~~~~~~~
src/sdp-xml.c:344:11: warning: Assigned value is garbage or undefined
buf[1] = data[i + 1];
^ ~~~~~~~~~~~
3 warnings generated.
src/sdp-client.c:353:14: warning: Access to field 'cb' results in a dereference of a null pointer
(*ctxt)->cb = cb;
~~~~~~~~~~~~^~~~
1 warning generated.
src/gatt-database.c:1175:10: warning: Value stored to 'bits' during its initialization is never read
uint8_t bits[] = { BT_GATT_CHRC_CLI_FEAT_ROBUST_CACHING,
^~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1 warning generated.
src/gatt-client.c:1569:2: warning: Use of memory after it is freed
notify_client_unref(client);
^~~~~~~~~~~~~~~~~~~~~~~~~~~
1 warning generated.
gobex/gobex-header.c:95:2: warning: Null pointer passed to 2nd parameter expecting 'nonnull'
memcpy(to, from, count);
^~~~~~~~~~~~~~~~~~~~~~~
1 warning generated.
gobex/gobex-transfer.c:423:7: warning: Use of memory after it is freed
if (!g_slist_find(transfers, transfer))
^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1 warning generated.
mesh/main.c:162:3: warning: Value stored to 'optarg' is never read
optarg += strlen("auto");
^ ~~~~~~~~~~~~~~
1 warning generated.
doc/btmon-connections.rst:7: (SEVERE/4) Title level inconsistent:
CONNECTION TRACKING
===================
Exiting due to level-4 (SEVERE) system message.
make[1]: *** [Makefile:12381: doc/btmon.1] Error 1
make[1]: *** Waiting for unfinished jobs....
make: *** [Makefile:4227: all] Error 2
https://github.com/bluez/bluez/pull/1959/checks
---
Regards,
Linux Bluetooth
^ permalink raw reply [flat|nested] 7+ messages in thread
end of thread, other threads:[~2026-03-12 18:00 UTC | newest]
Thread overview: 7+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2026-03-12 17:15 [PATCH BlueZ v1 1/6] doc/btmon: Split Advertising and Scanning into btmon-advertising.rst Luiz Augusto von Dentz
2026-03-12 17:15 ` [PATCH BlueZ v1 2/6] doc/btmon: Split LE Audio Protocol Flow into btmon-le-audio.rst Luiz Augusto von Dentz
2026-03-12 17:15 ` [PATCH BlueZ v1 3/6] doc/btmon: Split L2CAP Channel Tracking into btmon-l2cap.rst Luiz Augusto von Dentz
2026-03-12 17:15 ` [PATCH BlueZ v1 4/6] doc/btmon: Split SMP Pairing Flow into btmon-smp.rst Luiz Augusto von Dentz
2026-03-12 17:15 ` [PATCH BlueZ v1 5/6] doc/btmon: Split GATT Database Reconstruction into btmon-gatt.rst Luiz Augusto von Dentz
2026-03-12 17:15 ` [PATCH BlueZ v1 6/6] doc/btmon: Split Connection Tracking into btmon-connections.rst Luiz Augusto von Dentz
2026-03-12 18:00 ` [BlueZ,v1,1/6] doc/btmon: Split Advertising and Scanning into btmon-advertising.rst 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