mckero
2154f80414
The previous commit removed three TRACE fprintfs from py32f071.c as
cleanup. That silently broke the keypad completely -- no press reached the
UI, and nothing warned about it.
Root cause is dead-code elimination, not the printing.
qdev_init_gpio_out_named() is inlinable and only records the row_out array;
the lines are filled in later by qdev_connect_gpio_out_named() from board
code, which GCC cannot see. At -O2 GCC therefore proves every element is
still NULL, sees that qemu_set_irq() returns immediately on a NULL irq, and
deletes the body of keypad_update_rows() along with all five calls to it. No
row line is ever driven and the firmware's scan reads all-high.
From the object code:
callers reaching keypad_update_rows
plain none -- the calls are gone
volatile keypad_key_changed, keypad_col_changed, keypad_set_press,
keypad_reset, uvk5_machine_init
keypad_col_changed compiles to a store and a ret with no call at all; with
volatile it ends in jmp keypad_update_rows. Declaring row_out volatile fixes
it at the cause. 10/10 on the press test, 3/3 on keypad_test.py, no build
warnings.
Scoped rather than assumed: PY32GpioState::out is not affected. Marking it
volatile too gives a byte-identical object file, because py32_gpio_write()
is only reachable through a MemoryRegionOps function-pointer table so GCC
cannot enumerate its callers. It stays plain.
Adds tools/keypad_test.py: boots its own instance on private ports and
checks that a short MENU press opens the menu, DOWN moves the cursor, and a
held key is visible to the scan. This is what should have caught the
breakage before it was pushed.
Docs corrected. The breakage had been written up as "power save stops the
keypad scan" and called a gap in the model; it was neither. AGENTS.md now
records the mechanism, the measurements, the objdump check, and the two
measurement traps that made this hard: reading gKeyReading0 after releasing
the key (always KEY_INVALID), and trusting a gdb breakpoint on
KEYBOARD_Poll (with the guest stopped the scan's delays cost no guest time,
so Poll returns KEY_MENU on a build where it fails when running free).
README screenshots regenerated from the current build.
UV-K5 V3 emulator
Runs Quansheng UV-K5 V3 / UV-K1 firmware on a PC. The radio uses a Puya PY32F071 (Cortex-M0+), which QEMU has no machine for, so this adds one.
The firmware boots to its main loop in about five seconds, the LCD contents are readable, and the keypad drives the menus. See Status for what is and is not modelled.
| Main screen | Menu | Navigated with keys |
|---|---|---|
 |
 |
 |
