---
# The chip's hardware in one file: package, pins, the driver hook of each pin, the blocks inside and the reference
# circuits. `kokeb-docs figures` draws the pinout, the package outline, the block diagram and the circuits from it,
# `kokeb-docs gen` writes the chip card of the README and the tables of docs/hardware.md,
# `kokeb-docs hardware --check` validates it and `kokeb-docs hardware --kicad-netlist OUT --circuit ID` exports a
# circuit for a schematic or PCB tool. Schema: docs/chip-diagrams.md in kokeb-labs/ci-tools.
#
# Every fact cites the ADS9324 data sheet (SBASB22, December 2025) listed in docs/datasheets.yml, by section and
# printed page. Anything the data sheet does not state carries `unverified`.
schema: 1
chip: ADS9324

refs:
  pinout: {doc: ds, section: "4 Pin Configuration and Functions, Figure 4-1", page: 3}
  pins: {doc: ds, section: "4 Pin Configuration and Functions, Pin Functions", page: 4}
  analog: {doc: ds, section: "4 Pin Configuration and Functions, Pin Functions", page: 3}
  roc: {doc: ds, section: "5.3 Recommended Operating Conditions", page: 6}
  blocks: {doc: ds, section: "7.2 Functional Block Diagram", page: 24}
  reference: {doc: ds, section: "7.3.6 Reference, Table 7-3", page: 28}
  app: {doc: ds, section: "9.2 Typical Application, Figure 9-2", page: 107}
  supply: {doc: ds, section: "9.3 Power Supply Recommendations, Figure 9-4", page: 109}
  outline: {doc: ds, section: "12.1 Mechanical Data, RSK0064B", page: 112}
  order: {doc: ds, section: "12 Mechanical, Packaging, and Orderable Information", page: 115}

# The ADS9324 in the 64-pin VQFN (RSK). The exposed thermal pad connects to GND.
package:
  type: VQFN-64
  pins: 64
  exposed_pad: true
  # As Figure 4-1 draws it (top view): pins 1 to 16 down the left side, 17 to 32 along the bottom, 33 to 48 up the
  # right side and 49 to 64 along the top.
  sides:
    left: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]
    bottom: [17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32]
    right: [33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48]
    top: [49, 50, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60, 61, 62, 63, 64]
  ref: pinout
  outline: {length_mm: 8.0, width_mm: 8.0, height_mm: 1.0, pitch_mm: 0.4, ref: outline}
  variants:
    - {id: rsk0064e, type: VQFN-64, pins: 64, size: "8.0 x 8.0 x 1.0 mm", ordering: "ADS9324RSKR",
       note: "second drawing, RSK0064E, with a 5.56 mm pad (RSK0064B: 5.31 mm)", ref: outline}

# The supply range of each rail (the README's chip card shows it).
supply:
  - {name: AVDD_5V, min_v: 4.75, max_v: 5.25, ref: roc}
  - {name: AVDD_1V8, min_v: 1.7, max_v: 1.9, ref: roc}
  - {name: IOVDD, min_v: 1.7, max_v: 3.6, ref: roc}

# The port hooks a pin can map to (the names the driver's port headers declare).
hooks:
  - {id: transfer, call: "Transfer()", kind: spi, source: inc/ads9324_spi_interface.hpp, symbol: Transfer}
  - {id: lanes, call: "CaptureLanes()", kind: other, source: inc/ads9324.hpp, symbol: CaptureLanes}
  - {id: reset, call: "GpioSet(CtrlPin::Reset)", kind: gpio-out, source: inc/ads9324_spi_interface.hpp, symbol: Reset}
  - {id: convst, call: "GpioSet(CtrlPin::Convst)", kind: gpio-out, source: inc/ads9324_spi_interface.hpp,
     symbol: Convst}
  - {id: drdy, call: "GpioGet(CtrlPin::DrdyAlarm)", kind: gpio-in, source: inc/ads9324_spi_interface.hpp,
     symbol: DrdyAlarm}

