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

#include "ble_hci_ra8_ble.h"
#include <stdint.h>
#include <string.h>
#include "nimble_transport_stubs.h"
#include "ra8_attributes.h"
#include "ra8_ble.h"
#include "ra8_err.h"

Include dependency graph for ble_hci_ra8_ble.c:

Enumerations
enum	ble_hci_ra8_ble_state_t : uint8_t { k_ble_hci_ra8_ble_state_idle = 0U , k_ble_hci_ra8_ble_state_running = 1U }
	Adapter lifecycle states. More...
enum	ble_hci_ra8_ble_evt_layout_t : uint8_t { k_ble_hci_evt_off_code = 0U , k_ble_hci_evt_off_len = 1U , k_ble_hci_evt_off_params = 2U , k_ble_hci_evt_header_len = 2U }
	Layout offsets used when packing/unpacking HCI event buffers. More...
enum	ble_hci_ra8_ble_acl_layout_t : uint8_t { k_ble_hci_acl_off_handle_lo = 0U , k_ble_hci_acl_off_handle_hi = 1U , k_ble_hci_acl_off_len_lo = 2U , k_ble_hci_acl_off_len_hi = 3U , k_ble_hci_acl_off_payload = 4U , k_ble_hci_acl_header_len = 4U }
	Layout offsets used when packing/unpacking HCI ACL data. More...
enum	ble_hci_ra8_ble_bits_t : uint8_t { k_ble_hci_shift_byte = 8U }
	Shared bit-shift constants. More...
enum	ble_hci_ra8_ble_masks_t : uint32_t { k_ble_hci_mask_byte = 0xFFU }
	Shared bit-mask constants. More...

Functions
static void	internal_event_cb (void ctx, uint8_t evt_code, const uint8_t params, uint8_t params_len)
	Inbound HCI event callback (controller -> host).
static void	internal_acl_cb (void ctx, uint16_t handle, const uint8_t payload, uint16_t len)
	Inbound ACL data callback (controller -> host).
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.
void	ble_transport_ll_init (void)
	LL-side transport init hook (called by ble_transport_init).
int	ble_transport_to_ll_cmd_impl (void *buf)
	Controller-side handler for an HCI command from the host.
int	ble_transport_to_ll_acl_impl (struct os_mbuf *om)
	Controller-side handler for an ACL packet from the host.
int	ble_transport_to_ll_iso_impl (struct os_mbuf *om)
	Stub LL-side ISO transport hook.

Variables
static ble_hci_ra8_ble_state_t	s_state = k_ble_hci_ra8_ble_state_idle
	Single-instance state for the adapter.

Detailed Description

Apache NimBLE HCI transport adapter against the ra8_ble HCI ring.

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

Implementation of the LL-side HCI transport for Apache NimBLE, routed onto our ra8_ble driver. NimBLE's host stack runs in the "host" partition and emits HCI commands / ACL frames through ble_transport_to_ll_cmd / ble_transport_to_ll_acl – both resolve to our *_impl symbols below thanks to the upstream weak-binding scheme.

Inbound HCI events / ACL frames originate from the radio block. ra8_ble_dispatch (called from the kernel main loop or BLE IRQ) fires our internal_event_cb / internal_acl_cb callbacks. We copy the bytes into NimBLE-allocated buffers and hand them off to ble_transport_to_hs_evt / ble_transport_to_hs_acl so they land in NimBLE's host-side input queue.

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

Since: 0.1.0

Definition in file ble_hci_ra8_ble.c.

Enumeration Type Documentation

◆ ble_hci_ra8_ble_acl_layout_t

enum ble_hci_ra8_ble_acl_layout_t : uint8_t

Layout offsets used when packing/unpacking HCI ACL data.

Bluetooth Core 5.3 Vol 4 Part E 5.4.2 "HCI ACL Data Packet": flat byte layout [handle_lo][handle_hi][len_lo][len_hi][payload...].

Enumerator
k_ble_hci_acl_off_handle_lo	Handle low byte.
k_ble_hci_acl_off_handle_hi	Handle high byte + flags.
k_ble_hci_acl_off_len_lo	Length low byte.
k_ble_hci_acl_off_len_hi	Length high byte.
k_ble_hci_acl_off_payload	Payload start offset.
k_ble_hci_acl_header_len	Total ACL-header byte count.

Definition at line 86 of file ble_hci_ra8_ble.c.

◆ ble_hci_ra8_ble_bits_t

enum ble_hci_ra8_ble_bits_t : uint8_t

Shared bit-shift constants.

Enumerator
k_ble_hci_shift_byte	Byte shift for LE16 fold/unfold.

Definition at line 99 of file ble_hci_ra8_ble.c.

◆ ble_hci_ra8_ble_evt_layout_t

enum ble_hci_ra8_ble_evt_layout_t : uint8_t

