ra8_ble.c

Go to the documentation of this file.

 
#include "ra8_ble.h"
 
#include <stddef.h>
#include <stdint.h>
 
#include "ra8_attributes.h"
#include "ra8_ble_internal.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_log.h"

RA8_INTERNAL static inline void internal_byte_copy(uint8_t* dst, const uint8_t* src, uint16_t n)
{
  for (uint16_t i = 0U; i < n; ++i) {
    dst[i] = src[i];
  }
}
 
static const char* s_tag = "BLE";
 
/* =============================================================================
 * Driver-internal tunables and limits
 * =============================================================================
 */
 
typedef enum : uint32_t {
  k_ra8_ble_dispatch_budget = 64U, 
} ra8_ble_internal_t;
 
typedef enum : uint16_t {
  k_ra8_ble_tx_capture_bytes = 1024U,   
  k_ra8_ble_rx_inject_bytes  = 1024U,   
  k_ra8_ble_scan_min         = 0x0004U, 
  k_ra8_ble_scan_max         = 0x4000U, 
} ra8_ble_param_limits_t;
 
typedef enum : uint8_t {
  k_ra8_ble_byte_shift = 8U,    
  k_ra8_ble_byte_mask  = 0xFFU, 
} ra8_ble_byte_const_t;

typedef enum : uint16_t {
  k_ra8_ble_op_le_set_random_address = 0x2005U, 
  k_ra8_ble_op_le_set_adv_data       = 0x2008U, 
  k_ra8_ble_op_le_set_adv_enable     = 0x200AU, 
  k_ra8_ble_op_le_set_scan_params    = 0x200BU, 
  k_ra8_ble_op_le_set_scan_enable    = 0x200CU, 
} ra8_ble_hci_opcode_t;
 
typedef enum : uint8_t {
  k_ra8_ble_scan_param_bytes     = 7U, 
  k_ra8_ble_scan_own_pub         = 0U, 
  k_ra8_ble_scan_filt_basic      = 0U, 
  k_ra8_ble_scan_off_type        = 0U, 
  k_ra8_ble_scan_off_interval_lo = 1U, 
  k_ra8_ble_scan_off_interval_hi = 2U, 
  k_ra8_ble_scan_off_window_lo   = 3U, 
  k_ra8_ble_scan_off_window_hi   = 4U, 
  k_ra8_ble_scan_off_own_addr    = 5U, 
  k_ra8_ble_scan_off_filter      = 6U, 
  k_ra8_ble_scan_enable_bytes    = 2U, 
} ra8_ble_scan_const_t;
 
/* =============================================================================
 * Driver state
 * =============================================================================
 */
 
typedef struct {
  ra8_ble_event_fn_t evt_fn;  
  void*              evt_ctx; 
  ra8_ble_acl_fn_t   acl_fn;  
  void*              acl_ctx; 
  uint8_t            open;    
  /* TX capture, used by unit tests to inspect framing. */
  uint8_t  tx_capture[k_ra8_ble_tx_capture_bytes]; 
  uint16_t tx_capture_len;                         
  /* RX injection, used by unit tests to deliver synthetic events. */
  uint8_t  rx_inject[k_ra8_ble_rx_inject_bytes]; 
  uint16_t rx_inject_len;                        
  uint16_t rx_inject_pos;                        
} ra8_ble_state_t;
 
static ra8_ble_state_t s_state = {};
 
/* =============================================================================
 * Internal helpers
 * =============================================================================
 */

RA8_INTERNAL static void internal_tx_byte(uint8_t b)
{
  if (s_state.tx_capture_len < k_ra8_ble_tx_capture_bytes) {
    s_state.tx_capture[s_state.tx_capture_len] = b;
    s_state.tx_capture_len                     = (uint16_t)(s_state.tx_capture_len + 1U);
  }
}

RA8_INTERNAL static uint8_t internal_rx_byte(uint8_t* out)
{
  if (s_state.rx_inject_pos >= s_state.rx_inject_len) {
    return 0U;
  }
  *out                  = s_state.rx_inject[s_state.rx_inject_pos];
  s_state.rx_inject_pos = (uint16_t)(s_state.rx_inject_pos + 1U);
  return 1U;
}
 
