diff options
Diffstat (limited to 'src/board_pins.zig')
| -rw-r--r-- | src/board_pins.zig | 186 |
1 files changed, 186 insertions, 0 deletions
diff --git a/src/board_pins.zig b/src/board_pins.zig new file mode 100644 index 00000000..134cd92c --- /dev/null +++ b/src/board_pins.zig @@ -0,0 +1,186 @@ +//! JP1, the JC-ESP32P4-M3-DEV's 26-pin header, as ONE TABLE that everything else is derived from: +//! the ASCII drawing the `Gpio` word prints, and the pin directories the board's 9P tree generates. +//! +//! WHY THIS IS ITS OWN FILE, and it is the whole reason it exists. The drawing lived in +//! `src/board_memory.zig`, which imports `pardes.zig` and therefore the entire core; the board's 9P +//! image (`src/esp32p4_9p.zig`) links no core at all, so it could not have reached it. The two +//! ways out of that were a second copy of the header in the 9P tree — a table of thirteen rows +//! transcribed off a schematic, maintained twice, with no test that could tell you the day they +//! disagreed — or this: a LEAF that imports `std` and nothing else, so both sides import the same +//! thirteen rows. `board_memory.zig` keeps its `pinout` name as an alias of `jp1_text` and its own +//! shape test, so the console word's output is unchanged to the byte. +//! +//! WHY A TABLE AND NOT THE STRING. The string was the source before, and a string is fine for one +//! consumer that prints it. It is no use at all to the second, which needs to know WHICH of these +//! twenty-six pins are the P4's own GPIOs, because that is the set of directories its tree has. A +//! consumer would have to parse the drawing back out — scan for `GPIO `, take the digits, hope +//! nobody aligned a column differently — which is exactly the sort of code that works until the +//! day the drawing is edited. So the rows are data, the drawing is RENDERED from them at comptime, +//! and `gpio_pins` is COLLECTED from them at comptime. Adding a pin to the header is one row, and +//! the drawing, the pin list and the 9P tree all move together because there is only one of them. +//! +//! READ OFF THE VENDOR SCHEMATIC, sheet 2 "Expand IO" +//! (`01-esp32p4-m3/docs/schematics/2_EXPAND_IO&BAT.png`), which is the only document that carries +//! this mapping — the specification PDF's "Interface Description" page is a marketing render, and +//! there is no board user guide. The sheet is a 872x1168 raster, so the assignment was taken from +//! the drawing's own geometry rather than by eye: thirteen wires leave each side of the symbol, a +//! net wire runs ~100 px to its label and a power stub ~21 px, which is what identifies pin 8 as +//! unconnected rather than as the first of the GPIO4x labels. Cross-checked against a second, +//! independent source: `05-zig-p4/build.zig` has always documented `-Dled=20` as "JP1 pin 17", and +//! GPIO20 lands on pin 17 here. +const std = @import("std"); + +/// What is behind one header pin, and the ONE distinction that matters to both consumers: whether +/// this pad is a GPIO of the ESP32-P4 this program is running on. +/// +/// `.none` is a pin the header brings out with nothing behind it (pin 8). `.net` is a pad that is +/// not the P4's to drive as a GPIO: `3V3`, `5V` and `GND` are power, `C6_*` are the ESP32-C6 +/// companion's pins — toggling a P4 GPIO cannot reach them — and `ES_I2C_*` is the audio codec's +/// bus. The codec's two ARE P4 pads, and they are `.net` anyway, deliberately: the schematic does +/// not name their GPIO numbers, and a tree that invented one would offer a file that drives an +/// unknown pin. They stay in the drawing because a shared bus is a reason to know the pin is there. +pub const Pad = union(enum) { + none, + /// a P4 GPIO, by the number the schematic, the silkscreen and the datasheet all use + gpio: u8, + /// a named net that is not a P4 GPIO + net: []const u8, + + /// The text this pad wears in the drawing. `GPIO 47` and not `GPIO47`: the space is what the + /// header has always printed, and the shape test in `board_memory.zig` matches on it. + pub fn label(p: Pad) []const u8 { + return switch (p) { + .none => "--", + .gpio => |n| std.fmt.comptimePrint("GPIO {d}", .{n}), + .net => |s| s, + }; + } +}; + +/// One row of the header: the odd pin on the left, the even pin on its right, exactly as the board +/// wears it. The pin NUMBERS are not stored — row `i` is pins `2i+1` and `2i+2` — because a +/// hand-written number beside a row is a number that can disagree with its position. +pub const Row = struct { left: Pad, right: Pad }; + +/// JP1 itself: thirteen rows, pin 1 at the top left. THE SINGLE SOURCE for the drawing below, for +/// `gpio_pins`, and for the per-pin directories in `src/board9p.zig`. +pub const jp1 = [13]Row{ + .{ .left = .{ .net = "3V3" }, .right = .{ .net = "5V" } }, + .{ .left = .{ .net = "3V3" }, .right = .{ .net = "5V" } }, + .{ .left = .{ .net = "GND" }, .right = .{ .net = "GND" } }, + .{ .left = .{ .gpio = 1 }, .right = .none }, + .{ .left = .{ .gpio = 2 }, .right = .{ .gpio = 47 } }, + .{ .left = .{ .gpio = 3 }, .right = .{ .gpio = 46 } }, + .{ .left = .{ .gpio = 4 }, .right = .{ .gpio = 45 } }, + .{ .left = .{ .gpio = 5 }, .right = .{ .net = "GND" } }, + .{ .left = .{ .gpio = 20 }, .right = .{ .net = "3V3" } }, + .{ .left = .{ .gpio = 32 }, .right = .{ .net = "C6_U0RXD" } }, + .{ .left = .{ .gpio = 33 }, .right = .{ .net = "C6_U0TXD" } }, + .{ .left = .{ .net = "ES_I2C_SDA" }, .right = .{ .net = "C6_IO9" } }, + .{ .left = .{ .net = "ES_I2C_SCL" }, .right = .{ .net = "C6_CHIP_PU" } }, +}; + +/// The row format, and it is load-bearing rather than cosmetic: a header drawn in two columns stops +/// being a header the moment a row wraps or a column slips, and the widest row here is 34 columns +/// against the board's own 80-column grid. Ten for the left label right-aligned, two for each pin +/// number, and the three bars land under the box's own corners because the left label's field plus +/// one space is eleven characters and `+---------+` is eleven wide. +/// +/// `board_memory.zig`'s "the pinout fits the board's own grid" test is the check that this stays +/// true, and it checks the RENDERED text mechanically — every pin row's first bar in the same +/// column — rather than trusting this string. +const row_format = "{s:>10} | {d:>2} | {d:>2} | {s}\n"; + +/// The box the pin numbers sit inside. Eleven characters, indented by the left label's field width +/// plus the space before the first bar, so its corners are the bars. +const border = " +---------+\n"; + +/// JP1 as the text the `Gpio` word prints and a read of the 9P tree's `gpio/pinout` returns — the +/// SAME BYTES, which is a test in `src/board9p.zig` and not a hope. +/// +/// The trailer names the `Gpio` word, which the 9P image does not have. It is here anyway, because +/// "the same bytes" is worth more than a sentence that is true of both faces and useful to neither: +/// a person reading this table through 9P is a person who has the editor's own console in the other +/// window, and telling them the word that flips a pin is telling them something they can use. The +/// 9P equivalent — writing `0` or `1` to `gpio/<n>/value` — is documented where a 9P client will +/// look for it, which is the tree's own doc comment. +pub const jp1_text = text: { + var out: []const u8 = + \\JP1 header - 26 pins, pin 1 top left. + \\Every number here is DECIMAL. + \\ + \\ + ; + out = out ++ border; + for (jp1, 0..) |row, i| out = out ++ std.fmt.comptimePrint( + row_format, + .{ row.left.label(), 2 * i + 1, 2 * i + 2, row.right.label() }, + ); + break :text out ++ border ++ + \\ + \\Gpio <pin> flips one: 0->1 or 1->0. + \\ + ; +}; + +/// Every P4 GPIO JP1 brings out, ascending. THE SET OF PIN DIRECTORIES the board's 9P tree has, so +/// that tree has exactly the pins this board has and not a range somebody typed. +/// +/// Ascending rather than in header order, because the consumer is `ls`: the header's order puts 47 +/// between 2 and 3, and a directory listing that counts 1 2 3 4 5 20 32 33 45 46 47 is one a person +/// can scan. Nothing depends on the order — the names are the pin numbers — so it may as well be +/// the readable one. +pub const gpio_pins = pins: { + var found: [2 * jp1.len]u8 = undefined; + var n: usize = 0; + for (jp1) |row| for ([2]Pad{ row.left, row.right }) |p| switch (p) { + .gpio => |g| { + found[n] = g; + n += 1; + }, + else => {}, + }; + std.mem.sort(u8, found[0..n], {}, std.sort.asc(u8)); + break :pins found[0..n].*; +}; + +// The drawing, byte for byte, because it is the one thing here whose CORRECTNESS IS ITS SHAPE and +// because it used to be a string literal: this is the check that the renderer above reproduces what +// the console has always printed. A golden test is the right kind of duplication — the expectation +// is the thing being asserted, and if the two ever differ the diff says which byte. +test "the rendered header is the drawing the console has always printed" { + try std.testing.expectEqualStrings( + \\JP1 header - 26 pins, pin 1 top left. + \\Every number here is DECIMAL. + \\ + \\ +---------+ + \\ 3V3 | 1 | 2 | 5V + \\ 3V3 | 3 | 4 | 5V + \\ GND | 5 | 6 | GND + \\ GPIO 1 | 7 | 8 | -- + \\ GPIO 2 | 9 | 10 | GPIO 47 + \\ GPIO 3 | 11 | 12 | GPIO 46 + \\ GPIO 4 | 13 | 14 | GPIO 45 + \\ GPIO 5 | 15 | 16 | GND + \\ GPIO 20 | 17 | 18 | 3V3 + \\ GPIO 32 | 19 | 20 | C6_U0RXD + \\ GPIO 33 | 21 | 22 | C6_U0TXD + \\ES_I2C_SDA | 23 | 24 | C6_IO9 + \\ES_I2C_SCL | 25 | 26 | C6_CHIP_PU + \\ +---------+ + \\ + \\Gpio <pin> flips one: 0->1 or 1->0. + \\ + , jp1_text); +} + +// The pin list is the tree's shape, so it is asserted as a list rather than as a count: a row edited +// wrongly changes WHICH pins the board offers, and a count would not notice a 45 that became a 44. +test "the header's own GPIOs, and only those" { + try std.testing.expectEqualSlices(u8, &.{ 1, 2, 3, 4, 5, 20, 32, 33, 45, 46, 47 }, &gpio_pins); + // Pin 8 is unconnected and pin 24 is the C6's, so neither contributes a pad. Both are counted + // here rather than only drawn, because "the tree has exactly the pins the board has" is a claim + // about what is ABSENT as much as what is present. + try std.testing.expectEqual(Pad.none, jp1[3].right); + try std.testing.expectEqualStrings("C6_IO9", jp1[11].right.net); +} |