Design Decisions

Informative

The rationale behind the memory driver contract. This helps implementers get the behavior right; it is not itself a requirement. Each entry points to the requirement it explains.

Why an asynchronous job model with no queue?

Governs CHI-MEM-MUST-02, CHI-MEM-MUST-04.

Flash operations (erase in particular) take a long time relative to the CPU, so blocking calls would stall the system. Running each operation as an asynchronous job advanced by Mem_PollFunction lets the caller do other work meanwhile. A queue is deliberately omitted: it adds RAM and complexity that a thin driver on a small MCU should not carry — sequencing is the upper layer’s job, so the driver accepts one job at a time and rejects the rest.

Implication for implementers: keep per-instance state to a single active job; reject new requests while one is pending.

Why no alignment, buffering, or result verification?

Governs CHI-MEM-MUST-15, CHI-MEM-MUST-16.

Aligning and buffering sub-page writes, and reading back to verify, would each add code, RAM, and time. The upper layer already knows the device geometry and can align its requests, and can verify where it needs to. Pushing these out of the driver keeps it minimal and predictable.

Implication for implementers: validate alignment as a development error rather than silently fixing it; do not read back after a write or erase.

Why offer a binary image and dynamic activation?

Relates to CHI-MEM-MUST-20, CHI-MEM-MUST-23.

Some systems must load or update a memory driver at runtime (for example to program flash from a relocatable routine running in RAM). A self-contained, position-independent binary image with a header and a service function-pointer table lets the integrator activate the driver dynamically and call it indirectly, while the delimiter (the ones’ complement of the unique id) gives a cheap consistency check.

Implication for implementers: if you ship a binary image, make it fully self-contained (no external calls) and populate the function-pointer table for every service.

Why hardware-based suspend/resume and a single hardware-service dispatcher?

Relates to CHI-MEM-MUST-11, CHI-MEM-MUST-12.

Suspend/resume and device-special operations are inherently hardware-specific. Rather than mandate a software emulation or grow the API with per-device functions, the driver exposes suspend/resume as hardware-based services (returning E_MEM_SERVICE_NOT_AVAIL where unsupported) and funnels everything else through one Mem_HwSpecificService dispatcher.

Implication for implementers: map suspend/resume to the hardware where it exists; expose other device features via hwServiceId rather than new APIs.