{
  "schemaVersion": 1,
  "id": "atlas-lesson-firmware-device-contract",
  "title": "Firmware handoff and device readiness",
  "category": "learning",
  "format": "Atlas lesson",
  "description": "Separate device compatibility, driver discovery, resource ownership and queue readiness before any operand is consumed.",
  "canonicalUrl": "https://semiaifoundry.com/learn/atlas/firmware-device-contract/",
  "publishedDate": null,
  "revisionDate": "2026-10-07",
  "author": null,
  "topic": "Executable software",
  "series": null,
  "license": null,
  "rightsUrl": "https://semiaifoundry.com/ai-atlas/licenses.html",
  "version": "1.3.0",
  "status": "Published educational lesson",
  "evidenceScope": "Primary sources establish the cited runtime mechanisms. Numerical values, address ranges, ABI strings, event schedule and reset/retry epochs are authored teaching contracts. No real device, firmware image, operating-system driver, page table, cache protocol or security verification is executed.",
  "contentCoverage": "published-lesson",
  "artifactUrl": "https://semiaifoundry.com/ai-atlas/lesson-data/firmware-device-contract-af99231c7ca5e469.json",
  "interactiveUrl": "https://semiaifoundry.com/ai-atlas/#firmware-device-contract",
  "related": [],
  "supersedes": [],
  "supersededBy": [],
  "contentHash": "1aecc713a863e4b859b3f2a0dec96f19a3b1e9cb2d477f013f75419f9c1d3c81",
  "contentLength": 6332,
  "jsonUrl": "https://semiaifoundry.com/agents/publications/atlas-lesson-firmware-device-contract.json",
  "markdownUrl": "https://semiaifoundry.com/agents/publications/atlas-lesson-firmware-device-contract.md",
  "sections": [
    {
      "id": "section-1",
      "title": "Firmware handoff and device readiness",
      "start": 36,
      "end": 515
    },
    {
      "id": "section-2",
      "title": "The mechanism",
      "start": 515,
      "end": 2118
    },
    {
      "id": "section-3",
      "title": "Science and assumptions",
      "start": 2118,
      "end": 2146
    },
    {
      "id": "section-4",
      "title": "The declared ABI gate",
      "start": 2146,
      "end": 2734
    },
    {
      "id": "section-5",
      "title": "Engineering example",
      "start": 2734,
      "end": 3207
    },
    {
      "id": "section-6",
      "title": "Distinctions and tradeoffs",
      "start": 3207,
      "end": 3742
    },
    {
      "id": "section-7",
      "title": "Specifications and interfaces",
      "start": 3742,
      "end": 4122
    },
    {
      "id": "section-8",
      "title": "Interfaces",
      "start": 4122,
      "end": 4367
    },
    {
      "id": "section-9",
      "title": "Check your understanding",
      "start": 4367,
      "end": 4396
    },
    {
      "id": "section-10",
      "title": "An ABI mismatch leaves host buffers populated. Has the device computed their matrix product?",
      "start": 4396,
      "end": 4783
    },
    {
      "id": "section-11",
      "title": "Evidence and scope",
      "start": 4783,
      "end": 5301
    },
    {
      "id": "section-12",
      "title": "Sources",
      "start": 5301,
      "end": 5729
    },
    {
      "id": "section-13",
      "title": "Continue exploring",
      "start": 5729,
      "end": 5752
    },
    {
      "id": "section-14",
      "title": "Foundations",
      "start": 5752,
      "end": 5976
    },
    {
      "id": "section-15",
      "title": "Related lessons",
      "start": 5976,
      "end": 6332
    }
  ],
  "citations": [
    {
      "title": "Explore in Atlas",
      "url": "https://semiaifoundry.com/ai-atlas/#firmware-device-contract"
    },
    {
      "title": "Linux 6.16 — How To Write Linux PCI Drivers",
      "url": "https://docs.kernel.org/6.16/PCI/pci.html"
    },
    {
      "title": "OASIS — Virtual I/O Device (VIRTIO) Version 1.3",
      "url": "https://docs.oasis-open.org/virtio/virtio/v1.3/virtio-v1.3.html"
    },
    {
      "title": "Published lesson data",
      "url": "https://semiaifoundry.com/ai-atlas/lesson-data/firmware-device-contract-af99231c7ca5e469.json"
    },
    {
      "title": "Atlas releases and licensing",
      "url": "https://semiaifoundry.com/ai-atlas/licenses.html"
    },
    {
      "title": "Runtime, driver and device dispatch",
      "url": "https://semiaifoundry.com/learn/atlas/runtime-device-dispatch/"
    },
    {
      "title": "Baseboard management controller",
      "url": "https://semiaifoundry.com/learn/atlas/management-controller/"
    },
    {
      "title": "Process, physical and device address spaces",
      "url": "https://semiaifoundry.com/learn/atlas/process-dma-address-spaces/"
    },
    {
      "title": "Commissioning a usable AI cluster",
      "url": "https://semiaifoundry.com/learn/atlas/cluster-commissioning-gates/"
    },
    {
      "title": "Tapeout, bring-up and productization",
      "url": "https://semiaifoundry.com/learn/atlas/chip-tapeout-productization/"
    }
  ],
  "recordHash": "013f638e7a7152ea1f60b10f742a0cd3f610f638b02f7df7788d055f4bfffd7f",
  "contentFormat": "text/markdown",
  "content": "Executable software · Atlas v1.3.0\n\n# Firmware handoff and device readiness\n\nSeparate device compatibility, driver discovery, resource ownership and queue readiness before any operand is consumed.\n\n[Explore in Atlas](https://semiaifoundry.com/ai-atlas/#firmware-device-contract)One process and device job; logical states and byte addresses, no timing or physical geometry\n\nLearning objectiveDistinguish the compatibility, discovery, resource and queue gates and identify the first gate that prevents a device job.\n\n## The mechanism\n\nA powered accelerator is not yet a usable participant in a computation. Its interface must be recognized, its required resources must be available, and a driver must complete the device-specific readiness contract. Firmware and boot software can establish initial device state, but a compatible interface string does not prove who produced an image or whether it is trustworthy. This lesson deliberately begins with an advertised teaching ABI and follows how that claim gates later actions. The process can already own and populate host buffers while the device remains unavailable. Rejected compatibility leaves those values intact and produces no DMA or numerical output. The distinction matters during bring-up: silicon, an installed driver, a discovered function and a running command are different milestones. The execution trace makes each gate inspectable while leaving firmware loading, secure boot, attestation and physical reset release outside its scope.\n\n1.  The host process creates identified input and output buffers before it attempts a device job.\n2.  The device handoff advertises matrix-int32-v1 or an incompatible version; the model does not execute firmware code.\n3.  A recognized teaching device identity binds to a driver, and the register resource is claimed.\n4.  The assumed DMA addressing capability and queue setup are accepted before publication.\n5.  An incompatible ABI stops commissioning before any submission, device read or multiply-accumulate.\n6.  A later acknowledged device reset clears readiness and requires the contract to be established again.\n\n## Science and assumptions\n\n### The declared ABI gate\n\n$$\nG_{\\mathrm{ABI}}=\\mathbf{1}[a_{\\mathrm{device}}=a_{\\mathrm{driver}}]\n$$\n\nABI gate equals one only when the advertised and required interface identifiers match.\n\nSymbols and units\n\nGABI\n\nCompatibility gate\n\nBoolean\n\nadevice\n\nAdvertised ABI identifier\n\nstring\n\nadriver\n\nRequired ABI identifier\n\nstring\n\nThe model accepts one exact operation-interface identifier. Resource and queue gates remain separate after this comparison.\n\nAssumptions A declared symbolic interface contract, not image authentication, feature probing or proof of correct device behavior.\n\n## Engineering example\n\nKeep A=\\[\\[1,2\\],\\[3,4\\]\\] and B=\\[\\[5,6\\],\\[7,8\\]\\]. With a compatible handoff, the later job can publish \\[\\[19,22\\],\\[43,50\\]\\]. Select incompatible ABI: the trace still shows the process input values, but submitted attempts, DMA read bytes and executed MACs are all zero. It publishes no C. Restoring compatibility permits the remaining gates to run; it does not by itself establish memory visibility, correct mappings or a correct completion.\n\n## Distinctions and tradeoffs\n\nMatching a device interface identifies a supported contract; it does not verify a firmware image or establish end-to-end correctness.\n\nAdding interface versions can preserve compatibility only when negotiation and failure behavior are explicit. The current model chooses an exact single-version gate instead of emulating feature negotiation.\n\nAccelerator bring-up joins physical hardware to supported execution. A model framework depends on this lower interface being usable before tensor work can run.\n\n## Specifications and interfaces\n\nTeaching ABI\n\nmatrix-int32-v1\n\nString equality is a compatibility test, not cryptographic verification.\n\nScope of discovery\n\nOne declared device/driver match\n\nNo actual PCI configuration transactions or operating-system enumeration.\n\nReadiness outcome\n\nQueue ready or commissioning blocked\n\nInstalled hardware is not counted as a completed job.\n\n### Interfaces\n\nDeclared runtime inputs Input\n\nStable matrix job, buffer identities and the stated device/visibility contract\n\nInspectable accepted or rejected result Output\n\nEvent trace, actual buffer values and bounded completion/work ledger\n\n## Check your understanding\n\n### An ABI mismatch leaves host buffers populated. Has the device computed their matrix product?\n\n1.  Yes, because the driver is installed\n2.  No: no job was submitted or operands consumed\n3.  Yes, because populated memory implies DMA completion\n\nAnswer and reasoning\n\nNo: no job was submitted or operands consumed\n\nHost allocation and initialization do not execute the device command.\n\n## Evidence and scope\n\nPrimary sources establish the cited runtime mechanisms. Numerical values, address ranges, ABI strings, event schedule and reset/retry epochs are authored teaching contracts. No real device, firmware image, operating-system driver, page table, cache protocol or security verification is executed.\n\nThe commissioning-execution-1 studio executes this bounded 2×2 matrix, buffer and completion contract. The surrounding atlas scene is conceptual; it is not a firmware emulator or system simulator.\n\n## Sources\n\n-   [Linux 6.16 — How To Write Linux PCI Drivers](https://docs.kernel.org/6.16/PCI/pci.html)\n-   [OASIS — Virtual I/O Device (VIRTIO) Version 1.3](https://docs.oasis-open.org/virtio/virtio/v1.3/virtio-v1.3.html)\n\n[Published lesson data](https://semiaifoundry.com/ai-atlas/lesson-data/firmware-device-contract-af99231c7ca5e469.json) · [Atlas releases and licensing](https://semiaifoundry.com/ai-atlas/licenses.html)\n\n## Continue exploring\n\n### Foundations\n\n-   [Runtime, driver and device dispatch](https://semiaifoundry.com/learn/atlas/runtime-device-dispatch/)\n-   [Baseboard management controller](https://semiaifoundry.com/learn/atlas/management-controller/)\n\n### Related lessons\n\n-   [Process, physical and device address spaces](https://semiaifoundry.com/learn/atlas/process-dma-address-spaces/)\n-   [Commissioning a usable AI cluster](https://semiaifoundry.com/learn/atlas/cluster-commissioning-gates/)\n-   [Tapeout, bring-up and productization](https://semiaifoundry.com/learn/atlas/chip-tapeout-productization/)"
}