ra8_ota.c

Go to the documentation of this file.

 
#include "ra8_ota.h"
 
#include <stddef.h>
#include <stdint.h>
#include <string.h>
 
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_ota_internal.h"
#include "ra8_secure.h"
 
/* =============================================================================
 * Module-static storage
 * ============================================================================= */

static const char* const s_tag = "ra8_ota";

ra8_ota_state_t g_ra8_ota_state = k_ra8_ota_state_idle;

ra8_ota_cfg_t g_ra8_ota_cfg;

bool g_ra8_ota_initialized = false;

static ra8_ota_manifest_t s_manifest;

static bool s_manifest_valid = false;

static uint32_t s_bytes_done = 0U;

static ra8_err_t s_last_err = k_ra8_ok;

uint8_t g_ra8_ota_buf[k_ra8_ota_chunk_bytes];
 
/* =============================================================================
 * Internal helpers
 * ============================================================================= */

RA8_PRIV
void priv_ota_set_state(ra8_ota_state_t new_state, ra8_err_t err)
{
  g_ra8_ota_state = new_state;
  s_last_err      = err;
  if (g_ra8_ota_cfg.on_progress != nullptr) {
    const ra8_ota_progress_t snap = {
      .state       = new_state,
      .bytes_done  = s_bytes_done,
      .bytes_total = s_manifest_valid ? s_manifest.image_size_bytes : 0U,
      .last_err    = err,
    };
    g_ra8_ota_cfg.on_progress(&snap);
  }
}

RA8_INTERNAL
static ra8_err_t internal_drain(uint8_t* dst, uint32_t cap, uint32_t* out_n)
{
  uint32_t total = 0U;
  /* Bounded loop: each iteration must consume >= 1 byte or hit EOF. */
  for (uint32_t guard = 0U; guard < cap + 1U; ++guard) {
    if (total >= cap) {
      break;
    }
    uint32_t        got = 0U;
    const ra8_err_t e =
      g_ra8_ota_cfg.net.read(g_ra8_ota_cfg.net.ctx, dst + total, cap - total, &got);
    if (e != k_ra8_ok) {
      return e;
    }
    if (got == 0U) {
      break; /* EOF */
    }
    total += got;
  }
  *out_n = total;
  return k_ra8_ok;
}
 
/* =============================================================================
 * Public API
 * ============================================================================= */

ra8_err_t ra8_ota_init(const ra8_ota_cfg_t* cfg)
{
  if (g_ra8_ota_initialized) {
    return k_ra8_err_invalid_state;
  }
  const ra8_err_t e = priv_ota_validate_cfg(cfg);
  if (e != k_ra8_ok) {
    return e;
  }
  (void)memcpy(&g_ra8_ota_cfg, cfg, sizeof g_ra8_ota_cfg);
  g_ra8_ota_state       = k_ra8_ota_state_idle;
  s_manifest_valid      = false;
  s_bytes_done          = 0U;
  s_last_err            = k_ra8_ok;
  g_ra8_ota_initialized = true;
  /* run_as_thread is honoured by an external adapter -- on host the
   * caller drives ra8_ota_run_step() directly. */
  return k_ra8_ok;
}

ra8_err_t ra8_ota_deinit(void)
{
  g_ra8_ota_initialized = false;
  g_ra8_ota_state       = k_ra8_ota_state_idle;
  s_manifest_valid      = false;
  s_bytes_done          = 0U;
  s_last_err            = k_ra8_ok;
  (void)memset(&g_ra8_ota_cfg, 0, sizeof g_ra8_ota_cfg);
  return k_ra8_ok;
}

ra8_ota_state_t ra8_ota_get_state(void)
{
  return g_ra8_ota_state;
}

RA8_INTERNAL
static ra8_err_t internal_fetch_manifest_payload(uint32_t* out_got)
{
  uint32_t  content_len = 0U;
  ra8_err_t e =
    g_ra8_ota_cfg.net.open(g_ra8_ota_cfg.net.ctx, g_ra8_ota_cfg.manifest_url, &content_len);
  if (e != k_ra8_ok) {
    return e;
  }
  if (content_len > k_ra8_ota_manifest_max_bytes) {
    (void)g_ra8_ota_cfg.net.close(g_ra8_ota_cfg.net.ctx);
    return k_ra8_err_invalid_size;
  }
  uint32_t got = 0U;
  e            = internal_drain(g_ra8_ota_buf, k_ra8_ota_manifest_max_bytes - 1U, &got);
  (void)g_ra8_ota_cfg.net.close(g_ra8_ota_cfg.net.ctx);
  if (e != k_ra8_ok) {
    return e;
  }
  g_ra8_ota_buf[got] = 0U; /* NUL terminate so JSON helpers can use strstr. */
  *out_got           = got;
  return k_ra8_ok;
}