/* =============================================================================
 * Lifecycle
 * =============================================================================
 */
 
ra8_err_t ra8_ble_open(const ra8_ble_config_t* cfg)
{
  RA8_CHECK_NULL_PTR(cfg, s_tag, "cfg must not be NULL");
  if (s_state.open != 0U) {
    return k_ra8_err_invalid_arg;
  }
  s_state.open           = 1U;
  s_state.tx_capture_len = 0U;
  s_state.rx_inject_len  = 0U;
  s_state.rx_inject_pos  = 0U;
  ra8_log_info(s_tag, "BLE HCI transport open");
  return k_ra8_ok;
}
 
ra8_err_t ra8_ble_close(void)
{
  if (s_state.open == 0U) {
    return k_ra8_err_invalid_arg;
  }
  s_state.open = 0U;
  ra8_log_info(s_tag, "BLE HCI transport closed");
  return k_ra8_ok;
}
 
/* =============================================================================
 * Raw HCI traffic
 * =============================================================================
 */
 
ra8_err_t ra8_ble_hci_send_command(uint16_t opcode, const uint8_t* params, uint8_t params_len)
{
  if (s_state.open == 0U) {
    return k_ra8_err_not_initialized;
  }
  if ((params == nullptr) && (params_len > 0U)) {
    return k_ra8_err_null_ptr;
  }
  /* params_len is uint8_t so it cannot exceed k_ra8_ble_max_cmd_params (255). */
 
  internal_tx_byte(k_ra8_ble_pkt_cmd);
  internal_tx_byte((uint8_t)(opcode & k_ra8_ble_byte_mask));
  internal_tx_byte((uint8_t)((opcode >> k_ra8_ble_byte_shift) & k_ra8_ble_byte_mask));
  internal_tx_byte(params_len);
  for (uint16_t i = 0U; i < params_len; ++i) {
    internal_tx_byte(params[i]);
  }
  return k_ra8_ok;
}
 
ra8_err_t ra8_ble_hci_send_acl_data(uint16_t handle, const uint8_t* payload, uint16_t len)
{
  if (s_state.open == 0U) {
    return k_ra8_err_not_initialized;
  }
  if ((payload == nullptr) && (len > 0U)) {
    return k_ra8_err_null_ptr;
  }
  if (len > k_ra8_ble_max_acl_payload) {
    return k_ra8_err_invalid_arg;
  }
 
  internal_tx_byte(k_ra8_ble_pkt_acl_data);
  internal_tx_byte((uint8_t)(handle & k_ra8_ble_byte_mask));
  internal_tx_byte((uint8_t)((handle >> k_ra8_ble_byte_shift) & k_ra8_ble_byte_mask));
  internal_tx_byte((uint8_t)(len & k_ra8_ble_byte_mask));
  internal_tx_byte((uint8_t)((len >> k_ra8_ble_byte_shift) & k_ra8_ble_byte_mask));
  for (uint16_t i = 0U; i < len; ++i) {
    internal_tx_byte(payload[i]);
  }
  return k_ra8_ok;
}
 
/* =============================================================================
 * Receive callbacks
 * =============================================================================
 */
 
ra8_err_t ra8_ble_attach_event_handler(ra8_ble_event_fn_t fn, void* ctx)
{
  s_state.evt_fn  = fn;
  s_state.evt_ctx = ctx;
  return k_ra8_ok;
}
 
ra8_err_t ra8_ble_attach_acl_handler(ra8_ble_acl_fn_t fn, void* ctx)
{
  s_state.acl_fn  = fn;
  s_state.acl_ctx = ctx;
  return k_ra8_ok;
}

