@typecad/framework-zephyr 1.0.0-alpha.13 → 1.0.0-alpha.15

package/src/lowering/pwm.ts

@@ -1,74 +1,167 @@
-// ---------------------------------------------------------------------------
-// PWM lowering — pwm_dt_spec via pwm-led0 alias
-//
-// The XIAO nRF52840 exposes PWM via the `pwm-led0` devicetree alias (PWM_OUT0
-// on P0.17, inverted). The lowering emits a `pwm_dt_spec` per channel and uses
-// `pwm_set_pulse_dt` / `pwm_set_dt`. Duty is scaled from the Arduino-style
-// 0–255 (or 0–1023) range to nanoseconds against the spec's period.
-// ---------------------------------------------------------------------------
-
-import type { HALOpIR } from '@typecad/cuttlefish/api/shared';
-import type { ZephyrChipDescriptor, ZephyrPwmSpec } from '../chips/types.js';
-
-/** Look up a PWM spec by HAL pin number. */
-function findPwmSpec(chip: ZephyrChipDescriptor, pin: number): ZephyrPwmSpec | undefined {
-  return chip.pwm?.specs.find((s) => s.pin === pin);
-}
-
-/** The C variable name emitted for a PWM channel's spec. */
-function pwmVarName(spec: ZephyrPwmSpec): string {
-  return `__tc_pwm_${spec.dtSpec.replace(/-/g, '_')}`;
-}
-
-/**
- * Emit the per-channel PWM spec declarations. One per spec in the chip
- * descriptor. Called from shimLines when the program uses PWM.
- */
-export function pwmInitLines(chip: ZephyrChipDescriptor): string[] {
-  const lines: string[] = ['// CUTTLEFISH_PWM_BEGIN'];
-  for (const spec of chip.pwm?.specs ?? []) {
-    lines.push(
-      `static const struct pwm_dt_spec ${pwmVarName(spec)} = PWM_DT_SPEC_GET(DT_ALIAS(${spec.dtSpec}));`,
-    );
-  }
-  lines.push('// CUTTLEFISH_PWM_END');
-  return lines;
-}
-
-/**
- * Resolve a HAL pwm.* op to Zephyr C++.
- * Returns `{ code }` for statement ops, `{ expression }` for value-returning ops.
- */
-export function lowerPwm(
-  op: HALOpIR,
-  chip: ZephyrChipDescriptor,
-): { code?: string; expression?: string } {
-  const o = op as any;
-  const spec = findPwmSpec(chip, o.pin);
-  if (!spec) {
-    // Probe / unlisted pin: return a comment so the resolver reports non-
-    // undefined (the manifest validator's probe sends pin:0 with no spec).
-    // A real program pins the descriptor's pwm.specs entry.
-    return { code: `/* pwm on pin ${o.pin}: no PWM spec in chip descriptor */` };
-  }
-  const v = pwmVarName(spec);
-
-  switch (op.operation) {
-    case 'pwm.write': {
-      // Duty is 0–255 (Arduino analogWrite). Scale to ns against the period.
-      return { code: `pwm_set_pulse_dt(&${v}, (static_cast<uint32_t>(${o.duty}) * ${v}.period) / 255);` };
-    }
-    case 'pwm.get_frequency': {
-      // period is in ns; frequency = 1e9 / period (Hz).
-      return { expression: `(${v}.period ? (1000000000ULL / ${v}.period) : 0)` };
-    }
-    case 'pwm.get_resolution':
-      // Arduino-compatible 8-bit duty range.
-      return { expression: '8' };
-    default:
-      throw new Error(
-        `framework-zephyr does not yet support HAL op \`${op.operation}\`. ` +
-          `Open an issue or use rawCpp() to emit it manually.`,
-      );
-  }
-}
+// ---------------------------------------------------------------------------
+// PWM lowering — pwm_dt_spec via pwm-led0 alias
+//
+// The XIAO nRF52840 exposes PWM via the `pwm-led0` devicetree alias (PWM_OUT0
+// on P0.17, inverted). The lowering emits a `pwm_dt_spec` per channel and uses
+// `pwm_set_pulse_dt` / `pwm_set_dt`. Duty is scaled from the Arduino-style
+// 0–255 (or 0–1023) range to nanoseconds against the spec's period.
+// ---------------------------------------------------------------------------
+
+import type { HALOpIR } from '@typecad/cuttlefish/api/shared';
+import type { ZephyrChipDescriptor, ZephyrPwmSpec } from '../chips/types.js';
+
+/**
+ * The DT alias a PWM spec is addressed by. Board-shipped specs carry their
+ * alias in `dtSpec`; synthesized specs (controller + channel) get a
+ * `tc-pwm<pin>` alias that the overlay generator creates in
+ * <board>.overlay — both sides derive the name from the pin so they agree.
+ */
+export function pwmDtAlias(spec: ZephyrPwmSpec): string {
+  return spec.dtSpec ?? `tc-pwm${spec.pin}`;
+}
+
+/**
+ * The C macro token for a spec's alias. Zephyr's devicetree macros replace
+ * dashes in alias names with underscores (`pwm-led0` in DTS is
+ * DT_ALIAS(pwm_led0) in C) — the dashed spelling is a subtraction
+ * expression and fails to compile (caught by the blackpill E2E west build).
+ */
+export function pwmDtAliasToken(spec: ZephyrPwmSpec): string {
+  return pwmDtAlias(spec).replace(/-/g, '_');
+}
+
+/**
+ * Look up a PWM spec by HAL pin number. Matrix pins (ESP32 LEDC) synthesize
+ * a spec on the fly: the channel is inert here — the emitted C++ addresses
+ * the pin only via its `tc-pwm<pin>` alias (the DT pwms cell carries the
+ * real channel, assigned by the overlay generator over the driven pins).
+ */
+export function findPwmSpec(chip: ZephyrChipDescriptor, pin: number): ZephyrPwmSpec | undefined {
+  const spec = chip.pwm?.specs.find((s) => s.pin === pin);
+  if (spec) return spec;
+  const m = chip.pwm?.matrix;
+  if (m && m.pins.includes(pin)) return { pin, controller: m.controller, channel: 0 };
+  return undefined;
+}
+
+/** The C variable name emitted for a PWM channel's spec. */
+function pwmVarName(spec: ZephyrPwmSpec): string {
+  return `__tc_pwm_${pwmDtAliasToken(spec)}`;
+}
+
+/**
+ * Emit the per-channel PWM spec declarations. One per spec in the chip
+ * descriptor that the PROGRAM ACTUALLY DRIVES (`usedPins`) — a spec for an
+ * untouched pin is unused code in the emitted TU (and would need a dead DT
+ * alias in the overlay). When `usedPins` is omitted (probe paths with no
+ * program), every spec is emitted. Called from shimLines when the program
+ * uses PWM.
+ */
+export function pwmInitLines(
+  chip: ZephyrChipDescriptor,
+  usedPins?: ReadonlySet<number>,
+  userSpecs?: readonly { pin: number; controller: string; channel: number }[],
+): string[] {
+  const lines: string[] = ['// CUTTLEFISH_PWM_BEGIN'];
+  for (const spec of chip.pwm?.specs ?? []) {
+    if (usedPins && !usedPins.has(spec.pin)) continue;
+    lines.push(
+      `static const struct pwm_dt_spec ${pwmVarName(spec)} = PWM_DT_SPEC_GET(DT_ALIAS(${pwmDtAliasToken(spec)}));`,
+    );
+  }
+  // Inline-override pins (the escape hatch): the construction opts vouch for
+  // controller+channel on a pin the manifest does not map — the alias var
+  // the lowered calls reference (the DT node itself comes from the overlay
+  // regen's marker merge).
+  for (const spec of userSpecs ?? []) {
+    if (chip.pwm?.specs.some((s) => s.pin === spec.pin)) continue;
+    if (usedPins && !usedPins.has(spec.pin)) continue;
+    lines.push(
+      `static const struct pwm_dt_spec ${pwmVarName(spec)} = PWM_DT_SPEC_GET(DT_ALIAS(${pwmDtAliasToken(spec)}));`,
+    );
+  }
+  // Matrix pins (ESP32 LEDC): one alias per driven pin, ascending — the same
+  // order the overlay generator assigns channels in, though the C++ never
+  // needs the channel (the DT pwms cell carries it). An omitted usage set
+  // (probe paths) emits every matrix pin, mirroring the static behavior.
+  const m = chip.pwm?.matrix;
+  if (m) {
+    const pins = (usedPins ? [...usedPins].filter((p) => m.pins.includes(p)) : [...m.pins])
+      .sort((a, b) => a - b);
+    for (const pin of pins) {
+      const spec: ZephyrPwmSpec = { pin, controller: m.controller, channel: 0 };
+      lines.push(
+        `static const struct pwm_dt_spec ${pwmVarName(spec)} = PWM_DT_SPEC_GET(DT_ALIAS(${pwmDtAliasToken(spec)}));`,
+      );
+    }
+  }
+  lines.push('// CUTTLEFISH_PWM_END');
+  return lines;
+}
+
+/**
+ * Resolve a HAL pwm.* op to Zephyr C++.
+ * Returns `{ code }` for statement ops, `{ expression }` for value-returning ops.
+ */
+export function lowerPwm(
+  op: HALOpIR,
+  chip: ZephyrChipDescriptor,
+): { code?: string; expression?: string } {
+  const o = op as any;
+  // Construction-time controller/channel overrides (hal/pwm-pin.ts opts):
+  // the user vouches for the routing. The spec synthesizes from the
+  // override (addressing rides the tc-pwm<pin> alias like a matrix pin) and
+  // a marker comment carries controller+channel to the overlay regen, which
+  // synthesizes the DT node — the transpiler cannot.
+  const hasOverride = (typeof o.controllerOverride === 'string' && o.controllerOverride !== '')
+    || (typeof o.channelOverride === 'number' && o.channelOverride >= 0);
+  const spec = hasOverride
+    ? {
+        pin: o.pin as number,
+        controller: (o.controllerOverride as string | undefined) ?? 'pwm0',
+        channel: (o.channelOverride as number | undefined) ?? 0,
+      }
+    : findPwmSpec(chip, o.pin);
+  if (!spec) {
+    // Probe / unlisted pin: return a comment so the resolver reports non-
+    // undefined (the manifest validator's probe sends pin:0 with no spec).
+    // A real program pins the descriptor's pwm.specs entry.
+    return { code: `/* pwm on pin ${o.pin}: no PWM spec in chip descriptor */` };
+  }
+  const v = pwmVarName(spec);
+  // The overlay regen (toolchain) parses this into a synthesized pwm-leds
+  // spec: pin → controller/channel. Comment placement inside the block
+  // braces is legal C.
+  const marker = hasOverride
+    ? `/* cuttlefish-user-facts: pwm pin=${spec.pin} controller=${spec.controller} channel=${spec.channel} */ `
+    : '';
+
+  switch (op.operation) {
+    // ── Thin PWM (hal/pwm-pin.ts) — ns-true verbs ──────────────────────────
+    // Zephyr 4.4 has pwm_set_dt (period + pulse) and pwm_set_pulse_dt (pulse
+    // only) — no period-only setter. The construction period is established
+    // once via pwm_set_dt(period, pulse 0 = line idle), then every set is one
+    // pwm_set_pulse_dt. No 0–255 scaling anywhere.
+    case 'pwm.set_pulse': {
+      return {
+        code: `{ ${marker}static bool __tc_pwm_p${o.pin}_prd = false; if (!__tc_pwm_p${o.pin}_prd) { (void)pwm_set_dt(&${v}, ${o.periodNs}, 0); __tc_pwm_p${o.pin}_prd = true; } (void)pwm_set_pulse_dt(&${v}, ${o.pulseNs}); }`,
+      };
+    }
+    case 'pwm.set_duty': {
+      // duty is 0.0–1.0; pulse = duty × the construction period.
+      return {
+        code: `{ ${marker}static bool __tc_pwm_p${o.pin}_prd = false; if (!__tc_pwm_p${o.pin}_prd) { (void)pwm_set_dt(&${v}, ${o.periodNs}, 0); __tc_pwm_p${o.pin}_prd = true; } (void)pwm_set_pulse_dt(&${v}, static_cast<uint32_t>(static_cast<double>(${o.duty}) * static_cast<double>(${o.periodNs}))); }`,
+      };
+    }
+    case 'pwm.set_period': {
+      // No period-only API: pwm_set_dt applies the new period and resets the
+      // pulse to idle — follow with setPulse/setDuty to drive the line.
+      return { code: `${marker}(void)pwm_set_dt(&${v}, ${o.periodNs}, 0);` };
+    }
+    default:
+      throw new Error(
+        `framework-zephyr does not yet support HAL op \`${op.operation}\`. ` +
+          `Open an issue or use rawCpp() to emit it manually.`,
+      );
+  }
+}