Layout offsets used when packing/unpacking HCI event buffers.

Bluetooth Core 5.3 Vol 4 Part E 5.4.4 "HCI Event Packet": the host receives [evt_code][param_len][params...] as a flat byte array. The ra8_ble driver hands us evt_code + params separately; we re-pack them into NimBLE's evt-buffer format.

Enumerator
k_ble_hci_evt_off_code	Offset of the event-code byte.
k_ble_hci_evt_off_len	Offset of the parameter-length byte.
k_ble_hci_evt_off_params	Offset of the parameter payload.
k_ble_hci_evt_header_len	Total event-header byte count.

Definition at line 71 of file ble_hci_ra8_ble.c.

◆ ble_hci_ra8_ble_masks_t

enum ble_hci_ra8_ble_masks_t : uint32_t

Shared bit-mask constants.

Enumerator
k_ble_hci_mask_byte	Low-byte mask for 16-bit splits.

Definition at line 107 of file ble_hci_ra8_ble.c.

◆ ble_hci_ra8_ble_state_t

enum ble_hci_ra8_ble_state_t : uint8_t

Adapter lifecycle states.

Enumerator
k_ble_hci_ra8_ble_state_idle	Constructed, not yet attached.
k_ble_hci_ra8_ble_state_running	Callbacks attached to ra8_ble.

Definition at line 56 of file ble_hci_ra8_ble.c.

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().

◆ ble_transport_ll_init()

void ble_transport_ll_init ( void )

LL-side transport init hook (called by ble_transport_init).

Bring this port's controller-side transport up.

Idempotent: if the app already called ble_hci_ra8_ble_init we leave the running state alone. Otherwise we attach the inbound callbacks here so the very first HCI command issued by the host has a return path ready.

Precondition: ra8_ble_init returned k_ra8_ok.

Postcondition: Adapter is in the running state.

Since: 0.1.0

Precondition: Module has been initialized.

Postcondition: Side effects bounded to documented state.

Note: Not thread-safe unless documented otherwise.

Definition at line 286 of file ble_hci_ra8_ble.c.

References ble_hci_ra8_ble_init(), k_ble_hci_ra8_ble_state_running, and s_state.

◆ ble_transport_to_ll_acl_impl()

int ble_transport_to_ll_acl_impl ( struct os_mbuf * om )

Controller-side handler for an ACL packet from the host.

Hands the packet to the RA8 BLE transport, reached the same two ways as ble_transport_to_ll_cmd_impl().

Parameters

[in] om ACL mbuf chain.

Returns: Upstream transport status code.

Return values

0	Packet handed to the RA8 BLE transport.

Precondition: om is a valid ACL mbuf chain.; ble_hci_ra8_ble_init() has succeeded.

Postcondition: Ownership of om passes to the RA8 BLE transport.; No state changes on rejection.

Note: Not thread-safe; one ACL packet in flight at a time.

See also: ble_transport_to_ll_acl()

Since: 0.1.0

Definition at line 311 of file ble_hci_ra8_ble.c.

References k_ble_hci_acl_header_len, k_ble_hci_acl_off_handle_hi, k_ble_hci_acl_off_handle_lo, k_ble_hci_acl_off_len_hi, k_ble_hci_acl_off_len_lo, k_ble_hci_acl_off_payload, k_ble_hci_ra8_ble_acl_buf_max, k_ble_hci_shift_byte, k_ra8_ok, os_mbuf_copydata(), os_mbuf_free_chain(), os_mbuf_len(), and ra8_ble_hci_send_acl_data().

Referenced by ble_transport_to_ll_acl().

◆ ble_transport_to_ll_cmd_impl()

int ble_transport_to_ll_cmd_impl ( void * buf )

Controller-side handler for an HCI command from the host.

Hands the command to the RA8 BLE transport. The upstream transport core reaches this through ble_transport_to_ll_cmd(); the weak stub of that wrapper forwards here too, so an app that skips the core still reaches the controller.

Parameters

[in] buf HCI command buffer.

Returns: Upstream transport status code.

Return values

0	Command handed to the RA8 BLE transport.

Precondition: buf holds a well-formed HCI command.; ble_hci_ra8_ble_init() has succeeded.

Postcondition: Ownership of buf passes to the RA8 BLE transport.; No state changes on rejection.

Note: Not thread-safe; one HCI command in flight at a time.

See also: ble_transport_to_ll_cmd()

Since: 0.1.0

Definition at line 294 of file ble_hci_ra8_ble.c.

References ble_transport_free(), k_ble_hci_shift_byte, k_ra8_ok, and ra8_ble_hci_send_command().

Referenced by ble_transport_to_ll_cmd().

◆ ble_transport_to_ll_iso_impl()

int ble_transport_to_ll_iso_impl ( struct os_mbuf * om )

