Spend Your Effort on the Layer With No Reference Path and No Error Case

Mostafa Dhouib·7 min read

Spend Your Effort on the Layer With No Reference Path and No Error Case

The short answer. When people look at a layered product and ask where the risk is, they point at the layer that is hardest to build. That is usually the wrong layer, because difficulty attracts attention, reference implementations and tooling. The dangerous layer is the one with two properties: no worked reference path to follow, and no mechanism that fails loudly when it is wrong. In a camera converting to a standard host interface, the firmware and programmable-logic layer has a documented vendor reference, and the controller inserts stream framing in hardware. The register-to-descriptor handshake above it has neither, so a mistake there streams happily, passes every test written against the vendor's own tooling, and fails the first time a host nobody on the project wrote tries to enumerate the device.

A client worries about the layer they can see. On a camera project that means the firmware and the programmable logic, because that is where the visible engineering is and where the specialists are expensive.

They are often right that it is hard and wrong that it is risky, and the distinction is worth making precisely, because it decides where the budget goes.

Two properties that make a layer safe

A layer is relatively safe when it has either of these, and quite safe when it has both.

A reference path. Somebody has done this before and written down how. A vendor reference design, a known-good driver, a specification with worked examples. You are following a route rather than finding one, and the mistakes available to you are the ones somebody already documented.

A loud failure mode. When you get it wrong, something stops. A stream does not start, a device does not enumerate, a test fails. The feedback arrives immediately and is unambiguous.

On the camera stack, the lower layers have both. The silicon vendor publishes a reference path. The controller's transfer engine inserts the required stream framing automatically, which removes an entire class of error from the firmware's responsibility. And when the firmware is wrong, the stream does not run, which is about as loud as feedback gets.

So the layer everybody is worried about is the layer with a map and an alarm.

The layer with neither

One level up sits the descriptor handshake: the chain by which a host discovers what the device is and what it can do. A bootstrap register points to a further register region, which points to a manifest, which declares a descriptor document, which the host reads to construct its model of the device's capabilities.

This layer has no reference path for your device, because the descriptor is specific to your feature set. Nobody has written yours. And it has no loud failure mode, which is the part that matters.

Consider one concrete error: the manifest under-declares the size of the descriptor document. The host reads exactly the number of bytes the manifest said. It receives a truncated document. It cannot build a capability model from it.

What does not happen is an error. The camera is streaming. The transport is healthy. The device is enumerating at the bus level. Everything reports success, and the host simply has no idea what the device can do. From the device's side nothing is wrong at all.

Why in-house testing cannot find it

This is the part that makes it expensive, and it generalises well beyond cameras.

The team tests with the vendor's own tooling, which is the sensible thing to do and which is the problem. That tool was written alongside the hardware by people who knew how it behaves. It is tolerant in the places the hardware is unusual, because tolerating those was how it was made to work.

So the vendor tool reads the device successfully whether the descriptor is right or wrong. It has other ways of knowing. The test passes, and the test was never capable of distinguishing the two cases.

The first thing that distinguishes them is a host written by someone with no knowledge of your device, enumerating it from the standard alone. That is also the condition the product meets in the field, on day one, at a customer site.

The general rule

Find the layers with no reference path and no error case, and put the proof there.

The test is two questions per layer. If I get this wrong, does anything stop? And has anyone written down how to do this for a device like mine?

A layer that answers no to both is where the budget belongs, regardless of how difficult it is to build. Difficulty and risk are different axes and people conflate them constantly.

This is also an argument for a specific kind of acceptance test. The only honest test of an interoperability layer is a client nobody on the project wrote. Not a better in-house harness, because a harness written by the team encodes the team's assumptions and agrees with them. An independent implementation reading from the specification is the first thing that does not.

What the proof looks like

On work of this shape, the first paid piece is usually small and specific: take a representative slice of the feature set, perhaps five to eight registers covering the structural cases, and prove it end to end against an independent runtime.

Three checks carry most of the risk.

Size. Every declared length matches the actual length of the thing it describes.

Integrity. Any checksum or hash over the descriptor is computed over exactly the bytes being served.

Linkage. Every pointer in the chain resolves, in order, to the thing the next stage expects.

Those three are where the silent failures concentrate, and they are checkable mechanically once somebody decides to check them.

The honest limit

This describes where to put proof, not how to make the descriptor correct. Getting it right is still domain work requiring the standard and the device.

And the rule has a boundary. A layer with a reference path can still be risky if the reference assumes something your product does not do, which happens whenever a vendor reference is written for the common case and you are not it. The two questions are a heuristic for allocating attention, not a guarantee.

What is reliable is the asymmetry. A loud failure gets found on the bench by whoever caused it. A silent one gets found by a customer, weeks later, with no diagnostic trail, and costs an order of magnitude more to resolve.

FAQ

How do I find the riskiest layer in a layered product? Ask two questions of each layer. If this is wrong, does anything stop? And has anyone written down how to do this for a device like mine? A layer answering no to both is where the risk sits, regardless of how hard it is to build, because difficulty and risk are different axes.

Why does a device stream correctly but fail to enumerate on a standard host? Commonly because the descriptor chain is wrong in a way that does not affect streaming. If a manifest under-declares the size of the descriptor document, the host reads a truncated document and cannot build a capability model, while the device continues streaming and reports no error at all.

Why does the vendor's own tool fail to catch descriptor errors? Because it was written alongside the hardware by people who knew its quirks, so it is tolerant in exactly the places your device is unusual and has other ways of knowing what the device can do. It reads the device successfully whether the descriptor is correct or not, so the test never distinguishes the two.

What is the only honest test of an interoperability layer? A client nobody on the project wrote, enumerating the device from the published standard alone. An improved in-house harness does not help, because a harness written by the team encodes the team's assumptions and agrees with them. The independent implementation is the first thing that does not.

What should a first proof slice cover? A representative set of registers covering the structural cases, proven end to end against an independent runtime, with three specific checks: every declared length matches the actual length, every checksum covers exactly the bytes served, and every pointer resolves in order to what the next stage expects.

Is a layer with a vendor reference path automatically safe? No. A reference written for the common case can assume something your product does not do, and then following it carefully produces a confident wrong result. The two questions allocate attention rather than guarantee safety, and the asymmetry they exploit is that loud failures are found on the bench and silent ones are found by customers.