package/src/lowering/random.ts

@@ -5,7 +5,7 @@
 // the configured entropy source (the nRF52840 hardware RNG when
 // CONFIG_HARDWARE_DEVICE_RANDOM_GENERATOR is selected, or the default test/
 // xoroshiro generator otherwise). It is seeded automatically at boot from the
-// entropy driver, so unlike Arduino there is no implicit seeding step.
+// entropy driver, so there is no implicit seeding step.
 //
 // The HAL random surface is the Arduino-core model:
 //   random.int()    → a non-negative 31-bit integer [0, 2^31 - 1]
@@ -73,7 +73,7 @@ export function randomInitLines(): string[] {
     `}`,
     ``,
     `// Re-seed the PRNG. After this call the sequence is deterministic from`,
-    `// \`seed\`, matching Arduino randomSeed. A literal zero seed is accepted and`,
+    `// \`seed\`, matching the platform's randomSeed. A literal zero seed is accepted and`,
     `// remapped to the same odd constant (xorshift32 cannot start from 0).`,
     `static inline void __tc_rand_seed(uint32_t seed) {`,
     `    __tc_rand_state = (seed == 0U) ? 0x9E3779B9U : seed;`,
@@ -87,7 +87,7 @@ export function randomInitLines(): string[] {
     `}`,
     ``,
     `// Half-open range [min, max-1]. Implements the HAL contract directly rather`,
-    `// than calling Arduino random(min, max): the modulus rejection-free form`,
+    `// than calling the platform random(min, max): the modulus rejection-free form`,
     `// avoids the modulo bias a naive (rand % (max-min)) introduces. max > min`,
     `// is assumed (the HAL validates this at the source level).`,
     `static inline int32_t __tc_rand_range(int32_t min, int32_t max) {`,

package/src/lowering/sensor.ts

@@ -0,0 +1,155 @@
+// ---------------------------------------------------------------------------
+// Sensor lowering — Zephyr's uniform sensor API over the generated catalog
+//
+// One code shape for every part in @typecad/hal's sensor catalog: the op's
+// part token resolves to the DT compatible, the bus string to the controller
+// index, and the address to the I2C reg. The names are derived identically
+// here (device handles), in strategy.ts state blocks, and in the overlay
+// scanner (dt-config/overlay.ts + toolchain/index.ts) — the tc-pwm<pin>
+// discipline: both sides derive from the same facts, so they cannot drift.
+//
+// Kconfig: nothing per-part. The in-tree driver Kconfigs are `default y` on
+// DT_HAS_<COMPAT>_ENABLED, so the overlay's child node IS the enable switch;
+// CONFIG_SENSOR (the umbrella under `if SENSOR`) is usage-gated in
+// dt-config/kconfig.ts off the lowered `sensor_` tokens.
+// ---------------------------------------------------------------------------
+
+import { SENSOR_PART_INFO } from '@typecad/hal';
+import type { HALOpIR } from '@typecad/cuttlefish/api/shared';
+import { parseControllerIndex } from './util.js';
+
+/** Strip the 'SENSOR.' property-access prefix from a part token arg. */
+export function sensorPartKey(part: string): string {
+  return part.replace(/^SENSOR\./, '');
+}
+
+/** Strip the 'CHAN.' property-access prefix from a channel arg. */
+export function sensorChanName(chan: string): string {
+  return chan.replace(/^CHAN\./, '');
+}
+
+/** All names a constructed sensor is known by, derived from the op facts. */
+export interface SensorNames {
+  /** DT nodelabel of the child node the overlay emits
+   *  (tc_<part>_i2c<N>_0x<addr> / tc_<part>_spi<N>_cs<pin>). */
+  dtLabel: string;
+  /** C device-handle variable (__tc_sensor_<stem>_dev). */
+  devVar: string;
+  /** C sensor_value scratch variable (__tc_sensor_<stem>_val). */
+  valVar: string;
+  /** The controller index the bus string carries. */
+  busIndex: number;
+  /** The bus port: I2C address or SPI CS pin. */
+  port: number;
+  /** 'i2c' | 'spi'. */
+  busKind: 'i2c' | 'spi';
+}
+
+/** Derive a sensor's DT/C++ names. The scanner regexes the emitted __tc_
+ *  prefix form, so the part group must stay [a-z0-9_]+ and greedy. */
+export function sensorNames(part: string, bus: string, port: number | string, busKind: string = 'i2c'): SensorNames {
+  const partKey = sensorPartKey(String(part));
+  const busIndex = parseControllerIndex(typeof bus === 'string' ? bus : String(bus));
+  const portNum = typeof port === 'number' ? port : parseInt(String(port));
+  const stem = busKind === 'spi'
+    ? `${partKey}_spi${busIndex}_cs${portNum}`
+    : `${partKey}_i2c${busIndex}_0x${portNum.toString(16)}`;
+  return {
+    dtLabel: `tc_${stem}`,
+    devVar: `__tc_sensor_${stem}_dev`,
+    valVar: `__tc_sensor_${stem}_val`,
+    busIndex,
+    port: portNum,
+    busKind: busKind === 'spi' ? 'spi' : 'i2c',
+  };
+}
+
+/**
+ * Resolve the part token against the generated catalog, validating the bus
+ * kind and (when the driver scan knows them) the channel. Throws a build-time
+ * error with the Zephyr-facing name — the same words the user would meet in
+ * Zephyr docs, checked before west ever runs.
+ */
+/** @internal */
+function requirePartInfo(partKey: string) {
+  const info = SENSOR_PART_INFO[partKey];
+  if (!info) {
+    throw new Error(
+      `Sensor part '${partKey}' is not in the Zephyr sensor catalog (SENSOR in @typecad/hal). ` +
+        `Check the token against the catalog — it is the compatible with , and - replaced by _.`,
+    );
+  }
+  return info;
+}
+
+/** Validate the op's bus kind against the part's bindings. */
+function requireBusKind(partKey: string, info: ReturnType<typeof requirePartInfo>, busKind: string) {
+  if (!info.buses.includes(busKind)) {
+    throw new Error(
+      `Sensor part '${partKey}' (${info.compatible}) does not bind on ${busKind.toUpperCase()} — ` +
+        `its bindings are ${info.buses.join('/').toUpperCase()}.`,
+    );
+  }
+}
+
+/**
+ * Emit the per-sensor state block (device handle + sensor_value scratch).
+ * Called from shimLines for each distinct sensor the program's ops reference.
+ */
+export function sensorStateLines(part: string, bus: string, port: number | string, busKind: string = 'i2c', spiHz: number | string = 0, spiMode: number | string = 0, alertPin: number | string = -1): string[] {
+  const partKey = sensorPartKey(String(part));
+  requireBusKind(partKey, requirePartInfo(partKey), busKind);
+  const n = sensorNames(part, bus, port, busKind);
+  // The config comment carries construction facts (SPI clock, mode, alert
+  // GPIO) to the overlay scanner — they shape the DT node, not the C++.
+  const cfg = `// tc-sensor-cfg: ${n.dtLabel} hz=${Number(spiHz)} mode=${Number(spiMode)} alert=${Number(alertPin)}`;
+  return [
+    '// CUTTLEFISH_SENSOR_BEGIN',
+    `static const struct device* ${n.devVar} = DEVICE_DT_GET(DT_NODELABEL(${n.dtLabel}));`,
+    `static struct sensor_value ${n.valVar};`,
+    cfg,
+    '// CUTTLEFISH_SENSOR_END',
+  ];
+}
+
+/**
+ * Resolve a HAL sensor.* op to Zephyr C++.
+ * Returns `{ code }` for fetch (statement), `{ expression }` for get (value).
+ */
+export function lowerSensor(op: HALOpIR): { code?: string; expression?: string } {
+  const o = op as any;
+  const partKey = sensorPartKey(String(o.part));
+  const info = requirePartInfo(partKey);
+  requireBusKind(partKey, info, String(o.busKind ?? 'i2c'));
+  const n = sensorNames(o.part, o.bus, o.port ?? o.address, String(o.busKind ?? 'i2c'));
+
+  switch (op.operation) {
+    case 'sensor.fetch':
+      // sensor_sample_fetch. The leading (void) keeps the value scratch
+      // referenced under Zephyr's -Werror when the program fetches but never
+      // reads a channel (the state block is emitted per referenced sensor).
+      return {
+        code: `(void)${n.valVar}; sensor_sample_fetch(${n.devVar});`,
+      };
+    case 'sensor.get': {
+      const chan = sensorChanName(String(o.chan));
+      if (info.channels.length > 0 && !info.channels.includes(chan)) {
+        throw new Error(
+          `Sensor part '${partKey}' (${info.compatible}) does not serve channel '${chan}' — ` +
+            `its driver serves: ${info.channels.join(', ')}.`,
+        );
+      }
+      // sensor_value is val1 + val2 * 1e-6; evaluate once per read.
+      return {
+        expression:
+          `(sensor_channel_get(${n.devVar}, SENSOR_CHAN_${chan}, &${n.valVar}), ` +
+          `static_cast<double>(${n.valVar}.val1) + static_cast<double>(${n.valVar}.val2) / 1000000.0)`,
+      };
+    }
+    default:
+      throw new Error(
+        `framework-zephyr does not yet support HAL op \`${op.operation}\`. ` +
+          `Open an issue or use rawCpp() to emit it manually.`,
+      );
+  }
+}