pins:
  - {number: 1, name: AIN5P, type: analog, domain: AVDD_5V,
     function: "Analog input channel 5, positive input", ref: analog}
  - {number: 2, name: AIN5M, type: analog, domain: AVDD_5V,
     function: "Analog input channel 5, negative input", ref: analog}
  - {number: 3, name: AIN6P, type: analog, domain: AVDD_5V,
     function: "Analog input channel 6, positive input", ref: analog}
  - {number: 4, name: AIN6M, type: analog, domain: AVDD_5V,
     function: "Analog input channel 6, negative input", ref: analog}
  - {number: 5, name: AIN7P, type: analog, domain: AVDD_5V,
     function: "Analog input channel 7, positive input", ref: analog}
  - {number: 6, name: AIN7M, type: analog, domain: AVDD_5V,
     function: "Analog input channel 7, negative input", ref: analog}
  - {number: 7, name: AIN8P, type: analog, domain: AVDD_5V,
     function: "Analog input channel 8, positive input", ref: analog}
  - {number: 8, name: AIN8M, type: analog, domain: AVDD_5V,
     function: "Analog input channel 8, negative input", ref: analog}
  - {number: 9, name: AIN9P, type: analog, domain: AVDD_5V,
     function: "Analog input channel 9, positive input", ref: analog}
  - {number: 10, name: AIN9M, type: analog, domain: AVDD_5V,
     function: "Analog input channel 9, negative input", ref: analog}
  - {number: 11, name: AIN10P, type: analog, domain: AVDD_5V,
     function: "Analog input channel 10, positive input", ref: analog}
  - {number: 12, name: AIN10M, type: analog, domain: AVDD_5V,
     function: "Analog input channel 10, negative input", ref: analog}
  - {number: 13, name: AIN11P, type: analog, domain: AVDD_5V,
     function: "Analog input channel 11, positive input", ref: analog}
  - {number: 14, name: AIN11M, type: analog, domain: AVDD_5V,
     function: "Analog input channel 11, negative input", ref: analog}
  - {number: 15, name: AIN12P, type: analog, domain: AVDD_5V,
     function: "Analog input channel 12, positive input", ref: analog}
  - {number: 16, name: AIN12M, type: analog, domain: AVDD_5V,
     function: "Analog input channel 12, negative input", ref: analog}
  - {number: 17, name: AIN13P, type: analog, domain: AVDD_5V,
     function: "Analog input channel 13, positive input", ref: analog}
  - {number: 18, name: AIN13M, type: analog, domain: AVDD_5V,
     function: "Analog input channel 13, negative input", ref: analog}
  - {number: 19, name: AIN14P, type: analog, domain: AVDD_5V,
     function: "Analog input channel 14, positive input", ref: analog}
  - {number: 20, name: AIN14M, type: analog, domain: AVDD_5V,
     function: "Analog input channel 14, negative input", ref: analog}
  - {number: 21, name: AIN15P, type: analog, domain: AVDD_5V,
     function: "Analog input channel 15, positive input", ref: analog}
  - {number: 22, name: AIN15M, type: analog, domain: AVDD_5V,
     function: "Analog input channel 15, negative input", ref: analog}
  - {number: 23, name: AIN16P, type: analog, domain: AVDD_5V,
     function: "Analog input channel 16, positive input", ref: analog}
  - {number: 24, name: AIN16M, type: analog, domain: AVDD_5V,
     function: "Analog input channel 16, negative input", ref: analog}
  - {number: 25, name: GND, type: ground, domain: GND,
     function: "Ground", ref: pins}
  - {number: 26, name: AVDD_5V, type: power, domain: AVDD_5V,
     function: "5 V analog supply, 4.75 V to 5.25 V; 1 µF and 0.1 µF to GND at each supply pin", ref: supply}
  - {number: 27, name: AVDD_5V, type: power, domain: AVDD_5V,
     function: "5 V analog supply, 4.75 V to 5.25 V; 1 µF and 0.1 µF to GND at each supply pin", ref: supply}
  - {number: 28, name: REFM, type: ground, domain: GND,
     function: "Reference ground; short to the GND plane outside the device", ref: pins}
  - {number: 29, name: REFCAPB, type: analog, domain: AVDD_5V,
     function: "Reference amplifier output; 1 µF low-ESR X7R to REFM (pin 28)", ref: pins}
  - {number: 30, name: AVDD_1V8, type: power, domain: AVDD_1V8,
     function: "1.8 V supply, 1.7 V to 1.9 V; 1 µF and 0.1 µF to GND at each supply pin", ref: supply}
  - {number: 31, name: REFSEL, type: digital-in, domain: IOVDD,
     function: "Reference source: high selects the internal reference, low the external one (Table 7-3)", ref: reference}
  - {number: 32, name: RESET, type: digital-in, domain: IOVDD,
     function: "Hardware reset, active low", hook: reset, ref: pins}
  - {number: 33, name: GND, type: ground, domain: GND,
     function: "Ground", ref: pins}
  - {number: 34, name: IOVDD, type: power, domain: IOVDD,
     function: "Digital I/O supply, 1.7 V to 3.6 V; 1 µF and 0.1 µF to GND at each supply pin", ref: supply}
  - {number: 35, name: CS, type: bus, domain: IOVDD,
     function: "SPI chip select, active low", hook: transfer, ref: pins}
  - {number: 36, name: SDI, type: bus, domain: IOVDD,
     function: "SPI data in (MOSI)", hook: transfer, ref: pins}
  - {number: 37, name: SCLK, type: bus, domain: IOVDD,
     function: "SPI clock, up to 60 MHz", hook: transfer, ref: pins}
  - {number: 38, name: SDOUT, type: bus, domain: IOVDD,
     function: "SPI data out (MISO): register replies and the data of the 1-lane mode", hook: transfer, ref: pins}
  - {number: 39, name: D7, type: digital-io, domain: IOVDD,
     function: "Serial output data lane 7", hook: lanes, unused: Leave open, unverified: "the data sheet does not say how to terminate an unused data lane", ref: pins}
  - {number: 40, name: D6, type: digital-io, domain: IOVDD,
     function: "Serial output data lane 6", hook: lanes, unused: Leave open, unverified: "the data sheet does not say how to terminate an unused data lane", ref: pins}
  - {number: 41, name: D5, type: digital-io, domain: IOVDD,
     function: "Serial output data lane 5", hook: lanes, unused: Leave open, unverified: "the data sheet does not say how to terminate an unused data lane", ref: pins}
  - {number: 42, name: D4, type: digital-io, domain: IOVDD,
     function: "Serial output data lane 4", hook: lanes, unused: Leave open, unverified: "the data sheet does not say how to terminate an unused data lane", ref: pins}
  - {number: 43, name: D3, type: digital-io, domain: IOVDD,
     function: "Serial output data lane 3 or daisy-chain input 3", hook: lanes, unused: Leave open, unverified: "the data sheet does not say how to terminate an unused data lane", ref: pins}
  - {number: 44, name: D2, type: digital-io, domain: IOVDD,
     function: "Serial output data lane 2 or daisy-chain input 2", hook: lanes, unused: Leave open, unverified: "the data sheet does not say how to terminate an unused data lane", ref: pins}
  - {number: 45, name: D1, type: digital-io, domain: IOVDD,
     function: "Serial output data lane 1 or daisy-chain input 1", hook: lanes, unused: Leave open, unverified: "the data sheet does not say how to terminate an unused data lane", ref: pins}
  - {number: 46, name: D0, type: digital-io, domain: IOVDD,
     function: "Serial output data lane 0 or daisy-chain input 0", hook: lanes, unused: Leave open, unverified: "the data sheet does not say how to terminate an unused data lane", ref: pins}
  - {number: 47, name: IOVDD, type: power, domain: IOVDD,
     function: "Digital I/O supply, 1.7 V to 3.6 V; 1 µF and 0.1 µF to GND at each supply pin", ref: supply}
  - {number: 48, name: GND, type: ground, domain: GND,
     function: "Ground", ref: pins}
  - {number: 49, name: DRDY/ALARM, type: digital-io, domain: IOVDD,
     function: "Data ready or alarm, active high; polarity and source in DRDY_ALARM_SEL", hook: drdy, unused: Leave open, unverified: "unused-pin termination is not stated", ref: pins}
  - {number: 50, name: CONVST, type: digital-in, domain: IOVDD,
     function: "Start of conversion: the falling edge samples all 16 channels (section 7.4.2); keep it high before DRDY rises in the internal oversampling mode (Figure 5-7)", hook: convst, ref: pins}
  - {number: 51, name: AVDD_1V8, type: power, domain: AVDD_1V8,
     function: "1.8 V supply, 1.7 V to 1.9 V; 1 µF and 0.1 µF to GND at each supply pin", ref: supply}
  - {number: 52, name: REFCAPA, type: analog, domain: AVDD_5V,
     function: "Reference amplifier output; 1 µF low-ESR X7R to REFM (pin 53)", ref: pins}
  - {number: 53, name: REFM, type: ground, domain: GND,
     function: "Reference ground; short to the GND plane outside the device", ref: pins}
  - {number: 54, name: REFIO, type: analog, domain: AVDD_5V,
     function: "Internal reference output (REFSEL high) or external reference input (REFSEL low); 4.7 µF to REFM", ref: pins}
  - {number: 55, name: GND, type: ground, domain: GND,
     function: "Ground", ref: pins}
  - {number: 56, name: AVDD_5V, type: power, domain: AVDD_5V,
     function: "5 V analog supply, 4.75 V to 5.25 V; 1 µF and 0.1 µF to GND at each supply pin", ref: supply}
  - {number: 57, name: AIN1P, type: analog, domain: AVDD_5V,
     function: "Analog input channel 1, positive input", ref: analog}
  - {number: 58, name: AIN1M, type: analog, domain: AVDD_5V,
     function: "Analog input channel 1, negative input", ref: analog}
  - {number: 59, name: AIN2P, type: analog, domain: AVDD_5V,
     function: "Analog input channel 2, positive input", ref: analog}
  - {number: 60, name: AIN2M, type: analog, domain: AVDD_5V,
     function: "Analog input channel 2, negative input", ref: analog}
  - {number: 61, name: AIN3P, type: analog, domain: AVDD_5V,
     function: "Analog input channel 3, positive input", ref: analog}
  - {number: 62, name: AIN3M, type: analog, domain: AVDD_5V,
     function: "Analog input channel 3, negative input", ref: analog}
  - {number: 63, name: AIN4P, type: analog, domain: AVDD_5V,
     function: "Analog input channel 4, positive input", ref: analog}
  - {number: 64, name: AIN4M, type: analog, domain: AVDD_5V,
     function: "Analog input channel 4, negative input", ref: analog}
  - {number: EP, name: EPAD, type: ground, domain: GND, function: "Exposed thermal pad; connect to GND", ref: pins}

