ra8-firmware 0.1.0
Bare-metal firmware for the Renesas RA8 family (RA8D2 / RA8P1)
Loading...
Searching...
No Matches
ra8_dfu_host.h File Reference
Security & TrustZone

Polled on-board USB-DFU host driver, bound to either controller. More...

#include <stdint.h>
#include "ra8_err.h"
#include "ra8_usb.h"
Include dependency graph for ra8_dfu_host.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  ra8_dfu_host_result_t
 Outcome of a DFU round-trip for diagnostics / banners. More...

Functions

ra8_err_t ra8_dfu_host_run (ra8_usb_speed_t host_speed, const uint8_t *img, uint32_t img_len, ra8_dfu_host_result_t *out)
 Enumerate, DFU_DNLOAD img, DFU_ABORT, DFU_UPLOAD, and byte-verify.
ra8_err_t ra8_dfu_host_program (ra8_usb_speed_t host_speed, const uint8_t *img, uint32_t img_len, ra8_dfu_host_result_t *out)
 Enumerate, DFU_DNLOAD img, then a zero-length DFU_DNLOAD (manifest).

Detailed Description

Polled on-board USB-DFU host driver, bound to either controller.

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

The host half of the bidirectional HIL self-loop twins: enumerate the DFU device on the cabled-together jack, DFU_DNLOAD a test image (which the device programs into MRAM), DFU_ABORT back to dfuIDLE, then DFU_UPLOAD it back and byte-compare. Built on the first-party polled ra8_usb_host_* / ra8_usb_host_control_xfer primitives and parameterized by ra8_usb_speed_t, so the same driver runs as the HS host in Config A and the FS host in Config B. Firmware-only (the host test build has no USB controller).

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

Definition in file ra8_dfu_host.h.

Function Documentation

◆ ra8_dfu_host_program()

ra8_err_t ra8_dfu_host_program ( ra8_usb_speed_t host_speed,
const uint8_t * img,
uint32_t img_len,
ra8_dfu_host_result_t * out )
nodiscard

Enumerate, DFU_DNLOAD img, then a zero-length DFU_DNLOAD (manifest).

The real DFU flash flow – what dfu-util does – rather than the self-test round-trip of ra8_dfu_host_run. Brings the host controller up, enumerates the DFU device, downloads img one 64-byte block at a time, then issues a zero-length DFU_DNLOAD that signals end-of-download so the DEVICE commits the slot header (via its worker) and enters dfuMANIFEST. There is no UPLOAD/ABORT: the caller drives the device half on the SAME chip (self-loop) and confirms the commit with ra8_dfu_device_committed + ra8_dfu_slot_valid.

Parameters
[in]host_speedWhich controller acts as host (FS or HS).
[in]imgBootable slot image to flash (non-NULL).
[in]img_lenImage length; non-zero multiple of 64.
[out]outResult/diagnostics (non-NULL; pid populated).
Returns
ra8_err_t outcome (also mirrored in out->last_err).
Return values
k_ra8_okImage downloaded and the manifest accepted.
k_ra8_err_null_ptrimg or out was NULL.
k_ra8_err_invalid_argimg_len is 0 or not a multiple of 64.
k_ra8_err_*The failing enumerate / transfer code.
Precondition
The two USB jacks are cabled together; host_speed is the host jack.
ra8_time_init has run; the device half targets the slot to commit.
Postcondition
On failure the host controller is deinitialized for a clean retry.
The device has been told to commit; the caller polls for completion.
Note
Blocking; runs on the host worker thread.
Since
0.1.0

Definition at line 727 of file ra8_dfu_host.c.

References ra8_dfu_host_result_t::blocks_ok, internal_program_seq(), k_ra8_err_invalid_arg, k_ra8_err_null_ptr, k_ra8_ok, k_rdh_mismatch_none, k_rdh_xfer_size, ra8_dfu_host_result_t::last_err, ra8_dfu_host_result_t::mismatch, ra8_dfu_host_result_t::pid, ra8_usb_host_deinit(), and ra8_usb_host_init().

Referenced by dfu_host_pass().

◆ ra8_dfu_host_run()

ra8_err_t ra8_dfu_host_run ( ra8_usb_speed_t host_speed,
const uint8_t * img,
uint32_t img_len,
ra8_dfu_host_result_t * out )
nodiscard

Enumerate, DFU_DNLOAD img, DFU_ABORT, DFU_UPLOAD, and byte-verify.

Runs the full round-trip on host_speed: brings the host controller up, enumerates the DFU device (bus reset -> GET_DESCRIPTOR -> SET_ADDRESS -> SET_CONFIGURATION, into dfuIDLE), downloads img one 64-byte block at a time (polling DFU_GETSTATUS to dfuDNLOAD-IDLE between blocks), DFU_ABORTs back to dfuIDLE, then uploads each block and compares to img. The device half programs/serves the bytes from real MRAM, so a clean byte-match proves the inactive slot was actually written.

Parameters
[in]host_speedWhich controller acts as host (FS or HS).
[in]imgImage to download + expected upload bytes (non-NULL).
[in]img_lenImage length; non-zero multiple of 64.
[out]outResult/diagnostics (non-NULL).
Returns
ra8_err_t outcome (also mirrored in out->last_err).
Return values
k_ra8_okDownload + upload + byte-verify all passed.
k_ra8_err_null_ptrimg or out was NULL.
k_ra8_err_invalid_argimg_len is 0 or not a multiple of 64.
k_ra8_err_invalid_sizeAn upload block returned the wrong length.
k_ra8_err_invalid_stateAn upload block's bytes differed.
k_ra8_err_*The failing enumerate / transfer code.
Precondition
The two USB jacks are cabled together; host_speed is the host jack.
ra8_time_init has run (ms delays); img_len % 64 == 0.
Postcondition
On any failure the host controller is deinitialized for a clean retry.
out is fully populated.
Note
Blocking; runs on the host worker thread.
Since
0.1.0

Definition at line 641 of file ra8_dfu_host.c.

References ra8_dfu_host_result_t::blocks_ok, internal_run_seq(), k_ra8_err_invalid_arg, k_ra8_err_null_ptr, k_ra8_ok, k_rdh_mismatch_none, k_rdh_xfer_size, ra8_dfu_host_result_t::last_err, ra8_dfu_host_result_t::mismatch, ra8_dfu_host_result_t::pid, ra8_usb_host_deinit(), and ra8_usb_host_init().

Referenced by dfu_host_pass().