ra8_err_t ra8_ota_check_for_update(ra8_ota_manifest_t* out_manifest)
{
  if (!g_ra8_ota_initialized) {
    return k_ra8_err_not_initialized;
  }
  RA8_CHECK_NULL_PTR(out_manifest, s_tag, "out_manifest");
  if (g_ra8_ota_state != k_ra8_ota_state_idle) {
    return k_ra8_err_invalid_state;
  }
  priv_ota_set_state(k_ra8_ota_state_checking, k_ra8_ok);
 
  uint32_t  got = 0U;
  ra8_err_t e   = internal_fetch_manifest_payload(&got);
  if (e != k_ra8_ok) {
    priv_ota_set_state(k_ra8_ota_state_error, e);
    return e;
  }
 
  e = priv_ota_manifest_decode((const char*)g_ra8_ota_buf, out_manifest);
  if (e != k_ra8_ok) {
    priv_ota_set_state(k_ra8_ota_state_error, e);
    return e;
  }
  (void)memcpy(&s_manifest, out_manifest, sizeof s_manifest);
  s_manifest_valid = true;
  priv_ota_set_state(k_ra8_ota_state_idle, k_ra8_ok);
  return k_ra8_ok;
}

RA8_INTERNAL
static ra8_err_t internal_download_chunk(uint32_t addr_base, uint32_t* in_out_done, uint32_t total)
{
  const uint32_t remaining = total - *in_out_done;
  const uint32_t want = (remaining < k_ra8_ota_chunk_bytes) ? remaining : k_ra8_ota_chunk_bytes;
  uint32_t       got  = 0U;
  ra8_err_t      e    = internal_drain(g_ra8_ota_buf, want, &got);
  if (e != k_ra8_ok) {
    return e;
  }
  if (got == 0U) {
    return k_ra8_err_hw_error;
  }
  e = g_ra8_ota_cfg.crypto.sha256_update(g_ra8_ota_cfg.crypto.ctx, g_ra8_ota_buf, got);
  if (e != k_ra8_ok) {
    return e;
  }
  e = g_ra8_ota_cfg.flash.program(g_ra8_ota_cfg.flash.ctx,
                                  addr_base + *in_out_done,
                                  g_ra8_ota_buf,
                                  got);
  if (e != k_ra8_ok) {
    return e;
  }
  *in_out_done += got;
  priv_ota_set_state(k_ra8_ota_state_downloading, k_ra8_ok);
  return k_ra8_ok;
}

RA8_INTERNAL
static ra8_err_t internal_prepare_bank(const ra8_ota_manifest_t* manifest)
{
  ra8_err_t e = g_ra8_ota_cfg.flash.erase(g_ra8_ota_cfg.flash.ctx,
                                          g_ra8_ota_cfg.flash.inactive_bank_addr,
                                          manifest->image_size_bytes);
  if (e != k_ra8_ok) {
    return e;
  }
  return g_ra8_ota_cfg.crypto.sha256_init(g_ra8_ota_cfg.crypto.ctx);
}

RA8_INTERNAL
static ra8_err_t internal_download_loop(const ra8_ota_manifest_t* manifest)
{
  const uint32_t max_chunks = (k_ra8_ota_max_image_bytes / k_ra8_ota_chunk_bytes) + 1U;
  uint32_t       chunks     = 0U;
  ra8_err_t      e          = k_ra8_ok;
  while (s_bytes_done < manifest->image_size_bytes) {
    /* Validation ensures image_size <= k_ra8_ota_max_image_bytes == 128 *
     * k_ra8_ota_chunk_bytes, so chunk count never exceeds 128 < max_chunks. */
    if (chunks >= max_chunks) {
      e = k_ra8_err_hw_error; /* GCOVR_EXCL_LINE -- chunk-budget exhaustion never reached */
      break;                  /* GCOVR_EXCL_LINE -- chunk-budget exhaustion never reached */
    }
    e = internal_download_chunk(g_ra8_ota_cfg.flash.inactive_bank_addr,
                                &s_bytes_done,
                                manifest->image_size_bytes);
    if (e != k_ra8_ok) {
      break;
    }
    ++chunks;
  }
  return e;
}