block_diagram:
  ref: blocks
  blocks:
    - {id: afe, label: Input clamps and PGA, detail: "1 MΩ inputs, 5 ranges, per-channel gain", at: [0, 0], tone: teal,
       pins: [AIN1P, AIN1M, AIN16P, AIN16M], side: left}
    - {id: adc, label: 16 SAR ADCs, detail: "simultaneous sampling, 1 MSPS each", at: [1, 0], tone: violet}
    - {id: ref, label: Reference, detail: "4.096 V internal, or external on REFIO", at: [0, 1], tone: amber,
       pins: [REFIO, REFSEL, REFCAPA, REFCAPB], side: left}
    - {id: dsp, label: Digital filters and calibration, detail: "offset, gain, phase, FIR, averages", at: [2, 0],
       tone: blue}
    - {id: out, label: Data interface, detail: "1, 2, 4 or 8 lanes, 16 or 24 bit", at: [3, 0], tone: blue,
       pins: [D0, D7, SDOUT], side: right}
    - {id: spi, label: Registers and control, detail: "three banks, 24-bit frames, CONVST", at: [3, 1], tone: blue,
       pins: [CS, SCLK, SDI, RESET, CONVST], side: right}
    - {id: dwc, label: Window comparator and alarm, detail: "per-channel limits", at: [2, 1], tone: amber}
  links:
    - {from: afe, to: adc, label: analog}
    - {from: ref, to: adc, label: VREF}
    - {from: adc, to: dsp, label: codes}
    - {from: dsp, to: out, label: results}
    - {from: dsp, to: dwc, label: codes}
    - {from: spi, to: dsp, label: settings}

