fix(gpio): pin state consistency across boot chain + SFSEL patch

[dakejahl]

Summary

Fixes the customer-reported GPIO pin drift on application exit (issue #54). Three stacked changes:

• Patch the JP 6.2.1 pinctrl-tegra SFSEL regression. NVIDIA's official fix (forum 301171) captures the original PADCTL SFIO bit on gpio_request_enable and restores it on gpio_disable_free, instead of unconditionally setting bit [10] = 1 on release. Dropped into patches/pinctrl-tegra-sfsel.patch and applied automatically by build_kernel.sh. Bundled in r36.5 / JP 6.2.2, so this patch becomes a no-op once we rebase.
• Complete the MB1 BCT configuration for the I2S connector / HDR40 pins on all three carriers (JAJ / PAB / PAB_V3). The 5 I2S pins (H,7 / I,0 / I,1 / I,2 / AC,6 on JAJ and PAB; 4 pins on PAB_V3) now come up as driven output-low at boot with tristate=DISABLE, enable-input=DISABLE, pull=NONE. On PAB_V3, AC,6 is preserved as output-high — it's the KSZ8795 ethernet switch reset line and must stay deasserted.
• Add docs/gpio.md — a customer-facing guide explaining the three-layer model (MB1 BCT → kernel pinctrl → userspace chardev), what this BSP handles for them, why userspace release semantics are what they are, and how to reconfigure pins (BCT edits, gpio-hog, partial-BCT flash recipe).

Supersedes #42 (JAJ-only, closed without merge). Addresses #32.

What this does NOT fix

Linux chardev semantics mean that when a userspace app drives a pin high and then exits, the OUTPUT_VALUE register in the Tegra GPIO controller retains the last written value. This PR does not add a kernel mechanism to re-apply BCT defaults on line release — that would require either upstream kernel work or a custom driver, and would break valid use cases where a single gpioset is expected to persist. docs/gpio.md spells this out and recommends the standard upstream patterns (systemd Restart=always, gpioset --mode=signal, gpio-hog for pins that should never be touched, external pull resistors for safety-critical outputs).

Test plan

• ./build_kernel.sh completes successfully for all three targets (PAB, JAJ, PAB_V3). Patch-apply log shows both Jetvariety and pinctrl-tegra-sfsel applied idempotently.
• Re-running ./build_kernel.sh on an already-patched source tree reports "already applied" for both patches and does not fail.
• Flash all three boards. On each, verify at boot (before any userspace app runs):
  • cat /sys/kernel/debug/gpio shows I2S pins soc_gpio41_ph7 / 42_pi0 / 43_pi1 / 44_pi2 as output-low on JAJ/PAB/PAB_V3.
  • soc_gpio59_pac6 is output-low on JAJ/PAB, output-high on PAB_V3.
  • gpioinfo shows these lines as unused with the correct direction/value.
  • Voltmeter reads ~0V on the relevant HDR40 header pins (JAJ/PAB) and the PAB_V3 I2S pins; KSZ8795 link still comes up on PAB_V3 (AC,6 deasserted).
• Userspace test: apply ark_i2s_gpio overlay, gpioset gpiochip0 PI.00=1, kill the gpioset process, verify pin stays in GPIO mode (not re-muxed to SFIO). Without the SFSEL patch the pin would revert to rsvd2; with it, the pad stays connected to the GPIO block.
• Confirm ark_i2s_gpio.dts overlay still works end-to-end for normal GPIO usage.
• Confirm PAB_V3 ethernet still works (AC,6 / KSZ8795 reset unchanged).

Notes

• device_tree/ark_pab_v3/.../tegra234-mb1-bct-gpio-p3767-dp-a03.dtsi diff is intentionally smaller than JAJ/PAB — only 4 I2S pins move, AC,6 stays in gpio-output-high.
• The build_kernel.sh refactor extracts a small apply_patch helper so additional patches can be added without duplicating the idempotency logic.

🤖 Generated with Claude Code