7. Reading a datasheet like a type signature

A datasheet is a contract with two very different kinds of number in it. Which one you are reading changes what a violation means.

Everything so far has been answerable from the netlist. Whether a wire connects, what a part is for, which pin drives. This chapter crosses a line: the questions here cannot be answered from the design at all, because the answers live in a document the design does not contain.

Prerequisites: Chapter 1, and chapter 3 for a first look at a rating.

Levels on this page: EE5. It links to what that level means.

A part is a contract (EE5)

If you write software, you already have the right model. A datasheet is a type signature for a part: it states what the part promises, and what it requires of you in return. Feed it what it requires and the promises hold. Go outside, and the vendor makes no claim at all about what happens.

Where the analogy pays off is in what a violation means. A type error is a compile-time refusal. A datasheet violation is nothing so tidy: the board gets built, and the part behaves in some way the vendor never characterised, which may be “fine on this unit today”.

Two numbers that look alike (EE5)

Here is the seeded data for the two regulators on the tutorial board:

$ agni query examples/tutorial-project/designs/gateway/gateway.edn --params examples/tutorial-project/params 'component.mpn(?r, ?m), param(?m, "VIN", ?max) => ?r, ?m, ?max'
r   m              max  provenance
U1  ACME-BUCK-3V3  32   datasheet "ACME-BUCK-3V3 Datasheet Rev A" page 4, "Recommended Operating Conditions" (hand, confidence 1) ; designs/gateway/gateway.edn
U1  ACME-BUCK-3V3  36   datasheet "ACME-BUCK-3V3 Datasheet Rev A" page 3, "Absolute Maximum Ratings" (hand, confidence 1) ; designs/gateway/gateway.edn
U2  ACME-LDO-1V8   3    datasheet "ACME-LDO-1V8 (placeholder, not transcribed)" page 0, "" (mock, confidence 0.3) ; designs/gateway/gateway.edn

3 result(s)

Look at U1. It has two VIN numbers, and they come from different pages of the same document.

36 V is the absolute maximum, from page 3. That is a damage threshold. It says nothing about the part working; it says that beyond this you may destroy it, and that the vendor’s other promises were never evaluated up there. It is not a design target and operating at it is not “using the full range”.

32 V is the recommended operating maximum, from page 4. That is the actual contract. Stay inside it and every other number in the datasheet applies: the efficiency curve, the output accuracy, the thermal figures.

The gap between them is deliberate margin, and treating the bigger number as the usable one is the classic way to build something that works on the bench and fails in the field. Confusing the two is probably the single most common datasheet mistake, and it is why the parameter layer records limit_kind on every row rather than storing “the VIN limit”.

Three voltage bands: recommended operating below 15 V, an unpromised band from 15 to 20 V, and damage above the 20 V absolute maximum 20 V 15 V 0 V Damage the part may not survive this Works, but nothing is promised no specification was evaluated here Recommended operating where the datasheet's other numbers hold absolute maximum recommended max a supply pin

There is a third thing on each row worth noticing: conditions. The seeded rows here carry TA = 25C. A number is only true under the conditions it was measured at, and a part characterised at 25°C tells you comparatively little about the same part at 85°C in a sealed enclosure.

A third number, which promises nothing (EE5)

The two numbers above are both promises. An absolute maximum promises damage beyond it; a recommended operating range promises the rest of the document holds inside it. A datasheet prints a third kind that promises nothing at all, and it is the one most likely to be mistaken for a fact.

Both regulators on this board state an output voltage:

$ agni query examples/tutorial-project/designs/gateway/gateway.edn --params examples/tutorial-project/params 'component.mpn(?r, ?m), param.typ(?m, "VOUT", ?typ) => ?r, ?m, ?typ'
r   m              typ  provenance
U1  ACME-BUCK-3V3  3.3  datasheet "ACME-BUCK-3V3 Datasheet Rev A" page 4, "Recommended Operating Conditions" (hand, confidence 1) ; designs/gateway/gateway.edn
U2  ACME-LDO-1V8   1.8  datasheet "ACME-LDO-1V8 (placeholder, not transcribed)" page 0, "" (mock, confidence 0.3) ; designs/gateway/gateway.edn

2 result(s)

U1 outputs 3.3 V. That is the number the schematic calls +3V3, the number on the rail label, the number you would put in a power budget. It is a typical value, which means it is roughly what a part from the middle of the production run does at room temperature with a modest load. The part on your bench is a sample from that distribution, and it is within spec anywhere the datasheet’s tolerance allows, which this row does not even state.

So a typical is useful for the things averages are useful for. Estimating what the board draws, sizing a heatsink, sanity-checking a rail label. It is the wrong number to design a threshold against, because the part that trips your comparator will be the one at the edge of the distribution, and it was in spec the whole time.

Ask for it the way you would ask for a limit and you can see the layer refusing to answer:

$ agni query examples/tutorial-project/designs/gateway/gateway.edn --params examples/tutorial-project/params 'component.mpn(?r, ?m), param(?m, "VOUT", ?max) => ?r, ?m, ?max'
r   m              max  provenance
U1  ACME-BUCK-3V3       datasheet "ACME-BUCK-3V3 Datasheet Rev A" page 4, "Recommended Operating Conditions" (hand, confidence 1) ; designs/gateway/gateway.edn
U2  ACME-LDO-1V8        datasheet "ACME-LDO-1V8 (placeholder, not transcribed)" page 0, "" (mock, confidence 0.3) ; designs/gateway/gateway.edn

2 result(s)

Two rows, and no number in either. param reports ceilings, a typical is not one, and the row stays with its number missing rather than quietly reporting zero. That absence is deliberate and it is load-bearing: a threshold written against a missing number cannot silently pass, because ordering refuses to compare an absent value against a present one.

Note the second row’s citation while you are here. U2’s 1.8 V comes from a placeholder at confidence 0.3, so it is a typical value that nobody has even transcribed from a real document. Two different reasons to distrust one number, which the next section is about.

The comparison (EE5)

With ratings available, the rule can do what it could not before:

$ agni check --verdicts --rule supply-exceeds-abs-max examples/tutorial-project/designs/gateway/gateway.edn
supply-exceeds-abs-max  1 fail, 1 pass
    fail  U2.1  3.3 V exceeds the absolute maximum of 3 V
    pass  U1.1  12 V is within the absolute maximum of 36 V

2 verdicts across 1 rule(s), 1 pass, 1 fail

U1 sits on 12 V against a 36 V maximum and passes. U2 sits on the 3.3 V rail against a 3 V maximum and fails.

Both verdicts state both numbers, which is the EE5 habit in miniature. “Exceeds its rating” is unactionable. “3.3 V exceeds the absolute maximum of 3 V” can be checked against the document by anyone.

Where did the number come from? (EE5)

Now the part that separates this layer from a spreadsheet of limits.

Every parameter carries provenance: which document, which page, which table, how it got there, and how much anyone should trust it. The query above printed it. U1’s rows say page 3, “Absolute Maximum Ratings” (hand, confidence 1). U2’s say page 0, "" (mock, confidence 0.3).

That difference is not cosmetic. U2’s rating is a placeholder somebody typed to stand in for a datasheet nobody has transcribed yet. It might be right. Nothing has checked it.

So the same finding reads differently depending on what is asking:

$ agni review examples/tutorial-project/designs/gateway --checklist examples/tutorial-project/review.yaml
| P4 | no part is operated above its absolute-maximum supply voltage | provisional | supply-exceeds-abs-max: U2 (power-input pin 1 on rail "PMIC_CORE_3V3": nominal 3.3V exceeds absolute-maximum VIN 3V — datasheet "ACME-LDO-1V8 (placeholder, not transcribed)" page 0, "" (mock, confidence 0.3)) |

agni check reported that as an error. A review reports it as provisional, because the evidence sits below the trust floor. The engine is declining to call a defect on a number nobody has verified, while still refusing to hide it.

This matters more than it first appears. A parameter corpus starts empty and fills up over months, mostly with rows somebody typed in a hurry. A tool that treated every seeded number as gospel would produce confident accusations from placeholder data, and the first time that happens to an engineer they stop believing the tool. A tool that ignored unverified rows would go quiet instead. Provisional is the third answer, and it is the honest one.

What this layer does not cover (EE5)

Count the verdicts above: two, on a board with nineteen parts.

That is not a bug and the rule says so where it happens: a part with no seeded datasheet is not a subject, because there is no stated rating to compare anything against. Only the two regulators have parameter files, so only their supply pins were judged. Every other part on the board went unexamined by this rule, and no output claims otherwise.

Coverage at EE5 is therefore bounded by your parameter corpus rather than by your design, which is a different shape from every earlier chapter. A connectivity rule sees the whole netlist for free. A datasheet rule sees exactly as much as somebody has typed in, and the work of extending it is transcription rather than cleverness.

Worth remembering chapter 3’s closing point here too, because it is the limit beyond this one. A number can be correctly transcribed, correctly compared, and still not be the number in your circuit: a ceramic capacitor’s marked value falls with applied voltage, so a part that satisfies every check on paper can be short of capacitance on the bench.

What you can now answer

  • Why a datasheet has two maximum voltages and what each one licenses. (EE5)
  • Why a rating is meaningless without its conditions. (EE5)
  • Why a typical value is not a promise, and what it is still good for. (EE5)
  • Why the same defect reads as an error to one command and as provisional to another. (EE5)
  • Why a datasheet rule judged two subjects on a nineteen-part board, and why that is honest. (EE5)

The rules this page explains

Rule Severity What it catches
supply-exceeds-abs-max error a supply pin above the part’s absolute-maximum input
cap-voltage error a capacitor’s rated voltage below its rail, with derating
fet-vdss-below-switched-rail error a FET on a rail at or above its drain-source breakdown voltage
regulator-output-exceeds-abs-max error a regulator driving a rail above what a part it feeds can survive
load-switch-trip-above-fet-rating error a load switch that trips above its pass FET’s continuous rating

Next: the power tree, where the question stops being about one part and becomes about how the whole board is fed.