Stub LL-side ISO transport hook.

Controller-side handler for an ISO packet from the host.

Bluetooth LE Audio (Core 5.2+) ISO data is not exposed through ra8_ble yet. We accept the call to keep the link satisfied, free the mbuf, and return success.

Parameters

[in] om NimBLE-allocated ISO mbuf chain.

Returns: 0 on success.

Precondition: om may be NULL.

Postcondition: om has been freed (if non-NULL).

Since: 0.1.0

Return values

0	Success or default value.

Precondition: Module has been initialized.

Postcondition: Side effects bounded to documented state.

Note: Not thread-safe unless documented otherwise.

Definition at line 370 of file ble_hci_ra8_ble.c.

References os_mbuf_free_chain().

◆ internal_acl_cb()

void internal_acl_cb	(	void *	ctx,
		uint16_t	handle,
		const uint8_t *	payload,
		uint16_t	len )

static

Inbound ACL data callback (controller -> host).

Allocates a NimBLE ACL mbuf, appends [handle_lo][handle_hi] [len_lo][len_hi][payload] into it, and hands it to ble_transport_to_hs_acl. Drops on allocator failure.

Parameters

[in]	ctx	Unused; registered as nullptr.
[in]	handle	Connection handle + PB/BC flags (LE16).
[in]	payload	Payload byte pointer (driver scratch region).
[in]	len	Payload byte count.

Precondition: ble_hci_ra8_ble_init returned k_ra8_ok.; payload != nullptr || len == 0.

Postcondition: Either the frame landed in NimBLE's host queue, or it was dropped due to a transient OOM.

Since: 0.1.0

Postcondition: Side effects bounded to documented state.

Note: Not thread-safe unless documented otherwise.

Definition at line 195 of file ble_hci_ra8_ble.c.

References ble_transport_alloc_acl_from_ll(), ble_transport_to_hs_acl(), k_ble_hci_acl_header_len, k_ble_hci_acl_off_handle_hi, k_ble_hci_acl_off_handle_lo, k_ble_hci_acl_off_len_hi, k_ble_hci_acl_off_len_lo, k_ble_hci_mask_byte, k_ble_hci_ra8_ble_state_running, k_ble_hci_shift_byte, os_mbuf_append(), os_mbuf_free_chain(), and s_state.

Referenced by ble_hci_ra8_ble_init().

◆ internal_event_cb()

void internal_event_cb	(	void *	ctx,
		uint8_t	evt_code,
		const uint8_t *	params,
		uint8_t	params_len )

static

Inbound HCI event callback (controller -> host).

Allocates a NimBLE event buffer, copies [evt_code][param_len] [params...] into it, and hands it to ble_transport_to_hs_evt. Drops the event silently if the allocator returns NULL (the host stack has back-pressure of its own).

Parameters

[in]	ctx	Unused; registered as nullptr.
[in]	evt_code	HCI event code (Bluetooth Core 5.3 Vol 4 Part E 7.7).
[in]	params	Parameter byte pointer (driver scratch region).
[in]	params_len	Parameter byte count.

Precondition: ble_hci_ra8_ble_init returned k_ra8_ok.; params != nullptr || params_len == 0.

Postcondition: Either the event landed in NimBLE's host queue, or it was dropped due to a transient OOM.

Note: Invoked from ra8_ble_dispatch; thread context depends on where the caller schedules dispatch (kernel loop or ISR).

Since: 0.1.0

Postcondition: Side effects bounded to documented state.

Definition at line 146 of file ble_hci_ra8_ble.c.

References ble_transport_alloc_evt(), ble_transport_to_hs_evt(), k_ble_hci_evt_off_code, k_ble_hci_evt_off_len, k_ble_hci_evt_off_params, k_ble_hci_ra8_ble_state_running, memcpy(), and s_state.

Referenced by ble_hci_ra8_ble_init().

Variable Documentation

◆ s_state

ble_hci_ra8_ble_state_t s_state = k_ble_hci_ra8_ble_state_idle

static

Single-instance state for the adapter.

Definition at line 112 of file ble_hci_ra8_ble.c.

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ ble_hci_ra8_ble_acl_layout_t

◆ ble_hci_ra8_ble_bits_t

◆ ble_hci_ra8_ble_evt_layout_t

◆ ble_hci_ra8_ble_masks_t

◆ ble_hci_ra8_ble_state_t

Function Documentation

◆ ble_hci_ra8_ble_deinit()

◆ ble_hci_ra8_ble_init()

◆ ble_transport_ll_init()

◆ ble_transport_to_ll_acl_impl()

◆ ble_transport_to_ll_cmd_impl()

◆ ble_transport_to_ll_iso_impl()

◆ internal_acl_cb()

◆ internal_event_cb()

Variable Documentation

◆ s_state