The Document That Everyone Depends on and Nobody Owns

Every embedded system has a boundary where hardware stops and software begins. That boundary is not physical — it is contractual. It lives in a document, or more often in a collection of documents, spreadsheets, and informal agreements that engineers have come to call the Hardware-Software Interface specification, or HSI.

The HSI defines what software can assume about the hardware it runs on. Memory maps, register layouts, bit-field definitions, interrupt vectors, timing constraints, communication protocols, power sequencing — all of it. If software needs to write to a control register to enable a peripheral, the HSI specifies which address, which bits, what the valid values are, and what happens if the write violates a timing window. If hardware asserts an interrupt, the HSI specifies the latency bounds, the polarity, and the clearing mechanism.

In principle, the HSI is the most important interface document in the program. In practice, it is one of the most reliably broken.

This article explains what an HSI specification is supposed to do, why it fails so consistently, and what it looks like when teams treat it as a live system artifact rather than a shared drive document.

What an HSI Specification Contains

A complete HSI covers several distinct layers of the hardware-software boundary. These are not always organized this way in practice, but this is the logical structure:

Memory map and address space. The physical and logical address ranges assigned to each peripheral, memory bank, and mapped register block. Includes base addresses, sizes, alignment constraints, and any aliasing behavior.

Register definitions. For each memory-mapped register: address offset, reset value, access type (read-only, write-only, read-write, write-to-clear), and a definition of every bit field. This is the most detailed and most frequently incorrect section of any HSI.

Interrupt specifications. Interrupt numbers or vectors, trigger conditions (level vs. edge, polarity), latency bounds from event to assertion, and the required software clearing sequence. Latency bounds are particularly critical in real-time systems and particularly often omitted.

Timing contracts. Setup and hold times for bus transactions, minimum pulse widths, clock domain crossing constraints that software must respect, and any sequencing requirements between signals or operations.

Communication protocols. For interfaces like SPI, I2C, CAN, PCIe, or proprietary links — the operating mode, supported speeds, framing formats, error handling behavior, and any hardware-enforced constraints on transaction ordering.

Power and reset behavior. Reset state of all registers, power domain boundaries, wake-up behavior, and any ordering requirements during power sequencing. This section is consistently underspecified until a board bring-up failure makes it obvious.

Errata. Known hardware behaviors that deviate from the specification. These belong in the HSI, not in a separate document engineers may or may not know to look for.

The Lifecycle of an HSI

The HSI is not a document you write once and archive. It has a lifecycle that spans the entire program, and most integration failures can be traced back to a lifecycle failure rather than a content error.

Creation. The HSI starts life during system architecture, when the partitioning between hardware and software is being decided. At this stage it is largely aspirational — it describes the interface the system architects intend to implement. This is the right time to write the HSI because decisions made here propagate directly into hardware design and software architecture.

Baselining. The HSI must be formally baselined before hardware design is locked and before software teams begin implementation against it. Baselining too early means the document does not reflect actual hardware decisions. Baselining too late means software has already been written against informal agreements that may not match what was built. Most programs get this timing wrong in the direction of too late.

Hardware revision tracking. Every time the hardware design changes in a way that affects the interface — a register address changes, a bit field is redefined, an interrupt polarity is corrected — the HSI must be updated and that change must propagate to all software teams working against it. This is where programs bleed the most. The hardware team updates a schematic. The firmware team finds out three weeks later during integration.

Software verification. The HSI defines what software is supposed to do, which means it defines what verification activities need to prove. Every timing contract and register behavior in the HSI should have a corresponding test or analysis. If it does not, the HSI is not being used as an engineering document — it is being used as a filing exercise.

Maintenance through integration and qualification. The HSI does not freeze at hardware tape-out. Hardware errata discovered during bring-up must be reflected in the HSI. Workarounds implemented in software because of hardware limitations must be documented. Programs that stop maintaining the HSI after silicon comes back end up with an artifact that describes what the hardware was supposed to do, not what it actually does.

Why the HSI Fails

The content of the HSI is rarely the primary failure mode. Engineers who write HSI documents generally know the interface. The failures are systemic.

Ownership ambiguity. Hardware teams feel the HSI belongs to software because software uses it. Software teams feel it belongs to hardware because hardware defines it. System architects often own it at the beginning and lose control of it as the program executes. When no one has clear authority to approve changes and enforce propagation, the document drifts.

Document-centric storage. An HSI stored as a PDF or Word document on a shared drive is not a living specification. It is a snapshot. When a hardware engineer updates a register definition in their design tool, there is no automatic connection to the HSI document. The update requires a manual edit, a manual review, and a manual communication to whoever is working against that document. Each of those manual steps is a failure opportunity.

