mirror of
https://github.com/espressif/esp-idf.git
synced 2026-10-01 18:50:34 +03:00
Zhou Xiao
2cf0638686
Protocol v8: every ENCODE record carries the one-byte id of the task that formatted it, replacing the incremental TASK_SWITCH marker scheme. Attribution becomes a property of the record: the per-source CAS lock, the last_task_handle writeback, and the try-lock contention drops are deleted, so concurrent writers to one source can no longer lose records to attribution races. The registry is a self-contained module (ble_log_task_registry.c/h, structured like the UART redirection writer): an append-only name-keyed table shared by every ENCODE writer, 16 bytes of RAM per entry, sized by CONFIG_BLE_LOG_TASK_ID_MAX. Word compares resolve ids lock-free on the record path; the registration CAS serializes only the cold path (once per task lifetime), and a record resolves its writer id after its claim succeeds, so the claim's lifetime reference pins the registry epoch and the id cannot cross an init/deinit boundary. A full registry or a contended registration degrades that record to the unknown id (0xFF) and still emits it. ISR callers stop at the lookup-miss branch before registration mutates shared state. Bindings are module-owned system output: every periodic snapshot window broadcasts one INTERNAL frame packing one fixed-layout record per registered entry on the registry's own dedicated transport, with a sequence of its own (a gap counts a skipped broadcast window, never a lost snapshot). A busy transport skips the window and the next one rebroadcasts, so a receiver that joined late converges on the next window. BLE_LOG_VERSION is bumped to 8: old decoders must not parse the new record layout. The compression encoders reject truncated NULL-buffer records instead of committing partial payloads, and the test app enables host compression with a 4-entry registry so the table-full path is reachable on target.
92 lines
3.5 KiB
C
92 lines
3.5 KiB
C
/*
|
|
* SPDX-FileCopyrightText: 2025-2026 Espressif Systems (Shanghai) CO LTD
|
|
*
|
|
* SPDX-License-Identifier: Apache-2.0
|
|
*/
|
|
#ifndef __BLE_LOG_H__
|
|
#define __BLE_LOG_H__
|
|
|
|
/* ------- */
|
|
/* BLE Log */
|
|
/* ------- */
|
|
|
|
/* INCLUDE */
|
|
#include <stdbool.h>
|
|
#include <stdint.h>
|
|
#include <stddef.h>
|
|
|
|
/* TYPEDEF */
|
|
/* CRITICAL:
|
|
* The number of BLE Log source code will directly determine the number of statistic manager
|
|
* memory requirements, keep it as less as possible; it's recommended to use subcode for more
|
|
* log data structure decoding */
|
|
/* CRITICAL: this enum is a public ABI and must not be reordered or renamed.
|
|
* Its values are the base on-wire source IDs of protocol v8 frames. */
|
|
typedef enum {
|
|
/* Internal */
|
|
BLE_LOG_SRC_INTERNAL = 0,
|
|
|
|
/* Custom */
|
|
BLE_LOG_SRC_CUSTOM,
|
|
|
|
/* BLE Stack */
|
|
BLE_LOG_SRC_LL_TASK,
|
|
BLE_LOG_SRC_LL_HCI,
|
|
BLE_LOG_SRC_LL_ISR,
|
|
BLE_LOG_SRC_HOST,
|
|
BLE_LOG_SRC_HCI,
|
|
BLE_LOG_SRC_ENCODE,
|
|
|
|
/* UART redirection (PORT 0 only) */
|
|
BLE_LOG_SRC_REDIR,
|
|
|
|
BLE_LOG_SRC_MAX,
|
|
} ble_log_src_t;
|
|
|
|
/* HCI Log Direction */
|
|
#define BLE_LOG_HCI_DOWNSTREAM 0
|
|
#define BLE_LOG_HCI_UPSTREAM 1
|
|
|
|
/* Encodes HCI direction in payload byte 0 bit 7 for the synchronous copy,
|
|
* then restores the complete original HCI type byte. The caller guarantees a
|
|
* non-NULL buffer with len > 0. */
|
|
#define ble_log_write_hci(direction, data, len) do { \
|
|
uint8_t *const ble_log_hci_data__ = (data); \
|
|
const uint8_t ble_log_hci_type__ = ble_log_hci_data__[0]; \
|
|
ble_log_hci_data__[0] = (ble_log_hci_type__ & 0x7fU) | \
|
|
((direction) ? 0x80U : 0U); \
|
|
(void)ble_log_write_hex(BLE_LOG_SRC_HCI, ble_log_hci_data__, \
|
|
(len)); \
|
|
ble_log_hci_data__[0] = ble_log_hci_type__; \
|
|
} while (0)
|
|
|
|
/* INTERFACE */
|
|
bool ble_log_init(void);
|
|
void ble_log_deinit(void);
|
|
/* Controls public producers only; periodic system output remains active. */
|
|
bool ble_log_enable(bool enable);
|
|
/* Blocking; call only from a caller-owned task, not an ISR or system callback. */
|
|
void ble_log_flush(void);
|
|
/* Waits for a shared transport in yieldable contexts; ISR and critical-section callers fail fast. */
|
|
bool ble_log_write_hex(ble_log_src_t src_code, const uint8_t *addr, size_t len);
|
|
/* Same backpressure as ble_log_write_hex(): yieldable claims wait for a
|
|
* shared transport when wait_for_transport is true; pass false for a lossy
|
|
* fast path from contexts that must not block (system periodic output).
|
|
* Non-yieldable contexts (ISR, critical section) fail fast either way. */
|
|
uint8_t *ble_log_claim(ble_log_src_t src_code, size_t max_len,
|
|
uint32_t *handle, bool wait_for_transport);
|
|
void ble_log_commit(uint32_t handle, size_t actual_len);
|
|
void ble_log_dump_to_console(void);
|
|
#if CONFIG_BLE_LOG_LL_ENABLED
|
|
void ble_log_write_hex_ll(uint32_t len, const uint8_t *addr,
|
|
uint32_t len_append, const uint8_t *addr_append, uint32_t flag);
|
|
#endif /* CONFIG_BLE_LOG_LL_ENABLED */
|
|
/* Task-context only. Controls the optional TS sync IO toggle, which starts
|
|
* disabled and low; this is a lifecycle-checked no-op when the toggle is not
|
|
* built. Periodic Internal Snapshots remain active in either state. */
|
|
bool ble_log_ts_sync_io_toggle_enable(bool enable);
|
|
/* Backward-compatible name for ble_log_ts_sync_io_toggle_enable(). */
|
|
bool ble_log_sync_enable(bool enable);
|
|
|
|
#endif /* __BLE_LOG_H__ */
|