Apache NimBLE HCI transport adapter against the ra8_ble HCI ring. More...

#include <stdint.h>
#include "ra8_err.h"

Include dependency graph for ble_hci_ra8_ble.h:

This graph shows which files directly or indirectly include this file:

Enumerations
enum	ble_hci_ra8_ble_limits_t : uint16_t { k_ble_hci_ra8_ble_evt_buf_max = 257U , k_ble_hci_ra8_ble_acl_buf_max = 255U , k_ble_hci_ra8_ble_handle_mask = 0x0FFFU }
	Sizing constants for the adapter's private scratch buffers. More...

Functions
ra8_err_t	ble_hci_ra8_ble_init (void)
	Attach the adapter to the ra8_ble HCI ring.
ra8_err_t	ble_hci_ra8_ble_deinit (void)
	Detach the adapter from the ra8_ble HCI ring.

Detailed Description

Apache NimBLE HCI transport adapter against the ra8_ble HCI ring.

Tag: [Ring 4 / PORT] {World: S}

Bridges Apache NimBLE's HCI transport entry points onto our ra8_ble driver:

ble_transport_to_ll_cmd(buf) – host -> controller HCI command
ble_transport_to_ll_acl(om) – host -> controller ACL data
ble_transport_to_hs_evt(buf) – controller -> host HCI event
ble_transport_to_hs_acl(om) – controller -> host ACL data

The host->controller path is wired to ra8_ble_hci_send_command / ra8_ble_hci_send_acl_data. The controller->host path is fed by ra8_ble_attach_event_handler / ra8_ble_attach_acl_handler callbacks invoked from ra8_ble_dispatch at every kernel tick (or from the controller IRQ once enabled).

The expected lifecycle is:

App calls ra8_ble_init() (clocks the radio and opens the HCI mailbox).
App calls ble_hci_ra8_ble_init() – this file – to attach the inbound callbacks and clear any private state.
App calls nimble_port_init() followed by ble_hs_sched_start() and the host stack starts pumping HCI commands through the adapter.

Warning: UNVALIDATED SCAFFOLD (issue #286): this NimBLE port and its ThreadX Native Porting Layer link and pass the static gates, but have NEVER been hardware-validated and are NOT emulator-gated – ra8_emulator models no RA8D2 BLE controller / HCI mailbox, and the underlying ra8_ble transport is itself unproven on this board (see #86, #91). Treat every symbol here as a link-only stub, not a working BLE stack. Consumers stay under examples/_unsupported/ until a NimBLE app is driven to real hardware validation and promoted out of that tier.

Copyright: Copyright (c) 2026 Brighton Sikarskie SPDX-License-Identifier: MIT

Definition in file ble_hci_ra8_ble.h.

Enumeration Type Documentation

◆ ble_hci_ra8_ble_limits_t

enum ble_hci_ra8_ble_limits_t : uint16_t

Sizing constants for the adapter's private scratch buffers.

The adapter copies inbound HCI events / ACL frames out of the driver-owned scratch buffer (ra8_ble_event_fn_t / ra8_ble_acl_fn_t promise the pointer is only valid for the duration of the callback) into NimBLE-allocated mbufs. The maxima below match the matching ra8_ble_limits_t constants but live here so the adapter does not reach across the driver header boundary for sizing.

Enumerator
k_ble_hci_ra8_ble_evt_buf_max	Maximum HCI event parameter byte count + 2-byte header.
k_ble_hci_ra8_ble_acl_buf_max	Maximum HCI ACL payload byte count + 4-byte header.
k_ble_hci_ra8_ble_handle_mask	ACL handle field carries the 12-bit handle plus PB/BC flags.

Definition at line 73 of file ble_hci_ra8_ble.h.

Function Documentation

◆ ble_hci_ra8_ble_deinit()

ra8_err_t ble_hci_ra8_ble_deinit ( void )

nodiscard

Detach the adapter from the ra8_ble HCI ring.

Calls ra8_ble_attach_event_handler(nullptr, nullptr) and ra8_ble_attach_acl_handler(nullptr, nullptr) so subsequent inbound traffic is dropped on the floor by the driver.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok Adapter detached.

Precondition: ble_hci_ra8_ble_init returned k_ra8_ok.

Postcondition: Inbound HCI events / ACL frames are silently dropped.

Since: 0.1.0

Definition at line 248 of file ble_hci_ra8_ble.c.

References k_ble_hci_ra8_ble_state_idle, k_ra8_ok, ra8_ble_attach_acl_handler(), ra8_ble_attach_event_handler(), and s_state.

◆ ble_hci_ra8_ble_init()

ra8_err_t ble_hci_ra8_ble_init ( void )

nodiscard

Attach the adapter to the ra8_ble HCI ring.

Registers priv_event_cb and priv_acl_cb with ra8_ble_attach_event_handler / ra8_ble_attach_acl_handler. The callbacks copy the inbound bytes out of the driver scratch region into NimBLE-allocated buffers and hand them to ble_transport_to_hs_evt / ble_transport_to_hs_acl.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Callbacks attached.
k_ra8_err_not_initialized	ra8_ble_init has not been called.

Precondition: ra8_ble_init returned k_ra8_ok.; nimble_port_init has been called (mbuf pools live).

Postcondition: Inbound HCI events / ACL frames flow into NimBLE.; Subsequent ble_transport_to_ll_* calls are accepted.

Note: Not thread-safe; call once during system bring-up.

Since: 0.1.0

Definition at line 235 of file ble_hci_ra8_ble.c.

References internal_acl_cb(), internal_event_cb(), k_ble_hci_ra8_ble_state_running, k_ra8_err_not_initialized, k_ra8_ok, ra8_ble_attach_acl_handler(), ra8_ble_attach_event_handler(), and s_state.

Referenced by ble_transport_ll_init(), and internal_demo_ble_or_halt().