Change propagation failures. This is the most expensive failure mode. A register address changes because of a routing decision. The hardware engineer updates the schematic. The HSI document is updated two weeks later, after someone notices a mismatch. The firmware team has already written a driver against the old address. The discrepancy is discovered at integration, six weeks before program review. Schedule impact: significant. Root cause: a change that was not propagated.

Lack of traceability to derived artifacts. An HSI entry defines the behavior of a peripheral register. A software requirement is derived from that entry, specifying how the driver must behave. A test case is derived from that requirement. When the register definition changes, the software requirement and test case need to change too. In a document-based system, that chain is invisible. Engineers do not know what they need to update because there is no recorded relationship between the HSI entry and the artifacts it affected.

Informal agreements that never make it in. Every program has conversations that should result in HSI updates and do not. A hardware engineer tells a firmware engineer in a hallway conversation that a particular bit field was changed in the latest rev. The firmware engineer updates their code. Neither of them updates the HSI. This is not negligence — it is the predictable behavior of engineers under schedule pressure who have no tool that makes updating the HSI easier than sending an email.

How Structured Interface Management Changes the Equation

The fundamental problem with document-based HSI management is that the HSI is being stored in a format that does not reflect its actual structure. An HSI is not a document — it is a graph of interface definitions, constraints, and dependencies. Storing it as a document discards all of that structure and forces engineers to reconstruct it manually every time something changes.

Structured interface management treats each HSI element — a register, a timing constraint, an interrupt definition — as a discrete, addressable object with explicit relationships to the hardware elements that define it and the software elements that depend on it.

Flow Engineering implements this model directly. In Flow Engineering, an HSI element such as a register definition is a node in the system model. That node carries its attributes — address, access type, bit fields, reset value — as structured data, not prose. The node has explicit links to the hardware design elements that specify it and to the software requirements that depend on it. When a hardware engineer changes the register definition, that change is visible immediately to the software requirements that reference it. Requirements that are now potentially inconsistent are flagged, not discovered six weeks later.

This is what live traceability means in practice: not a traceability matrix that someone exports at milestone review, but a continuously maintained graph of dependencies that makes change impact visible before it becomes integration damage.

Flow Engineering’s approach also resolves the ownership problem. The HSI in Flow Engineering is owned by the system architecture layer — not by hardware, not by software. Hardware engineers contribute their definitions through the model. Software engineers consume interface specifications from the model and derive their requirements from it. System architects can see when the interface is changing and govern the change process. The document is not the artifact — the model is.

A consequence of this architecture is that the HSI can be queried rather than read. Instead of asking an engineer to find every piece of software affected by a change to a SPI clock rate constraint, a system architect can query the model for all software requirements that trace to that constraint and see the impact immediately.

Practical Starting Points

Teams that want to move toward structured HSI management do not need to rebuild their entire process at once. A few concrete starting points:

Define ownership explicitly. Assign a system architect as the HSI owner with authority to approve all changes. Hardware and software engineers are contributors and consumers, not co-owners. This is an organizational decision, not a tool decision, and it can be made before any tool change.

Enumerate the interface elements as discrete objects. Even in a document-based system, replacing prose register descriptions with a structured table or database — even a spreadsheet — is a meaningful improvement. Each row is an addressable object. Changes to rows can be tracked. This is not a complete solution, but it is better than unstructured prose.

Establish a change control process before integration. The most common pattern is to establish change control after the first integration crisis. Establish it during system architecture instead. Define what level of change requires formal HSI update, who approves it, and what notification is required.

Trace from HSI entries to derived requirements explicitly. For every software requirement that depends on an HSI element, record that dependency. This can be done in a requirements management tool, in a model, or even in a tagged spreadsheet. What matters is that the relationship is recorded somewhere that is checked when the HSI element changes.

Treat errata as first-class HSI content. Workarounds and known deviations belong in the HSI alongside the nominal specification. If they are maintained separately, they will drift separately. Engineers who join the program after bring-up will not know what is specified and what is a workaround unless both are in the same place.

The Honest Summary

The HSI specification is not a bureaucratic artifact. It is the definition of a contract between two engineering domains that must be true simultaneously in one integrated system. When it fails, integration fails — in a lab, in a qualification test, or in a fielded product.

The failures are not usually caused by engineers who do not know their interface. They are caused by organizations that store a graph of dependencies in a document, manage changes through email and hope, and discover discrepancies at the worst possible time.

Structured interface management — treating HSI elements as live model objects with explicit, queryable traceability — is not a luxury for large programs. It is the minimum viable process for any program where hardware and software are developed in parallel and the interface is expected to change. That description covers almost every embedded systems program in development today.