Jetson ESP-Hosted Host Code — Embedded Linux Driver Reading Course¶
Deep Dive · Embedded Systems
Transfer driver-reading skills to a custom accelerator.
A structured mini-course for engineers who want to read a real Embedded Linux host stack instead of only consuming board bring-up tutorials.
The code studied here is the Jetson-oriented fork:
The case study is the historical esp_hosted_ng/host/ tree at revision ce36dec9294988e598f04e84c9d28092ca9e9786 (April 20, 2026), with board observations reported by its authors. Start with the source-reading lab, reviewed October 18. It verifies the source identity, traces success and failure, and identifies ownership/error-path defects in the teaching excerpts. The legacy fork is not presented as a current production implementation.
For current firmware/host integration, follow the ESP-Hosted-Linux migration lesson. Keep the two generations separate.
Why this course exists¶
Most Embedded Linux learning material splits the world into separate boxes:
- SPI and GPIO tutorials
- kernel module tutorials
- Wi-Fi tutorials
- Bluetooth tutorials
Real systems are not split that way.
This codebase is useful because one host stack crosses all of those at once:
- an out-of-tree kernel module
- a board-specific bring-up script
- SPI transport and GPIO IRQs
cfg80211Wi-Fi integration- HCI / BlueZ integration for BLE
- Linux userspace tools such as
nmcli,bluetoothctl,hciconfig, andrfkill
That makes it a strong Embedded Linux case study.
What you will learn¶
- How a Linux host driver maps a remote ESP chip into normal Linux interfaces.
- How board-specific shell tooling and generic kernel module code fit together.
- How to read transport code in
esp_spi.cwithout getting lost in implementation detail. - How Wi-Fi becomes
wlan0throughcfg80211. - How BLE becomes
hci0through the HCI subsystem. - How to separate:
- board policy
- transport policy
- Linux subsystem integration
Kernel interface map¶
This mini-course is also a guided tour of real Linux kernel interfaces. Read each lecture with two questions in mind:
- Which kernel object or subsystem boundary is this code talking to?
- What user-visible Linux artifact proves that step worked?
| Lecture | Linux-facing interfaces in the code | Kernel concepts to keep in mind | Foundational refresh |
|---|---|---|---|
| 1 | esp_add_card(...), esp_add_network_ifaces(...), esp_init_bt(...) |
subsystem boundaries, kernel vs userspace, what a driver is producing for Linux | OS Lecture 1 — Modern OS Architecture & the Linux Kernel |
| 2 | insmod, module_param(...), spidev unbind, out-of-tree .ko build |
loadable kernel modules, boot-time hardware description, device ownership | OS Lecture 5 — Kernel Modules, Boot Process & Device Tree |
| 3 | spi_find_device(...), gpio_to_irq(...), request_irq(...) |
SPI device model, top half vs deferred work, interrupt-driven I/O | OS Lecture 3 — Interrupts, Exceptions & Bottom Halves, OS Lecture 17 — Linux Device Driver Model & Device Tree, OS Lecture 18 — Character Drivers, Interrupt-Driven I/O & V4L2 |
| 4 | wiphy_new(...), wiphy_register(...), esp_cfg80211_add_iface(...), register_netdevice(...) |
Linux wireless subsystem contracts, wiphy, wireless_dev, netdev registration |
OS Lecture 17 — Linux Device Driver Model & Device Tree |
| 5 | hci_alloc_dev(), hci_register_dev(), hci_recv_frame(...) |
Bluetooth HCI as a subsystem boundary, controller registration, host/controller split | OS Lecture 1 — Modern OS Architecture & the Linux Kernel, OS Lecture 17 — Linux Device Driver Model & Device Tree |
That habit is more valuable than memorizing function names.
What you should already know¶
Before this mini-course, you should be comfortable with:
- Linux command-line basics
- the boot chain at a high level: bootloader -> kernel -> root filesystem
- device tree and kernel modules at a beginner level
- basic SPI/GPIO concepts
If not, do the main Embedded Linux guide and Yocto course first.
Step-by-step lectures¶
Each lecture is under Lecture/. Work in order.
| # | Topic | Lecture |
|---|---|---|
| 1 | Linux mental model for this host stack | Lecture-01.md |
| 2 | Build, load, and board policy on Jetson | Lecture-02.md |
| 3 | SPI transport, GPIOs, and IRQ-driven bring-up | Lecture-03.md |
| 4 | How Wi-Fi becomes wlan0 |
Lecture-04.md |
| 5 | How BLE becomes hci0 and how to validate the full path |
Lecture-05.md |
Recommended study pattern¶
For each lecture:
- read the Linux-side explanation first
- open the exact file in the repo
- trace the named functions yourself
- compare the explanation against the real code
- answer the lab questions before moving on
Do not try to memorize the whole repo. Learn to recognize the architecture and the subsystem boundaries.
Reported board context and reproduction boundary¶
The existing roadmap records the following bring-up observations. This course review did not rerun them; reproduce them with the matching fork revision, peer firmware, carrier board, pinmux, and kernel before using the values:
- Jetson Orin Nano over SPI
spi0.0resetpin=-1spi_handshake_gpio=471spi_dataready_gpio=433- runtime SPI clock capped at
10 MHz wlan0appears after manual ESP resethci0appears and BLE scan works
Global GPIO numbers and interface names can change across kernels and configurations. Translate schematic/header pins to the current GPIO controller and line, confirm voltage levels, and verify device ownership before adapting the example. A registered wlan0 or hci0 is one milestone; data exchange and restart recovery are separate checks.
Transfer driver-reading skills to a custom accelerator¶
Trace one command through board policy, transport submission, deferred work, subsystem completion, and cleanup. Record which context may sleep and who owns each buffer. Then imagine replacing the radio peer with an accelerator: which objects change, and which ownership, timeout, interrupt, and reset questions remain?
Pass the course with source links pinned to a commit, a successful exchange log if hardware is available, and a recovery analysis for peer reset during traffic. Interface registration alone is insufficient: verify data flow before claiming end-to-end success. Keep the reported board values above separate from your own tested configuration.
Carry forward: Pinned driver path, buffer ownership table, and reset/recovery evidence. Continue with the next course and reuse that evidence.