Real captures, not mock-ups: tools/screenshot.py reads the firmware's
gFrameBuffer out of guest memory and renders it, so these are the pixels the
LCD driver actually wrote. Left to right: the dual-watch main screen, the menu
opened with key.py MENU (entry 01/79, Step), and 03/79 after key.py DOWN DOWN.
What it is for
Editing firmware and reflashing a radio to test one line is slow, and some bugs are invisible from the outside. A recent example: CW macro recording appeared to do nothing, and the cause was three layers down -- the keyer was being torn down by a later call that recomputed its state from the wrong VFO. On hardware you see "nothing happens"; here you can read the actual variables.
What it does not do is model radio behaviour. It reproduces what the firmware commanded -- frequency, power step, carrier keying in time -- not the analogue result. Keying envelopes, spurious emissions and sensitivity need a real radio and a spectrum analyser. That is not a gap to be closed later; the transceiver chip has no public datasheet, so its driver is the only specification available.
Status
| Area | State |
|---|---|
| Boot to main loop | works, ~5 s |
| LCD contents | readable via tools/screenshot.py |
| SPI flash, settings, calibration | works |
| Keypad and menu navigation | works, including waking from power save |
| Timing accuracy | deliberately wrong, see Timing |
| Radio/RF behaviour | not modelled |
A short tools/key.py MENU opens the menu, UP/DOWN move through it, MENU enters
a submenu, and typing a menu number jumps straight to that entry. Press duration
decides short versus held, which the firmware treats as different events -- see
Timing.
Press duration is the thing to get right. A hold of 400 ms or more is a long
press, and handlers act on it differently: MAIN_Key_MENU opens the menu on a
short release and does nothing on the hold path. If a key seems ignored, shorten
the press rather than lengthening it. Waking from power save needs nothing
special -- one 200 ms press both wakes the radio and opens the menu, verified
after 45 s of idle.
tools/keypad_test.py checks all of this against a throwaway QEMU instance. It
exists because the keypad has one non-obvious trap: the keypad model's row_out
array must stay volatile, or GCC at -O2 proves the lines are still NULL and
deletes every call to keypad_update_rows(), so no row is ever driven and
keypresses silently stop working. Run the test after touching that code;
AGENTS.md has the object-code evidence.
Layout
qemu/ QEMU sources to be copied into a QEMU tree
py32f071.c the SoC and machine (the bulk of the work)
armv7m_systick.*.patched SysTick with the poll-boost property added
assets/
calibration.bin 512-byte dump from a real radio
docs/screenshots/ LCD captures used in this README
tools/ run, screenshot, inject keys, probe state
harness/, stubs/, shim/, tests/ host build of the CW timing chain (stage A)
Building
Needs a QEMU 7.2 source tree, meson, ninja, libfdt-dev, libglib2.0-dev,
libpixman-1-dev.
# 1. Drop the sources into a QEMU tree
cp qemu/py32f071.c $QEMU/hw/arm/
cp qemu/armv7m_systick.c.patched $QEMU/hw/timer/armv7m_systick.c
cp qemu/armv7m_systick.h.patched $QEMU/include/hw/timer/armv7m_systick.h
# 2. Register the machine. In $QEMU/hw/arm/Kconfig:
# config UVK5_V3
# bool
# default y
# depends on TCG && ARM
# select PY32F071_SOC
# config PY32F071_SOC
# bool
# select ARM_V7M
# select UNIMP
# In $QEMU/hw/arm/meson.build:
# arm_ss.add(when: 'CONFIG_UVK5_V3', if_true: files('py32f071.c'))
# 3. Build just the ARM target
cd $QEMU
./configure --target-list=arm-softmmu --disable-docs --disable-tools
cd build && ninja qemu-system-arm
Running
python3 tools/make_flash.py # once, builds assets/flash.img
tools/run.sh # starts the machine
tools/where.sh # where the firmware is executing
python3 tools/screenshot.py --frame-addr 0x200013DC \
--status-addr 0x2000175C --port 1234 --out screen.png
python3 tools/key.py MENU # inject a keypress
tools/gpiob_dump.sh # GPIOB registers
The machine exposes a GDB stub on port 1234 and a QMP socket at
/tmp/uvk5-qmp.sock. It is headless: the screen is read out of guest memory
rather than drawn, so no display backend is needed.
Screenshots need the addresses of gFrameBuffer and gStatusLine, which move
between builds. Find them with:
arm-none-eabi-nm firmware.elf | grep -E 'gFrameBuffer|gStatusLine'
How the machine is put together
Register layouts come from the vendor CMSIS header shipped with the firmware
(Drivers/CMSIS/Device/PY32F071/Include/py32f071xB.h), not from guesswork.
FLASH 0x08000000 128 KB application at +0x2800, bootloader below it
SRAM 0x20000000 16 KB
RCC 0x40021000
GPIO 0x50000000 ports A, B, C, F at 0x400 intervals
SPI1 0x40013000 display
SPI2 0x40003800 flash
ADC1 0x40012400
Modelled: RCC, GPIO, ADC, both SPI controllers, DMA1, and the PY25Q16 flash. Everything else answers through a logging catch-all — the log is how the next thing worth modelling gets identified.
Seven things had to be right before the firmware would boot, each found by watching where it stopped:
- Flash alias at the application offset. The core fetches its vector table from address 0, and the image loads at 0x08002800, so 0 has to alias there and not at the flash base.
- Clock ready bits.
BOARD_Initpolls them; each enable bit is mirrored into its ready bit. - ADC calibration.
CR2.CALis write-1-to-start and hardware-cleared, so it must never be stored set or the wait loop never exits. - SPI flags. Transfers complete inside the register write, so TXE stays asserted and RXNE is raised by the write.
- DMA. The flash driver never touches the SPI data register — it arms channels 4 and 5, enables the transfer-complete interrupt and spins on a flag its ISR sets.
- SysTick. See below.
- Transceiver data line.
RADIO_SetupRegisterswaits for bit 0 of the BK4819 REG_0C to clear. The bus is bit-banged over GPIO, so PB9 idles low until that bus has a real model, making reads return zero.
Timing
SYSTICK_DelayUs polls the SysTick counter and accumulates differences. On
hardware each loop iteration advances the counter by tens of ticks; under
emulation a register read costs far more relative to guest time, so the counter
barely moves per read. Measured: a 120 ms delay advanced 832 of 5,760,000
required ticks in four seconds — about 7.7 hours to complete.
Lowering the clock does not help, which is worth knowing before trying it: the bottleneck is loop iterations per second, not counter speed. Dropping 48 MHz to 200 Hz gained only 32x.
What works is reporting a counter value that runs ahead of the real one, growing
with every read. The poll-boost property on SysTick does that. Two earlier
attempts wrote the value back into the timer instead, which made each read
re-anchor the count — the reported value stopped changing, the firmware's
if (cur != prev) guard never fired, and the loop hung outright.
The consequence is that guest time runs fast during any delay. Fine for exercising menus and control flow; wrong for judging signal timing.
poll-boost accelerates counter reads only. SysTick interrupts still
fire at close to real time, and those are what drive SysTick_Handler ->
gNextTimeslice -> APP_TimeSlice10ms -> CheckKeys. So the firmware's 10 ms
timeslice thresholds hold in wall clock: a key must be down for 20 ms to
register and 400 ms makes it a long press.
Keeping those two apart matters. tools/key.py originally held keys for 2500 ms
on the assumption that guest time ran fast here too, which turned every press
into a long press. Handlers that act on a short release — MAIN_Key_MENU among
them — ignored all of it, and the keypad looked broken when it was not.
Stage A: the CW timing chain on the host
harness/, stubs/, shim/ and tests/ compile app/cwkeyer.c and
app/cwmacro.c unmodified against stub drivers, with a virtual clock and
scripted paddle input. Feed a timeline of contact closures, assert on the decoded
characters and element durations.
Firmware sources are compiled as-is on purpose. Editing them to make them build
on a host would let the tests drift from what the radio runs. The debounce in
CW_ReadKeys is transcribed rather than stubbed, because its asymmetry (three
consecutive reads to register a press, immediate release) is part of the timing
behaviour under test.
Licence
Apache 2.0, see LICENSE.
One exception: qemu/py32f071.c is licensed GPL-2.0-or-later, as its header
states. It is built into QEMU and derives from QEMU's device models, which are
GPL-2.0, so it cannot be anything else. The tools, harness and documentation are
Apache 2.0.
Credits
Base firmware: armel/uv-k1-k5v3-firmware-custom. Register definitions from the vendor CMSIS headers.