Study guides · Advanced

MMIO to character output: follow a virtual UART access

Trace a register write through trapping, validation, emulation, and guest resumption in a small UART model.

Ask Logeia about this articleTry the three questionsReview your answers

Updated

On this page
  1. An address can represent a device operation
  2. Make device placement an explicit guest contract
  3. Route only validated trapped operations
  4. Register size and device transfer size differ
  5. Do not execute a completed emulation twice
  6. Model steps are not UART timing measurements
  7. Exercise: validate one character output
  8. Ask Logeia about this articleCheck your understanding

An address can represent a device operation

MMIO assigns device registers to parts of an address space. A read or write can mean sending a character or obtaining status rather than storing ordinary RAM data. This lesson uses a small model inspired by PL011, limited to selected character output behavior. It does not claim complete register, FIFO, interrupt, or timing compatibility.

Compare sending the same value to ordinary RAM and to the selected UART location. RAM changes stored contents; the UART operation changes an output sequence. An assignment succeeding is not evidence of a complete device implementation. A device model needs a meaning for each supported register, its associated side effects, and an explicit response to unsupported operations. Keeping those responsibilities separate makes later FIFO and interrupt extensions easier to understand and test.

Make device placement an explicit guest contract

A guest needs a device range and interface description. Device Tree is one mechanism for providing such information. The example fixes the UART IPA base at 0x09000000 and the selected data-register offset at zero, but these are stated example assumptions. A real system should use its platform description rather than assuming that every Arm machine has the same layout.

Subtracting the example base gives offset zero for 0x09000000 and offset four for 0x09000004. This first model supports only the former, so the latter must leave output unchanged. A platform description also creates expectations: advertising registers or functionality that the implementation lacks can break a guest even if the description parses correctly. Restricting the lesson is acceptable; silently presenting unsupported functionality as available is a different design error.

Route only validated trapped operations

When an access reaches the selected UART range, the model routes it to EL2 rather than directly mapped RAM. Management code validates the range, direction, width, and operand information. Architectural syndrome fields are not valid for every instruction form. An implementation supporting a restricted form must reject unsupported decoding rather than guess what the guest intended.

The demonstration constructs decoded operation information from its controlled inputs; it does not read a real ESR_EL2. A hardware implementation must check validity conditions, including the relevant syndrome fields, before using them. Supporting forms that lack sufficient syndrome information can require additional instruction decoding. Do not invent missing operands merely because the display has a field for them. Architectural-looking register labels do not establish that their values were measured on the host CPU.

Register size and device transfer size differ

A 64-bit general register does not imply a 64-bit character transfer. Validate the device’s supported access width and relevant bits. In the model, a supported data-register write of 0x41 emits the low-byte character A. This is not a Unicode string API, and supported widths for actual hardware come from its specification, not from the width of the CPU operand.

The first player accepts a 32-bit store to its selected data location. Changing the variant to a 64-bit store stops as unsupported. That is a negative test of this model’s acceptance rules, not a measurement of how every real PL011 handles that width. Compare output counts across accepted and rejected cases. This establishes that width validation controls side effects, rather than merely changing explanatory text while allowing the same character output.

python
def teaching_uart_write(address, width, value):
    if address != 0x09000000 or width != 32:
        raise ValueError('unsupported register or width')
    return chr(value & 0xff)

assert teaching_uart_write(0x09000000, 32, 0x41) == 'A'
for address, width in [(0x09000004, 32), (0x09000000, 64)]:
    try:
        teaching_uart_write(address, width, 0x41)
    except ValueError:
        pass
    else:
        raise AssertionError('unsupported access was accepted')
print('A; two unsupported accesses rejected')

Do not execute a completed emulation twice

After emitting A, record the guest operation as completed and resume according to that instruction/exception contract. Repeating the same emulation could emit AA. This differs from repairing a RAM mapping, where the store still needs execution. The trace couples output-buffer changes to the return-position decision so duplicate side effects are visible.

The successful example starts at PC 0x4000 and resumes at 0x4004 after one selected A64 instruction is emulated. Unsupported width and register variants keep the output count at zero and do not report that successful continuation. How a complete hypervisor reports that rejected operation to a guest is a later policy. This first view must still distinguish a supported completed instruction from an unresolved or rejected one rather than silently treating both paths as ordinary execution.

Model steps are not UART timing measurements

The interval between clicks is not a measured UART baud rate. The view shows logical ordering: guest operation, trap, validation, virtual device update, and resumption. FIFO capacity, input, and interrupt controls require additional state and contracts. Add those features explicitly rather than suggesting that an output animation already implements them.

In a real implementation, use distinct markers to separate output emitted directly by management logging from output produced through the guest MMIO path. Seeing a management message alone does not demonstrate that a guest store reached the virtual device. Correlating the guest marker, accessed address, and handler invocation count provides stronger evidence that the intended path ran. Keep that evidence separate from the concept model’s locally generated trace and from any recording produced under another configuration.

Exercise: validate one character output

For a supported write of 0x42 to IPA 0x09000000, validate the registered range, data-register offset, width, direction, and valid operand information; then emit B once and resume as completed. Changing the IPA to an unregistered 0x08000000 must not produce UART output. A form lacking supported decoding information must be reported as unsupported rather than silently emulated.

Check the answer by explaining the conditions validated before B was emitted and the state left unchanged in rejected cases. Compare one normal write, one unsupported width, and one unsupported register while keeping the character fixed. These cases expose accidental over-acceptance more effectively than three successful characters. When input, FIFOs, or interrupts are later added, rerun the same cases to verify that the original output contract and refusal behavior have not changed unexpectedly.

Try the interactive model

Guest output and MMIO traps

Loading demo checkpoint…

Reading and practice are recorded separately in this browser, for each language.

Choose a learning path