<!--
  HACKING.md - Description of sbc-harness sources

  Copyright (C) 2024-2025  Luke T. Shumaker <lukeshu@lukeshu.com>
  SPDX-License-Identifier: AGPL-3.0-or-later
-->

# Source Layout

Our own "flavor" of C: GNU C plus `-fplan9-extensions`, making use of:

 - `libobj/`: For Go-like object-oriented programming
 - `libmisc/`: Low-level C programming utilities; sort of an augmented
   "libc"

Our own tiny cooperative-multitasking OS:

 - `libcr/`: The kernel (a simple coroutine library)
 - `libcr_ipc/`: IPC primatives (semaphores, mutexes, channels, ...)
   for libcr
 - `libhw/`: The hardware drivers
 - `libhw_generic/`: The hardware abstraction layer

Libraries for generic parts of what the harness is doing:

 - `lib9p/`: a 9P network filesystem server library
 - `lib9p_util/`: Utilities for use with lib9p
 - `libdhcp/`: A DHCP client
 - `libusb/`: Wrapper and utilities for TinyUSB

 - `cmd/sbc_harness/`: The main firmware image
 - `3rd-party/`: Sources from third parties; some definitions of
   things (USB language codes, Linux kernel errnos), and the Pico-SDK
   (for the RP2040 CPU, and its included TinyUSB).  Does not include
   newlib, which you need to have installed separately.
 - `build-aux/`: Build-system files

# Debugging

There are 2 "debug" connectors on the harness:

## UART (Universal Asynchronous Receiver/Transmitter) logging

Baud rate: 115200

