Something went wrong. Try again.
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823// oled.cpp — Oled: the display controller chip (Cortex-M0).//// - create() boots the firmware (tick counter and IRQ-flag waits fed by// hooks) and resets the display context.// - send_* queue 8-byte wire frames and run one pass of the REAL// firmware RX dispatch loop; the framebuffer at addr::oled_fb is the// output (read it with framebuffer() / write it with write_pgm()).
#include "targets/oled.hpp"#include "core/hooks.hpp"#include "core/internal.hpp"#include "firmware/addr.hpp"
#include <unicorn/unicorn.h>
#include <algorithm>#include <array>#include <cstdint>#include <cstdio>#include <cstdlib>#include <cstring>#include <memory>#include <print>#include <vector>
namespace mf {
namespace {
constexpr uint32_t FLASH_BASE = 0x08000000U;constexpr uint32_t FLASH_MAP = 0x40000U; // 256 KiB window; payload 0x13EF0, rest 0xFFconstexpr uint32_t RAM_BASE = 0x20000000U;constexpr uint32_t RAM_SIZE = 0x8000U; // 32 KiBconstexpr uint32_t PERIPH_BASE = 0x40000000U;constexpr uint32_t PERIPH_SIZE = 0x1000000U; // APB peripherals (benign)constexpr uint32_t AHB2_BASE = 0x48000000U;constexpr uint32_t AHB2_SIZE = 0x20000U; // GPIOconstexpr uint32_t PPB_BASE = 0xE0000000U;constexpr uint32_t PPB_SIZE = 0x100000U;
// ── fake RX queue (reference _install_queue_hooks) ────────────────────// The dispatch loop calls vtable[0] (read byte) and vtable[1] (avail) on// the object at UART2+0x38. We point it at a RAM object with a RAM// vtable; the method bodies are never executed — host hooks fire at the// aligned addresses and return via PC = LR | 1. Quirks kept from the// reference:// - vtable entries must be ODD (Thumb bit): blx to an even RAM address// flips the CPU to ARM state.// - hooks must be registered at the EVEN aligned address (Unicorn// reports the aligned PC).constexpr uint32_t FAKE_Q = 0x20003000U; // queue object (inside the 32 KiB RAM)constexpr uint32_t VTB = 0x20003010U; // its vtable (read, avail)constexpr uint32_t READ_AT = 0x20003040U; // hook site for vtable[0] (entry: +1)constexpr uint32_t AVAIL_AT = 0x20003048U; // hook site for vtable[1] (entry: +1)
// Return instructions of ssd1306_spi_write's two source/destination-order// branches. At either site the DMA registers have been programmed.constexpr uint32_t OLED_DMA_STARTED_A = 0x08006A82U;constexpr uint32_t OLED_DMA_STARTED_B = 0x08006A8AU;constexpr uint32_t OLED_GPIO_WRITE = 0x08001184U;constexpr uint32_t OLED_DC_GPIO = 0x48000C00U;constexpr uint32_t OLED_DC_MASK = 4U;
constexpr uint32_t kDispatchSp = 0x20002000U; // SP for dispatch passes
} // namespace
// ══ Construction ═════════════════════════════════════════════════════
Oled::Oled(std::optional<uint32_t> font, UnmapPolicy unmap_policy, DiagFn diag, BusObserver bus_observer) : Target(RAM_BASE, RAM_SIZE, std::move(diag)), font_(font), bus_observer_(std::move(bus_observer)) { hook_ctx_.policy = unmap_policy; uc_err const e = uc_open( UC_ARCH_ARM, // NOLINTNEXTLINE(clang-analyzer-optin.core.EnumCastOutOfRange) — Unicorn modes are an OR-able bitmask; 48 is a valid combination. static_cast<uc_mode>(UC_MODE_THUMB | UC_MODE_MCLASS), &uc_); if (e != UC_ERR_OK) { return; // create() reports the failure (uc_ stays null) } // NOLINTNEXTLINE(clang-analyzer-optin.core.EnumCastOutOfRange) — Unicorn CPU ids are bitmask values, not enum members. if (uc_ctl_set_cpu_model(uc_, UC_CPU_ARM_CORTEX_M0) != UC_ERR_OK) { uc_close(uc_); uc_ = nullptr; }}
// ══ Internal hooks ═══════════════════════════════════════════════════
void Oled::tick_hook() { // During boot there is no external OLED clock yet, so the firmware's // timeout reads are the boot-time clock source. Once the target is live, // the explicit timer-wakeup path owns time and this hook is a plain read. if (!boot_complete_) { ++tick_; } uc_mem_write(&uc(), addr::oled_tick_var, &tick_, 4); uc_reg_write(&uc(), UC_ARM_REG_R0, &tick_);}
void Oled::wait_flag_hook() { // The firmware spins on [*oled_flag_obj + 0x10] & 1. A hardware timer // wake both releases this wait and advances the local emulated clock; // model both sides so OLED animations progress while the main loop runs. if (clock_running_) { ++tick_; uc_mem_write(&uc(), addr::oled_tick_var, &tick_, 4); } uint32_t p = 0; uc_mem_read(&uc(), addr::oled_flag_obj, &p, 4); if (p != 0) { uint32_t f = 0; uc_mem_read(&uc(), p + 0x10, &f, 4); f |= 1U; uc_mem_write(&uc(), p + 0x10, &f, 4); } if (clock_running_ && wakes_remaining_ > 0) { --wakes_remaining_; if (wakes_remaining_ == 0) { wait_seen_ = true; (void)uc_emu_stop(&uc()); } } else if (stop_after_wait_) { wait_seen_ = true; (void)uc_emu_stop(&uc()); }}
void Oled::queue_avail_hook() { const uint32_t r0 = ioc_rx_.available() > 0 ? 1U : 0U; uc_reg_write(&uc(), UC_ARM_REG_R0, &r0); uint32_t lr = 0; uc_reg_read(&uc(), UC_ARM_REG_LR, &lr); lr |= 1U; uc_reg_write(&uc(), UC_ARM_REG_PC, &lr); // return to the caller (Thumb)}
void Oled::queue_read_hook() { uint8_t byte = 0; (void)ioc_rx_.read({&byte, 1}); const uint32_t r0 = byte; uc_reg_write(&uc(), UC_ARM_REG_R0, &r0); uint32_t lr = 0; uc_reg_read(&uc(), UC_ARM_REG_LR, &lr); lr |= 1U; uc_reg_write(&uc(), UC_ARM_REG_PC, &lr); // return to the caller (Thumb)}
void Oled::gpio_write_hook() { uint32_t base = 0; uint32_t mask = 0; uint32_t set = 0; uc_reg_read(&uc(), UC_ARM_REG_R0, &base); uc_reg_read(&uc(), UC_ARM_REG_R1, &mask); uc_reg_read(&uc(), UC_ARM_REG_R2, &set); if (base == OLED_DC_GPIO && mask == OLED_DC_MASK) { dc_ = set != 0 ? 1U : 0U; }}
bool Oled::spi_write_hook(uc_mem_type /*type*/, uint64_t address, int size, int64_t value) { if (address > 0x4001300CU || address + static_cast<uint64_t>(size) <= 0x4001300CU) { return true; } const uint64_t offset = 0x4001300CU - address; const int count = std::min(size - static_cast<int>(offset), static_cast<int>(direct_bytes_.size())); for (int i = 0; i < count; ++i) { direct_bytes_[static_cast<size_t>(i)] = static_cast<uint8_t>(static_cast<uint64_t>(value) >> (8U * (i + offset))); } if (bus_observer_ && count > 0) { bus_observer_(BusTransfer{tick_, 0, 0, 0x4001300CU, dc_, {direct_bytes_.data(), static_cast<size_t>(count)}}); } return true;}
void Oled::boot_main_loop_hook() { if (!boot_complete_) { boot_main_loop_seen_ = true; (void)uc_emu_stop(&uc()); }}
void Oled::display_update_hook() { uc_reg_read(&uc(), UC_ARM_REG_R0, &display_driver_);}
// Model the missing local SSD1306 DMA peer. The firmware's DMA ISR clears the// busy state and invokes the callbacks that advance/finish a split transfer.// Complete transfers immediately after ssd1306_spi_write programs the channel;// this preserves firmware control flow without tying progress to an arbitrary// host polling frequency.void Oled::display_dma_started_hook() { // The local SSD1306 DMA has no peripheral peer in Unicorn. This is the // first point at which the firmware has accepted the source buffer and // programmed the physical transfer. Observe the source here; the real // DMA ISR is serviced outside the code hook. Neither observer is a host // framebuffer poll or an optimistic upload request. if (stop_after_dma_) { uint32_t pc = 0; uc_reg_read(&uc(), UC_ARM_REG_PC, &pc); if (skip_dma_pc_ == pc) { skip_dma_pc_ = 0; return; } }
uint32_t stream = 0; uint32_t length = 0; uint32_t peripheral = 0; uint32_t source = 0; if ((bus_observer_ || commit_observer_ != nullptr) && uc_mem_read(&uc(), addr::oled_dma_handle, &stream, sizeof(stream)) == UC_ERR_OK && stream != 0 && uc_mem_read(&uc(), stream + 4U, &length, sizeof(length)) == UC_ERR_OK && uc_mem_read(&uc(), stream + 8U, &peripheral, sizeof(peripheral)) == UC_ERR_OK && uc_mem_read(&uc(), stream + 12U, &source, sizeof(source)) == UC_ERR_OK) { bus_bytes_.resize(length); if (length == 0 || uc_mem_read(&uc(), source, bus_bytes_.data(), length) == UC_ERR_OK) { if (bus_observer_) { bus_observer_(BusTransfer{tick_, stream, source, peripheral, dc_, bus_bytes_}); } if (commit_observer_ != nullptr && source == addr::oled_fb && length == frame_bytes_.size()) { std::copy(bus_bytes_.begin(), bus_bytes_.end(), frame_bytes_.begin()); (*commit_observer_)(frame_bytes_, tick_); } } }
if (stop_after_dma_) { dma_seen_ = true; dma_pending_ = true; uint32_t pc = 0; uc_reg_read(&uc(), UC_ARM_REG_PC, &pc); (void)uc_emu_stop(&uc()); return; } dma_pending_ = true;}
void Oled::service_display_dma() { if (!dma_pending_ || servicing_display_dma_) { return; } dma_pending_ = false; servicing_display_dma_ = true; struct ServiceReset { bool &active; ~ServiceReset() { active = false; } } reset{servicing_display_dma_};
{ uint32_t dma_base = 0; uint32_t shift = 0; if (uc_mem_read(&uc(), addr::oled_dma_handle + 0x3CU, &dma_base, sizeof(dma_base)) != UC_ERR_OK || uc_mem_read(&uc(), addr::oled_dma_handle + 0x40U, &shift, sizeof(shift)) != UC_ERR_OK || dma_base == 0 || shift >= 28U) { return; } uint32_t isr = 0; if (uc_mem_read(&uc(), dma_base, &isr, sizeof(isr)) != UC_ERR_OK) { return; } // The SPI status register is the other half of the DMA/IRQ handshake. // Set TX-ready/bus-state bits so the real ISR takes its completion // callback instead of treating the flat peripheral as idle. const uint32_t spi = 0x40013000U; const uint32_t spi_status = 0x08U; (void)uc_mem_write(&uc(), spi, &spi_status, sizeof(spi_status));
// STM32 DMA ISR layout: TCIF is bit (1 + channel_shift). The handler // reads ISR through handle+0x3c and acknowledges through IFCR. const uint32_t tcif = 8U << shift; isr |= tcif; (void)uc_mem_write(&uc(), dma_base, &isr, sizeof(isr)); try { (void)call(addr::oled_dma_irq, CallArgs{}); if (display_driver_ != 0) { const uint8_t idle = 0; const uint8_t ready = 1; uc_mem_write(&uc(), display_driver_ + 0x20U, &idle, sizeof(idle)); uc_mem_write(&uc(), display_driver_ + 0x21U, &ready, sizeof(ready));
// display_driver_ is the DMA handle. Its owner at +0x24 is // the SPI/display context used by ssd1306_draw_region(); // the real DMA callback releases that context's +0x5d busy // byte, but the peripheral cannot generate that side effect // in flat Unicorn memory. uint32_t owner = 0; uc_mem_read(&uc(), display_driver_ + 0x24U, &owner, sizeof(owner)); if (owner != 0) { uc_mem_write(&uc(), owner + 0x5DU, &ready, sizeof(ready)); } } } catch (const Error &e) { std::println(stderr, "oled display DMA ISR failed: {}", e.what()); faulted_ = true; return; } // IFCR writes have no side effects in flat Unicorn peripheral memory. // Apply the hardware's corresponding ISR clear explicitly. isr &= ~tcif; (void)uc_mem_write(&uc(), dma_base, &isr, sizeof(isr)); }}
// ══ Command injection ════════════════════════════════════════════════
Oled::Frame Oled::text_append_frame(std::string_view text) { if (text.empty() || text.size() > 4) { throw Error{Status::argument, "OLED text append must contain 1..4 bytes"}; } std::array<uint8_t, 4> chars{}; for (size_t i = 0; i < text.size(); i++) { chars[i] = static_cast<uint8_t>(text[i]); } if (text.size() == 4) { return frame_build(0xF7, 0x72, chars[0], chars[1], chars[2], chars[3]); } return frame_build(0xF7, 0x71, chars[0], chars[1], chars[2], static_cast<uint8_t>(text.size()));}
// Run one dispatch pass over the queued bytes (reference send()): point// the uart2 object's RX queue at the fake queue (the firmware init// overwrites it at boot), set up the call registers, and run the real// dispatch loop with an instruction cap that also covers the main-loop// tail after LR.namespace {std::vector<uint32_t> g_trace;void trace_hook(uc_engine * /*uc*/, uint64_t addr, uint32_t /*size*/, void * /*user*/) { g_trace.push_back(static_cast<uint32_t>(addr));}bool enqueue_frame(IocRxQueue &queue, const std::array<uint8_t, 8> &frame) { return queue.write(std::span<const uint8_t>{frame});}
} // namespace
void Oled::dispatch(const FrameObserver &on_commit) { dispatch_impl(on_commit);}
void Oled::dispatch_until_idle(const FrameObserver &on_commit) { dispatch_impl(on_commit);}
void Oled::dispatch_impl(const FrameObserver &on_commit) { if (faulted_) { throw Error{Status::state, "oled faulted; destroy it"}; } if (ioc_rx_.available() == 0) { return; } const auto *previous_observer = commit_observer_; commit_observer_ = on_commit ? &on_commit : nullptr; struct ObserverReset { const FrameObserver *&slot; const FrameObserver *previous; ~ObserverReset() { slot = previous; } } observer_reset{commit_observer_, previous_observer}; const bool previous_stop = stop_after_wait_; stop_after_wait_ = true; wait_seen_ = false; struct StopReset { bool &stop; bool previous; ~StopReset() { stop = previous; } } stop_reset{stop_after_wait_, previous_stop};
uc_engine *uc = uc_; uc_hook trace_hook_id = 0; g_trace.clear(); if (std::getenv("MF_DISPATCH_TRACE") != nullptr) { uc_hook_add(uc, &trace_hook_id, UC_HOOK_CODE, reinterpret_cast<void *>(trace_hook), nullptr, 1, 0); } const auto remove_trace = [&]() { if (trace_hook_id != 0) { (void)uc_hook_del(uc, trace_hook_id); } };
const uint32_t q = FAKE_Q; uc_mem_write(uc, addr::oled_uart2_obj + 0x38, &q, 4); const uint32_t sp = kDispatchSp; const uint32_t r0 = addr::oled_uart2_obj; const uint32_t r1 = 0; const uint32_t lr = addr::oled_main_loop | 1U; uc_reg_write(uc, UC_ARM_REG_SP, &sp); uc_reg_write(uc, UC_ARM_REG_R0, &r0); uc_reg_write(uc, UC_ARM_REG_R1, &r1); uc_reg_write(uc, UC_ARM_REG_LR, &lr);
// A redraw can span several firmware wait boundaries (glyph rendering // plus the chip's internal idle loop). Re-enter until the queue is // drained; the state machine lives in chip RAM and each pass resumes at // the next byte. for (int pass = 0;; ++pass) { // Do not abandon a handler when the RX queue becomes empty halfway // through rendering. The wait hook supplies the real firmware // boundary, so no in-flight CPU state is lost. const uc_err e = emu_start(addr::oled_dispatch | 1U, 0); if (e != UC_ERR_OK) { faulted_ = true; std::array<char, 96> msg{}; std::snprintf(msg.data(), msg.size(), "oled dispatch: %s", detail::uc_err_str(e)); remove_trace(); throw Error{Status::emulator, msg.data()}; } service_display_dma(); if (ioc_rx_.available() == 0) { if (std::getenv("MF_DISPATCH_DEBUG") != nullptr) { std::println(stderr, "oled dispatch: drained in {} passes", pass + 1); } static unsigned trace_seq = 0; if (std::getenv("MF_DISPATCH_TRACE") != nullptr) { char path[64]; std::snprintf(path, sizeof(path), "/tmp/oled_trace_%02u.bin", trace_seq++); if (auto tf = std::fopen(path, "wb"); tf != nullptr) { std::fwrite(g_trace.data(), 4, g_trace.size(), tf); std::fclose(tf); std::println(stderr, "oled dispatch: traced {} pcs", g_trace.size()); } } remove_trace(); return; } }}
void Oled::advance_ticks(const uint32_t ticks, const FrameObserver &on_commit) { if (faulted_) { throw Error{Status::state, "oled faulted; destroy it"}; } if (ioc_rx_.available() != 0) { throw Error{Status::state, "OLED timer advance requires an empty RX queue"}; } if (ticks == 0) { return; }
const auto *previous_observer = commit_observer_; commit_observer_ = on_commit ? &on_commit : nullptr; struct ObserverReset { const FrameObserver *&slot; const FrameObserver *previous; ~ObserverReset() { slot = previous; } } observer_reset{commit_observer_, previous_observer};
// Match dispatch()'s boundary setup. The firmware returns from the RX // pass into its permanent main loop. Stop only for a requested timer // count or a programmed DMA transfer, so the missing peripheral can be // serviced without polling the framebuffer or paying one emulation start // per timer wake. const uint32_t q = FAKE_Q; uc_mem_write(&uc(), addr::oled_uart2_obj + 0x38, &q, 4); const uint32_t sp = kDispatchSp; const uint32_t r0 = addr::oled_uart2_obj; const uint32_t r1 = 0; const uint32_t lr = addr::oled_main_loop | 1U; uc_reg_write(&uc(), UC_ARM_REG_SP, &sp); uc_reg_write(&uc(), UC_ARM_REG_R0, &r0); uc_reg_write(&uc(), UC_ARM_REG_R1, &r1); uc_reg_write(&uc(), UC_ARM_REG_LR, &lr);
const bool previous_stop = stop_after_wait_; const bool previous_dma = stop_after_dma_; const bool previous_clock = clock_running_; const uint32_t previous_wakes = wakes_remaining_; const uint32_t previous_skip_pc = skip_dma_pc_; stop_after_wait_ = false; stop_after_dma_ = true; clock_running_ = true; wakes_remaining_ = ticks; struct AdvanceReset { bool &stop; bool &dma; bool &clock; uint32_t &wakes; uint32_t &skip_pc; bool previous_stop; bool previous_dma; bool previous_clock; uint32_t previous_wakes; uint32_t previous_skip_pc; ~AdvanceReset() { stop = previous_stop; dma = previous_dma; clock = previous_clock; wakes = previous_wakes; skip_pc = previous_skip_pc; } } advance_reset{stop_after_wait_, stop_after_dma_, clock_running_, wakes_remaining_, skip_dma_pc_, previous_stop, previous_dma, previous_clock, previous_wakes, previous_skip_pc}; uint32_t start_pc = addr::oled_dispatch | 1U; while (wakes_remaining_ != 0) { wait_seen_ = false; dma_seen_ = false; // The timer/DMA hooks are the completion conditions; the unbounded // run continues until one of those events. const uc_err e = emu_start(start_pc, 0); service_display_dma(); if (dma_seen_) { uint32_t pc = 0; uc_reg_read(&uc(), UC_ARM_REG_PC, &pc); skip_dma_pc_ = pc; start_pc = pc | 1U; } else { start_pc = addr::oled_dispatch | 1U; } if (e != UC_ERR_OK) { faulted_ = true; uint32_t pc = 0; uint32_t fault_lr = 0; uc_reg_read(&uc(), UC_ARM_REG_PC, &pc); uc_reg_read(&uc(), UC_ARM_REG_LR, &fault_lr); std::array<char, 128> msg{}; std::snprintf(msg.data(), msg.size(), "oled timer advance: %s pc=0x%08x lr=0x%08x", detail::uc_err_str(e), pc, fault_lr); throw Error{Status::emulator, msg.data()}; } if (!wait_seen_ && !dma_seen_) { faulted_ = true; throw Error{Status::budget, "OLED timer advance did not reach a timer or DMA event"}; } }}
void Oled::send_text(std::string_view text, bool draw) { if (faulted_) { throw Error{Status::state, "oled faulted; destroy it"}; } const size_t text_frames = (text.size() + 3U) / 4U; if (text_frames + (draw ? 1U : 0U) > ioc_rx_.writable() / 8U) { throw Error{Status::resource, "oled IOC RX queue overflow"}; } // Append frames: 1..4 chars each (display cmd handler, m1 & 3 path). // 1..3 chars: m1=0x71, chars in m2..m4 (zero-padded), len in m5 // 4 chars: m1=0x72, chars in m2..m5 for (size_t i = 0; i < text.size(); i += 4) { const auto f = text_append_frame(text.substr(i, std::min<size_t>(4, text.size() - i))); if (!enqueue_frame(ioc_rx_, f)) { throw Error{Status::resource, "oled IOC RX queue overflow"}; } } if (draw) { // clear + centered text: oled_display_cmd(0x1A, 3) — queued into // the SAME dispatch pass as the text frames (reference send_text). if (!enqueue_frame(ioc_rx_, display_cmd_frame(0x1A, 3))) { throw Error{Status::resource, "oled IOC RX queue overflow"}; } } dispatch();}
void Oled::send_display_cmd(uint8_t cmd, uint16_t param) { if (faulted_) { throw Error{Status::state, "oled faulted; destroy it"}; } // Existing queued bytes are preserved; callers that need a fresh stream // can clear ioc_rx() explicitly. display_cmd_frame masks the 11-bit // parameter field exactly as the firmware decoder does. if (!enqueue_frame(ioc_rx_, display_cmd_frame(cmd, param))) { throw Error{Status::resource, "oled IOC RX queue overflow"}; } dispatch();}
void Oled::send_bytes(std::span<const uint8_t> bytes) { if (faulted_) { throw Error{Status::state, "oled faulted; destroy it"}; } if (!ioc_rx_.write(bytes)) { throw Error{Status::resource, "oled IOC RX queue overflow"}; } dispatch();}
void Oled::send_frame(const Frame &frame) { send_bytes(frame);}
void Oled::send_frames(std::span<const Frame> frames) { if (faulted_) { throw Error{Status::state, "oled faulted; destroy it"}; } if (frames.size() > ioc_rx_.writable() / 8U) { throw Error{Status::resource, "oled IOC RX queue overflow"}; } for (const auto &frame : frames) { if (!enqueue_frame(ioc_rx_, frame)) { throw Error{Status::resource, "oled IOC RX queue overflow"}; } } dispatch();}
// ══ Output ═══════════════════════════════════════════════════════════
Oled::DisplayState Oled::display_state() const { DisplayState state; std::array<uint8_t, 0x13> ctx{}; if (uc_mem_read(uc_, addr::oled_display_ctx, ctx.data(), ctx.size()) != UC_ERR_OK || uc_mem_read(uc_, addr::oled_font_slot, &state.font, sizeof(state.font)) != UC_ERR_OK || uc_mem_read(uc_, addr::oled_text_len, &state.text_len, sizeof(state.text_len)) != UC_ERR_OK || uc_mem_read(uc_, addr::oled_text_buf, state.text.data(), state.text.size()) != UC_ERR_OK || uc_mem_read(uc_, addr::oled_scratch, state.scratch.data(), state.scratch.size()) != UC_ERR_OK) { throw Error{Status::emulator, "OLED display state read failed"}; } state.sub_screen = ctx[0x00]; state.dirty = ctx[0x01]; state.layout_text = ctx[0x11]; state.mode = ctx[0x12]; return state;}
Oled::Snapshot Oled::save_snapshot() { if (faulted_) { throw Error{Status::state, "oled faulted; destroy it"}; } if (ioc_rx_.available() != 0) { throw Error{Status::state, "OLED snapshot requires an empty RX queue"}; } return Snapshot{save_ram(), save_state(), tick_};}
void Oled::restore_snapshot(const Snapshot &snapshot) { restore_ram(snapshot.ram); restore_state(snapshot.cpu); tick_ = snapshot.tick; faulted_ = false; ioc_rx_.clear();}
std::array<uint8_t, 1024> Oled::framebuffer() const { std::array<uint8_t, 1024> fb{}; if (uc_mem_read(uc_, addr::oled_fb, fb.data(), fb.size()) != UC_ERR_OK) { throw Error{Status::emulator, "OLED framebuffer read failed"}; } return fb;}
void Oled::write_pgm(const std::string &path, unsigned scale) const { if (scale == 0) { throw Error{Status::argument, "scale must be >= 1"}; } const auto fb = framebuffer(); const unsigned w = 128 * scale; const unsigned h = 64 * scale;
std::vector<std::byte> img; img.reserve(static_cast<size_t>(w) * h + 16); const auto append = [&img](const char *s, size_t n) { const auto *b = reinterpret_cast<const std::byte *>(s); img.insert(img.end(), b, b + n); }; char header[32]; const int hdr_len = std::snprintf(header, sizeof(header), "P5\n%u %u\n255\n", w, h); append(header, static_cast<size_t>(hdr_len));
// SSD1306 layout: pixel (x, y) = bit (y % 8) of fb[(y / 8) * 128 + x]; // dark glyphs on white (reference dump_pgm). for (unsigned yy = 0; yy < h; yy++) { const unsigned y = yy / scale; for (unsigned xx = 0; xx < w; xx++) { const unsigned x = xx / scale; const unsigned bit = (fb[(y / 8) * 128 + x] >> (y % 8)) & 1U; img.push_back(static_cast<std::byte>(bit == 0 ? 255 : 0)); } } detail::write_file(path, img);}
// ══ create ═══════════════════════════════════════════════════════════
std::unique_ptr<Oled> Oled::create(std::span<const std::byte> firmware, std::optional<uint32_t> font, UnmapPolicy unmap_policy, DiagFn diag, FrameObserver on_commit, BusObserver on_bus) { if (firmware.empty()) { throw Error{Status::argument, "firmware bytes required"}; } std::unique_ptr<Oled> o( new Oled(font, unmap_policy, std::move(diag), std::move(on_bus))); if (o->uc_ == nullptr) { throw Error{Status::emulator, "uc_open failed"}; } uc_engine *uc = o->uc_; o->hook_ctx_.counters = &o->counters_;
struct Region { uint32_t base; uint32_t size; }; static constexpr std::array<Region, 6> kRegions{{ {FLASH_BASE, FLASH_MAP}, {RAM_BASE, RAM_SIZE}, {detail::kStubBase, detail::kStubSize}, {PERIPH_BASE, PERIPH_SIZE}, {AHB2_BASE, AHB2_SIZE}, {PPB_BASE, PPB_SIZE}, }}; for (const auto &r : kRegions) { const uc_err e = uc_mem_map(uc, r.base, r.size, UC_PROT_ALL); if (e != UC_ERR_OK && e != UC_ERR_MAP) { throw Error{Status::emulator, "uc_mem_map failed"}; } }
// Hooks. All registrations checked — a silently missing hook would // hang the boot on the first tick/flag wait. o->hook_ctx_.engine = uc; if (!code_hook_add<&Oled::tick_hook>(uc, addr::oled_tick_fn, o.get()) || !code_hook_add<&Oled::wait_flag_hook>(uc, addr::oled_wait_fn, o.get()) || !code_hook_add<&Oled::queue_read_hook>(uc, READ_AT, o.get()) || !code_hook_add<&Oled::queue_avail_hook>(uc, AVAIL_AT, o.get()) || !code_hook_add<&Oled::gpio_write_hook>(uc, OLED_GPIO_WRITE, o.get()) || !code_hook_add<&Oled::boot_main_loop_hook>(uc, addr::oled_main_loop, o.get()) || !code_hook_add<&Oled::display_update_hook>(uc, addr::oled_ssd1306_update, o.get()) || !code_hook_add<&Oled::display_dma_started_hook>(uc, OLED_DMA_STARTED_A, o.get()) || !code_hook_add<&Oled::display_dma_started_hook>(uc, OLED_DMA_STARTED_B, o.get()) || !mem_hook_add<&Oled::spi_write_hook>(uc, UC_HOOK_MEM_WRITE, 0x4001300CU, 0x4001300FU, o.get()) || !mem_hook_add<detail::unmapped_hook>(uc, UC_HOOK_MEM_UNMAPPED, 1, 0, &o->hook_ctx_)) { throw Error{Status::emulator, "uc_hook_add failed"}; }
// Fake RX queue object + vtable + nop bodies (see the constants above). const uint32_t vtb = VTB; uc_mem_write(uc, FAKE_Q, &vtb, 4); const uint32_t entries[2] = {READ_AT + 1U, AVAIL_AT + 1U}; // odd: Thumb uc_mem_write(uc, VTB, entries, sizeof(entries)); const std::array<uint8_t, 8> nops{0xBF, 0x00, 0xBF, 0x00, 0xBF, 0x00, 0xBF, 0x00}; uc_mem_write(uc, READ_AT, nops.data(), nops.size()); uc_mem_write(uc, AVAIL_AT, nops.data(), nops.size());
// Firmware payload (skip the 64-byte DFU header); the rest of the // 256 KiB window stays 0xFF — erased-flash state, as in the reference. if (firmware.size() <= 64) { throw Error{Status::unsupported, "image too small (need header+payload)"}; } const size_t payload_size = std::min(firmware.size() - 64, static_cast<size_t>(FLASH_MAP)); std::vector<std::byte> image(FLASH_MAP, std::byte{0xFF}); std::memcpy(image.data(), firmware.data() + 64, payload_size); if (uc_mem_write(uc, addr::oled_fw_load, image.data(), image.size()) != UC_ERR_OK) { throw Error{Status::emulator, "firmware write failed"}; }
// Boot from the SystemInit-skipping entry. The local SSD1306 has no DMA // peer in Unicorn, so stop at every programmed transfer, run the real DMA // ISR, and resume at the instruction after the hook. Stop once main's // permanent loop is reached; otherwise the initialization command stream // would leave the driver busy after its first byte (usually 0x81). const uint32_t sp = addr::oled_msp; uc_reg_write(uc, UC_ARM_REG_SP, &sp); o->commit_observer_ = on_commit ? &on_commit : nullptr; o->stop_after_dma_ = true; o->boot_main_loop_seen_ = false; o->skip_dma_pc_ = 0; uint32_t start_pc = addr::oled_boot_entry | 1U; uc_err e = UC_ERR_OK; constexpr unsigned kBootPasses = 128; for (unsigned pass = 0; pass < kBootPasses && !o->boot_main_loop_seen_; ++pass) { o->dma_seen_ = false; e = o->emu_start(start_pc, 0); o->service_display_dma(); if (e != UC_ERR_OK || o->boot_main_loop_seen_) { break; } if (!o->dma_seen_) { throw Error{Status::budget, "OLED boot did not reach DMA or main loop"}; } uint32_t pc = 0; uc_reg_read(uc, UC_ARM_REG_PC, &pc); o->skip_dma_pc_ = pc; start_pc = pc | 1U; } o->stop_after_dma_ = false; o->skip_dma_pc_ = 0; o->commit_observer_ = nullptr; if (e != UC_ERR_OK) { o->faulted_ = true; std::array<char, 96> msg{}; std::snprintf(msg.data(), msg.size(), "oled boot: %s", detail::uc_err_str(e)); throw Error{Status::boot, msg.data()}; } if (!o->boot_main_loop_seen_) { o->faulted_ = true; throw Error{Status::budget, "OLED boot did not reach main loop"}; }
// Display context reset (reference __init__ tail). The firmware's // main() selects the sans-serif font into FONT_SLOT at boot; the // default config re-writes the same value (reference behaviour), // nullopt keeps the firmware's own selection. if (o->font_.has_value()) { const uint32_t font_sel = *o->font_; uc_mem_write(uc, addr::oled_font_slot, &font_sel, 4); } const uint32_t zero4 = 0; uc_mem_write(uc, addr::oled_text_len, &zero4, 4); const std::array<uint8_t, 64> zeros64{}; uc_mem_write(uc, addr::oled_text_buf, zeros64.data(), zeros64.size()); const std::array<uint8_t, 1024> zeros_fb{}; uc_mem_write(uc, addr::oled_fb, zeros_fb.data(), zeros_fb.size());
o->boot_complete_ = true; o->loginfo("oled booted"); return o;}
} // namespace mf