RA8_INTERNAL static ra8_err_t internal_dispatch_event(void)
{
  uint8_t code = 0U;
  uint8_t plen = 0U;
  // mcdc-deactivated: TU-local helper internal_dispatch_event; HCI byte-stream RX guard against truncated event headers. Reaching this requires the producer to enqueue a partial header, which the HCI transport delivers as atomic packet boundaries -- the second short-circuit condition is unreachable on any well-formed link.
  if ((internal_rx_byte(&code) == 0U) || (internal_rx_byte(&plen) == 0U)) {
    return k_ra8_err_invalid_arg;
  }
  static uint8_t s_evt_scratch[k_ra8_ble_max_evt_params];
  for (uint8_t i = 0U; i < plen; ++i) {
    if (internal_rx_byte(&s_evt_scratch[i]) == 0U) {
      return k_ra8_err_invalid_arg;
    }
  }
  if (s_state.evt_fn != nullptr) {
    s_state.evt_fn(s_state.evt_ctx, code, s_evt_scratch, plen);
  }
  return k_ra8_ok;
}

RA8_INTERNAL static ra8_err_t internal_dispatch_acl(void)
{
  uint8_t hdl_lo = 0U;
  uint8_t hdl_hi = 0U;
  uint8_t len_lo = 0U;
  uint8_t len_hi = 0U;
  // mcdc-deactivated: TU-local helper internal_dispatch_acl; 4-byte HCI ACL header is delivered atomically by the transport. Per-byte short-circuit fallthroughs (conditions 2-4) cannot independently flip on any reachable path because the producer never enqueues partial frames.
  if ((internal_rx_byte(&hdl_lo) == 0U) || (internal_rx_byte(&hdl_hi) == 0U) ||
      (internal_rx_byte(&len_lo) == 0U) || (internal_rx_byte(&len_hi) == 0U)) {
    return k_ra8_err_invalid_arg;
  }
  const uint16_t handle = (uint16_t)(((uint16_t)hdl_hi << k_ra8_ble_byte_shift) | (uint16_t)hdl_lo);
  const uint16_t len    = (uint16_t)(((uint16_t)len_hi << k_ra8_ble_byte_shift) | (uint16_t)len_lo);
  if (len > k_ra8_ble_max_acl_payload) {
    return k_ra8_err_invalid_arg;
  }
  static uint8_t s_acl_scratch[k_ra8_ble_max_acl_payload];
  for (uint16_t i = 0U; i < len; ++i) {
    if (internal_rx_byte(&s_acl_scratch[i]) == 0U) {
      return k_ra8_err_invalid_arg;
    }
  }
  if (s_state.acl_fn != nullptr) {
    s_state.acl_fn(s_state.acl_ctx, handle, s_acl_scratch, len);
  }
  return k_ra8_ok;
}
 
ra8_err_t ra8_ble_dispatch(void)
{
  if (s_state.open == 0U) {
    return k_ra8_err_not_initialized;
  }
  for (uint32_t budget = 0U; budget < k_ra8_ble_dispatch_budget; ++budget) {
    uint8_t pkt_type = 0U;
    if (internal_rx_byte(&pkt_type) == 0U) {
      return k_ra8_ok;
    }
    if (pkt_type == k_ra8_ble_pkt_event) {
      const ra8_err_t err = internal_dispatch_event();
      if (err != k_ra8_ok) {
        return err;
      }
    } else if (pkt_type == k_ra8_ble_pkt_acl_data) {
      const ra8_err_t err = internal_dispatch_acl();
      if (err != k_ra8_ok) {
        return err;
      }
    } else {
      return k_ra8_err_invalid_arg;
    }
  }
  return k_ra8_ok;
}
 
/* =============================================================================
 * Convenience wrappers
 * =============================================================================
 */
 
ra8_err_t ra8_ble_set_random_address(const uint8_t addr[k_ra8_ble_addr_bytes])
{
  RA8_CHECK_NULL_PTR(addr, s_tag, "addr must not be NULL");
  return ra8_ble_hci_send_command(k_ra8_ble_op_le_set_random_address, addr, k_ra8_ble_addr_bytes);
}
 
ra8_err_t ra8_ble_set_advertising_data(const uint8_t* data, uint8_t len)
{
  if (len > k_ra8_ble_adv_data_max) {
    return k_ra8_err_invalid_arg;
  }
  if ((data == nullptr) && (len > 0U)) {
    return k_ra8_err_null_ptr;
  }
  /* Spec frames the command as: [len:1][data:31][padding:31-len].
   * Most stacks pad with zeros; here we forward only the meaningful
   * prefix to keep the framing test simple and let the controller
   * pad if it cares. */
  uint8_t buf[1U + k_ra8_ble_adv_data_max] = {};
  buf[0]                                   = len;
  if (len > 0U) {
    internal_byte_copy(&buf[1], data, len);
  }
  return ra8_ble_hci_send_command(k_ra8_ble_op_le_set_adv_data, buf, (uint8_t)(1U + len));
}
 