Pinout:
| RPi Pico | RP2040 | Use                                    |
|----------|--------|----------------------------------------|
| pin1     | gpio0  | TX (so connect it to your FTDI's RX)   |
| pin2     | gpio1  | RX (so connect it to your FTDI's TX)   |
| pin3     |        | gnd (so connect it to your FTDI's GND) |

Example use:

> I use `picocom` (because it's small and Parabola GNU/Linux-libre
> has it), but other programs such as GNU Screen or minicom work
> as well.
>
> I sometimes use a Rasberry Pi Debug Probe (see below) as my
> UART-to-USB adapter because it's convenient because I'm using it
> anyway for ARM SWD.  I sometimes use a FTDI-brand adapter because it
> seems to be more reliable; the Debug Probe can sometimes get
> messed-up byte boundaries.
>
> Depending on your UART adapter, on GNU/Linux the device may be
> named either `/dev/ttyUSB{n}` or `/dev/ttyACM{n}`.
>
> - `picocom --baud=115200 /dev/ttyUSB0`
> - `picocom --baud=115200 /dev/ttyACM0`

## ARM SWD (Serial Wire Debug)

Pinout: Separate from the main 40-pin layout of the RPi Pico, there
are 3 separate ARM SWD pins; they may have a [Raspberry Pi 3-pin Debug
Connector][#raspberry-pi-3-pin-debug-connector] socket soldered to
them, or may just be regular pin headers.
| Pin # | ARM SW-DP (Single-Wire Debug-Port) |
|-------|------------------------------------|
| 1     | SC/SWCLK (serial clock)            |
| 2     | GND                                |
| 3     | SD/SWDIO (bidi serial data)        |
| N/C   | SWO (optional: serial wire output) |

The RP2040 CPU speaks the ADIv5 SWD protocol on this port; you need a
separate USB device to translate this to the ARM CMSIS-DAP protocol (a
USB-based protocol), and then a piece of software on your PC  to talk
CMSIS-DAP; likely [OpenOCD](https://openocd.org/) to bridge to the GNU
Debugger (GDB):

```
┌─[Host PC]─────────────────────────┐
│              ┌─────┐              │
│              │ GDB │              │
│              └─────┘              │
│                 ⇑                 │
│                 ║ GDB Remote Serial Protocol on localhost:3333
│                 ⇓                 │
│            ┌─────────┐            │
│            │ OpenOCD │            │
│            └─────────┘            │
│                 ⇑                 │
└─────────────────║─────────────────┘
                USB-A
                  ║ ARM CMSIS-DAP protocol (a USB-based protocol)
            (micro)USB-B
       ┌─[Debug Probe]───────┐
       │          ⇓          │
       │  ┌────────────────┐ │
       │  │     ARM's      │ │
       │  │   reference    │ │
       │  │   CMSIS-DAP    │ │
       │  │ implementation │ │
       │  └────────────────┘ │
       │          ⇑          │
       └──────────║──────────┘
         SW-DP (3-pin JST-SH)
                  ║ ADIv5 SWD protocol
        SW-DP (3 .1" headers)
┌─[SBC-Harness]───║─────────────────┐
│ ╔═══════════════╝                 │
│ ║  ┌────────────────────────────┐ │
│ ║  │ Cortex-M0+ (core 0)        │ │
│ ║  │ ┌────────────────────────┐ │ │
│ ╠═══⇒│ CoreSight ADIv5 module │ │ │
│ ║  │ └────────────────────────┘ │ │
│ ║  └────────────────────────────┘ │
│ ║  ┌────────────────────────────┐ │
│ ║  │ Cortex-M0+ (core 1)        │ │
│ ║  │ ┌────────────────────────┐ │ │
│ ╚═══⇒│ CoreSight ADIv5 module │ │ │
│    │ └────────────────────────┘ │ │
│    └────────────────────────────┘ │
└───────────────────────────────────┘
```

Example use:

> For the device that translates from ADIv5 SWD to CMSIS-DAP, I use
> the [Raspberry Pi Debug
> Probe](https://www.raspberrypi.com/products/debug-probe/) because it
> is cheap, runs Free Software, and is also a UART-to-USB adapter, so
> I can use it for both ports with less clutter on my desk ([source
> code](https://github.com/raspberrypi/debugprobe),
> [tutorial](https://www.raspberrypi.com/documentation/microcontrollers/debug-probe.html).
> Another freedom-friendly option is the
> https://oshwlab.com/wagiminator/samd11c-swd-programmer which uses
> https://github.com/ataradov/free-dap instead of ARM's reference
> CMSIS implementation; but I have not tried it.
>
> I use OpenOCD for talking CMSIS-DAP from my laptop, but pyOCD is
> another option.
>
> In one terminal:
> - `openocd -f interface/cmsis-dap.cfg -c 'set USE_CORE 0' -f target/rp2040.cfg -c "adapter speed 5000"`
>   (Explanation of `USE_CORE`: https://github.com/raspberrypi/debugprobe/issues/45)
> In another terminal:
> - `arm-none-eabi-gdb ./build/rp2040-Debug/cmd/sbc_harness/sbc_harness.elf`
>   ```
>   target extended-remote localhost:3333
>   monitor reset init
>   continue
>   ```
>   See https://openocd.org/doc/html/General-Commands.html for
>   documentation on the commands that you can send from GDB to
>   OpenOCD with `monitor`.

References:
- https://developer.arm.com/documentation/101761/1-0/Debug-and-trace-interface/Serial-Wire-Debug-signals
- https://developer.arm.com/documentation/ihi0031/a/The-Serial-Wire-Debug-Port--SW-DP-/Introduction-to-the-ARM-Serial-Wire-Debug--SWD--protocol
- https://arm-software.github.io/CMSIS-DAP/latest/index.html
- ADIv5: https://developer.arm.com/documentation/ihi0031/g/
- ADIv6: https://developer.arm.com/documentation/ihi0074/e/

# Other references

## Raspberry Pi 3-pin Debug Connector

- https://datasheets.raspberrypi.com/debug/debug-connector-specification.pdf

| Pin # | UART                 | ARM SW-DP                          | cJTAG (IEEE 1149.7)              |
|-------|----------------------|------------------------------------|----------------------------------|
| 1     | RX (target←debugger) | SC/SWCLK (serial clock)            | TMSC - Test Clock Control        |
| 2     | GND                  | GND                                | GND                              |
| 3     | TX (target→debugger) | SD/SWDIO (bidi serial data)        | TCKC - Test Master/Slave Control |
|       |                      | SWO (optional: serial wire output) |                                  |

Note that the RP2040 chip has a pure SW-DP (just speaks SWD), not a
JTAG-DP (just speaks JTAG) nor a SWJ-DP (can speak either SWD or
JTAG).

The Raspberry Pi Debug Probe has 2 debug connectors on it; one to
connect to the UART (labeled "U"), one to connect to the SWD (labeled
"D").