ra8_err_t ra8_ota_download_to_inactive_bank(const ra8_ota_manifest_t* manifest)
{
  if (!g_ra8_ota_initialized) {
    return k_ra8_err_not_initialized;
  }
  RA8_CHECK_NULL_PTR(manifest, s_tag, "manifest");
  if (priv_ota_download_state_invalid((uint32_t)k_ra8_ota_state_idle,
                                      (uint32_t)k_ra8_ota_state_downloading,
                                      (uint32_t)g_ra8_ota_state)) {
    return k_ra8_err_invalid_state;
  }
  if (manifest->image_size_bytes > g_ra8_ota_cfg.flash.bank_size_bytes) {
    priv_ota_set_state(k_ra8_ota_state_error, k_ra8_err_invalid_size);
    return k_ra8_err_invalid_size;
  }
 
  if (s_bytes_done == 0U) {
    const ra8_err_t e = internal_prepare_bank(manifest);
    if (e != k_ra8_ok) {
      priv_ota_set_state(k_ra8_ota_state_error, e);
      return e;
    }
  }
 
  uint32_t  content_len = 0U;
  ra8_err_t e = g_ra8_ota_cfg.net.open(g_ra8_ota_cfg.net.ctx, manifest->image_url, &content_len);
  if (e != k_ra8_ok) {
    priv_ota_set_state(k_ra8_ota_state_error, e);
    return e;
  }
  priv_ota_set_state(k_ra8_ota_state_downloading, k_ra8_ok);
 
  e = internal_download_loop(manifest);
  (void)g_ra8_ota_cfg.net.close(g_ra8_ota_cfg.net.ctx);
 
  if (e != k_ra8_ok) {
    priv_ota_set_state(k_ra8_ota_state_error, e);
    return e;
  }
  priv_ota_set_state(k_ra8_ota_state_verifying, k_ra8_ok);
  return k_ra8_ok;
}

ra8_err_t ra8_ota_commit_and_reboot(void)
{
  if (!g_ra8_ota_initialized) {
    return k_ra8_err_not_initialized;
  }
  if (g_ra8_ota_state != k_ra8_ota_state_committing) {
    return k_ra8_err_invalid_state;
  }
  const ra8_err_t e = g_ra8_ota_cfg.flash.set_startup(g_ra8_ota_cfg.flash.ctx,
                                                      g_ra8_ota_cfg.flash.inactive_bank_index,
                                                      true);
  if (e != k_ra8_ok) {
    priv_ota_set_state(k_ra8_ota_state_error, e);
    return e;
  }
  priv_ota_set_state(k_ra8_ota_state_done, k_ra8_ok);
  /* On hardware ra8_ota_system_reset_hook is overridden to call
   * NVIC_SystemReset; in the host build it is a no-op. */
  ra8_ota_system_reset_hook();
  return k_ra8_ok;
}

RA8_INTERNAL
static ra8_err_t internal_step_dispatch(void)
{
  switch (g_ra8_ota_state) {
    case k_ra8_ota_state_idle: {
      /* If a previous run_step already fetched and validated the
       * manifest, advance to download instead of re-fetching it. */
      if (s_manifest_valid) {
        return ra8_ota_download_to_inactive_bank(&s_manifest);
      }
      ra8_ota_manifest_t m;
      return ra8_ota_check_for_update(&m);
    }
    /* checking and downloading are always resolved synchronously within a
     * single API call; internal_step_dispatch is never entered while the SM
     * holds one of these transient states in the host build. */
    case k_ra8_ota_state_checking:
    case k_ra8_ota_state_downloading:
      if (s_manifest_valid) {
        return ra8_ota_download_to_inactive_bank(&s_manifest);
      }
      return k_ra8_err_invalid_state;
    case k_ra8_ota_state_verifying:
      return ra8_ota_verify_signature(&s_manifest);
    case k_ra8_ota_state_committing:
      return ra8_ota_commit_and_reboot();
    case k_ra8_ota_state_done:
    case k_ra8_ota_state_error:
    case k_ra8_ota_state_count:
    default:
      return k_ra8_ok;
  }
}

ra8_err_t ra8_ota_run_step(void)
{
  if (!g_ra8_ota_initialized) {
    return k_ra8_err_not_initialized;
  }
  return internal_step_dispatch();
}

ra8_err_t ra8_ota_run_full_update(void)
{
  if (!g_ra8_ota_initialized) {
    return k_ra8_err_not_initialized;
  }
  /* Bounded by the longest legal sequence (idle -> checking ->
   * downloading -> verifying -> committing -> done). Six steps is
   * the upper bound; pad to ``k_ra8_ota_state_count`` for safety. */
  for (uint32_t i = 0U; i < (uint32_t)k_ra8_ota_state_count; ++i) {
    if ((g_ra8_ota_state == k_ra8_ota_state_done) || (g_ra8_ota_state == k_ra8_ota_state_error)) {
      break;
    }
    const ra8_err_t e = ra8_ota_run_step();
    if (e != k_ra8_ok) {
      return e;
    }
  }
  return s_last_err;
}
 
/* =============================================================================
 * Weak system-reset hook: real target overrides this with
 * ``NVIC_SystemReset()``.  Default is a no-op so unit tests don't
 * actually exit the process.
 * ============================================================================= */

#if defined(__GNUC__) || defined(__clang__)
[[gnu::weak]]
#endif
void ra8_ota_system_reset_hook(void)
{
  /* Intentionally empty. */
}