ra8_err_t ra8_ble_set_advertising_enable(uint8_t enable)
{
  const uint8_t param = (enable != 0U) ? 1U : 0U;
  return ra8_ble_hci_send_command(k_ra8_ble_op_le_set_adv_enable, &param, 1U);
}
 
ra8_err_t ra8_ble_scan_start(uint8_t active, uint16_t interval, uint16_t window)
{
  if ((interval < k_ra8_ble_scan_min) || (interval > k_ra8_ble_scan_max)) {
    return k_ra8_err_invalid_arg;
  }
  if ((window < k_ra8_ble_scan_min) || (window > k_ra8_ble_scan_max)) {
    return k_ra8_err_invalid_arg;
  }
  if (window > interval) {
    return k_ra8_err_invalid_arg;
  }
  if (s_state.open == 0U) {
    return k_ra8_err_not_initialized;
  }
 
  /* Bluetooth Core 5.3 Vol 4 Part E 7.8.10 LE_Set_Scan_Parameters
   * params: scan_type(1) | interval(2) | window(2) | own_addr(1) | filter(1) */
  uint8_t params[k_ra8_ble_scan_param_bytes];
  params[k_ra8_ble_scan_off_type]        = (active != 0U) ? 1U : 0U;
  params[k_ra8_ble_scan_off_interval_lo] = (uint8_t)(interval & k_ra8_ble_byte_mask);
  params[k_ra8_ble_scan_off_interval_hi] =
    (uint8_t)((interval >> k_ra8_ble_byte_shift) & k_ra8_ble_byte_mask);
  params[k_ra8_ble_scan_off_window_lo] = (uint8_t)(window & k_ra8_ble_byte_mask);
  params[k_ra8_ble_scan_off_window_hi] =
    (uint8_t)((window >> k_ra8_ble_byte_shift) & k_ra8_ble_byte_mask);
  params[k_ra8_ble_scan_off_own_addr] = k_ra8_ble_scan_own_pub;
  params[k_ra8_ble_scan_off_filter]   = k_ra8_ble_scan_filt_basic;
 
  ra8_err_t err =
    ra8_ble_hci_send_command(k_ra8_ble_op_le_set_scan_params, params, k_ra8_ble_scan_param_bytes);
  if (err != k_ra8_ok) {
    return err;
  }
 
  /* 7.8.11 LE_Set_Scan_Enable: enable(1) | filter_dup(1) */
  const uint8_t enable_params[k_ra8_ble_scan_enable_bytes] = {1U, 0U};
  return ra8_ble_hci_send_command(k_ra8_ble_op_le_set_scan_enable,
                                  enable_params,
                                  (uint8_t)sizeof(enable_params));
}
 
/* =============================================================================
 * Test-only external hooks; production code has no callers.
 * =============================================================================
 */
 
RA8_TEST_HELPER void ra8_ble_test_reset_capture(void)
{
  s_state.tx_capture_len = 0U;
  s_state.rx_inject_len  = 0U;
  s_state.rx_inject_pos  = 0U;
}
 
RA8_TEST_HELPER void ra8_ble_test_inject_rx(const uint8_t* bytes, uint16_t len)
{
  if ((bytes == nullptr) || (len == 0U)) {
    return;
  }
  if (len > k_ra8_ble_rx_inject_bytes) {
    len = k_ra8_ble_rx_inject_bytes;
  }
  internal_byte_copy(s_state.rx_inject, bytes, len);
  s_state.rx_inject_len = len;
  s_state.rx_inject_pos = 0U;
}
 
RA8_TEST_HELPER const uint8_t* ra8_ble_test_tx_capture(uint16_t* out_len)
{
  if (out_len != nullptr) {
    *out_len = s_state.tx_capture_len;
  }
  return s_state.tx_capture;
}