circuits:
  - id: typical
    title: Typical application
    description: >-
      One channel of the ADS9324 with the internal reference (REFSEL high), the data on SDOUT (1 lane) and the three
      supplies decoupled as Figure 9-4 shows; CONVST, RESET and DRDY/ALARM are on GPIOs the driver uses through
      GpioSet() and GpioGet(). The other fifteen channels repeat the input filter.
    ref: app
    parts:
      - {id: U1, kind: chip}
      - id: U2
        kind: mcu
        label: MCU
        pins:
          - {name: SCK, label: SPI SCK}
          - {name: MOSI, label: SPI MOSI}
          - {name: MISO, label: SPI MISO}
          - {name: CS, label: GPIO / CS}
          - {name: RST, label: GPIO}
          - {name: CNV, label: GPIO / timer}
          - {name: RDY, label: GPIO (IRQ)}
          - VDD
          - GND
      - {id: C1, kind: capacitor, value: 1 µF, ref: supply}
      - {id: C2, kind: capacitor, value: 0.1 µF, ref: supply}
      - {id: C3, kind: capacitor, value: 1 µF, ref: supply}
      - {id: C4, kind: capacitor, value: 0.1 µF, ref: supply}
      - {id: C5, kind: capacitor, value: 1 µF, ref: supply}
      - {id: C6, kind: capacitor, value: 0.1 µF, ref: supply}
      - {id: C7, kind: capacitor, value: 4.7 µF, ref: pins}
      - {id: C8, kind: capacitor, value: 1 µF, ref: pins}
      - {id: C9, kind: capacitor, value: 1 µF, ref: pins}
      - {id: R1, kind: resistor, value: 1 kΩ, ref: app,
         unverified: "REXT: the data sheet gives no value; choose it for the source and the input filter"}
      - {id: R2, kind: resistor, value: 1 kΩ, ref: app,
         unverified: "REXT: matched to R1 so the positive and negative paths see equal source resistance"}
      - {id: C10, kind: capacitor, value: 10 nF, ref: app,
         unverified: "CEXT: the data sheet gives no value; it sets the filter corner with REXT"}
    nets:
      - {name: "+5V", kind: supply, nodes: [U1.AVDD_5V, C1.1, C2.1]}
      - {name: "+1V8", kind: supply, nodes: [U1.AVDD_1V8, C3.1, C4.1]}
      - {name: "+3V3", kind: supply, nodes: [U1.IOVDD, C5.1, C6.1, U1.REFSEL, U2.VDD],
         unverified: "example IOVDD; the data sheet allows 1.7 V to 3.6 V. REFSEL high selects the internal reference"}
      - {name: GND, kind: ground,
         nodes: [U1.GND, U1.REFM, U1.EPAD, C1.2, C2.2, C3.2, C4.2, C5.2, C6.2, C7.2, C8.2, C9.2, U2.GND]}
      - {name: REFIO, nodes: [U1.REFIO, C7.1]}
      - {name: REFCAPA, nodes: [U1.REFCAPA, C8.1]}
      - {name: REFCAPB, nodes: [U1.REFCAPB, C9.1]}
      - {name: IN1P, nodes: [U1.AIN1P, R1.2, C10.1]}
      - {name: IN1M, nodes: [U1.AIN1M, R2.2, C10.2]}
      - {name: SCLK, nodes: [U1.SCLK, U2.SCK]}
      - {name: SDI, nodes: [U1.SDI, U2.MOSI]}
      - {name: SDOUT, nodes: [U1.SDOUT, U2.MISO]}
      - {name: CS, nodes: [U1.CS, U2.CS]}
      - {name: RESET, nodes: [U1.RESET, U2.RST]}
      - {name: CONVST, nodes: [U1.CONVST, U2.CNV]}
      - {name: DRDY, nodes: [U1.DRDY/ALARM, U2.RDY]}
    unused: [U1.AIN2P, U1.AIN2M, U1.AIN3P, U1.AIN3M, U1.AIN4P, U1.AIN4M, U1.AIN5P, U1.AIN5M, U1.AIN6P, U1.AIN6M,
             U1.AIN7P, U1.AIN7M, U1.AIN8P, U1.AIN8M, U1.AIN9P, U1.AIN9M, U1.AIN10P, U1.AIN10M, U1.AIN11P, U1.AIN11M,
             U1.AIN12P, U1.AIN12M, U1.AIN13P, U1.AIN13M, U1.AIN14P, U1.AIN14M, U1.AIN15P, U1.AIN15M, U1.AIN16P,
             U1.AIN16M, U1.D0, U1.D1, U1.D2, U1.D3, U1.D4, U1.D5, U1.D6, U1.D7, R1.1, R2.1]
