summaryrefslogtreecommitdiff
path: root/README.md
blob: c74f34f46163fe59ffe527c98c7e409f5d67d592 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
<!--
  README.md - Description of sbc-harness

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

# Building

Building requires cmake, make, an "arm-none-eabi" toolchain (including
newlib), and picotool (including the .cmake files;
eg. /usr/lib/cmake/picotool/*.cmake).

At the time of this writing, on Parabola GNU/Linux-libre that means:

 - make 4.4.1-2
 - cmake 3.30.3-1
 - arm-none-eabi-binutils 2.42-1
 - arm-none-eabi-gcc 14.1.0-1
 - arm-none-eabi-newlib 4.4.0.20231231-1
 - picotool 2.0.0-2

```bash
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Debug ..
make
```
# Debugging

UART:
- 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)
- `picocom --baud=115200 /dev/ttyUSB0`
- `picocom --baud=115200 /dev/ttyACM0`

- `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)
- `arm-none-eabi-gdb ./build/rp2040/cmd/sbc_harness/sbc_harness.elf`
  ```
  target extended-remote localhost:3333
  monitor reset init
  continue
  ```
  https://openocd.org/doc/html/General-Commands.html

SWD:
- https://www.raspberrypi.com/documentation/microcontrollers/debug-probe.html
- https://github.com/raspberrypi/debugprobe
- https://developer.arm.com/documentation/101451/0100/About-CMSIS-DAP

## 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) |                                  |

## UART (Universal asynchronous receiver/transmitter)

## ARM SWD (Serial Wire Debug)
- 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/

Alternative to Raspberry Pi Debug Probe:
https://oshwlab.com/wagiminator/samd11c-swd-programmer which uses
https://github.com/ataradov/free-dap instead of ARM's reference CMSIS
implementation

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

```
+-[Host PC]-------------------------+
|                                   |
|              +-----+              |
|              | GDB |              |
|              +-----+              |
|                 ^                 |
|                 | GDB Remote Serial Protocol
|                 | on localhost:3333
|                 V                 |
|            +---------+            |
|            | OpenOCD |            |
|            +---------+            |
|                 ^                 |
|                 |                 |
+-----------------|-----------------+
                USB-A
                  |
                  | ARM CMSIS-DAP protocol
                  | (a USB-based protocol)
                  |
            (micro)USB-B
       +-[Debug Probe]-------+
       |          |          |
       |          V          |
       |  +----------------+ |
       |  |     ARM's      | |
       |  |   reference    | |
       |  |   CMSIS-DAP    | |
       |  | implementation | |
       |  +----------------+ |
       |          ^          |
       |          |          |
       +----------|----------+
         SW-DP (3-pin JST-SH)
                  |
                  | ADIv5 SWD protocol
                  |
        SW-DP (3 .1" headers)
+-[SBC-Harness]---|-----------------+
|                 |                 |
| ,---------------'                 |
| |                                 |
| |  +----------------------------+ |
| |  | Cortex-M0+                 | |
| |  | +------------------------+ | |
| +--->| CoreSight ADIv5 module | | |
| |  | +------------------------+ | |
| |  +----------------------------+ |
| |                                 |
| |  +----------------------------+ |
| |  | Cortex-M0+                 | |
| |  | +------------------------+ | |
| `--->| CoreSight ADIv5 module | | |
|    | +------------------------+ | |
|    +----------------------------+ |
|                                   |
+-----------------------------------+
```

# Usage

The harness uses DHCP to acquire an IPv4 address, then serves the 9P
protocol over TCP:

 - TCP port: 564 (9P does not have a standard TCP port number, but
   this is the default port number used by most 9P-over-TCP clients,
   including the Linux kernel's v9fs driver).
 - Supported protocol versions:
   - `9P2000` (base protocol): Yes
   - `9P2000.u` (Unix extension): Yes, with Linux kernel
     architecture-"generic" errnos.  This will match the Linux kernel
     errnos on most architectures (but, as of Linux v6.7, not on
     Alpha, MIPS, PA-RISC, PowerPC, or SPARC; I am unsure whether on
     these platforms the kernel's v9fs filesystem driver will map the
     "generic" errnos to the architecture-specific errnos for you).
   - `9P2000.L` (Linux extension): No, it's an abomination and
     unlikely to ever be supported
   - `9P2000.e` (Erlang extension): No, but if you want it and ask
     nicely I'd be happy to add it (I'm not sure why you'd want it
     though).
 - Authentication: None

There are lots of 9P clients that you can use.  9P is a filesystem
protocol; and you can mount it directly with the the Linux kernel's
v9fs filesystem driver, with plan9port's `9pfuse`; or interact with it
without mounting it using the shell commands `9p` (from plan9port),
`wmiir`, `ixpc`; or interact with it without mounting it by using a
library for your programming language of choice.

Some notes on choosing a client:
 - On x86-32, the Linux kernel v9fs driver is known to drop entries
   from directory listings; I advise using 9pfuse instead of you want
   to mount it on 32-bit systems.
 - I generally like mounting it as a real filesystem, but this means
   that you only get errno errors, and the more-helpful error strings
   are discarded.
 - The sbc-harness only supports 8 concurrent connections to the 9P
   server, so while shell commands are handy for poking around, for
   real use where you're doing things in parallel you'll likely want
   to mount it or use a library that can reuse existing connections.

# Bugs/Limitations

 - Only supports 8 concurrent TCP connectsions to the 9P server (due
   to limitations in the W5500 TCP-offload chip; TODO: investigate
   using a software TCP/IP stack with the W5500 in MAC-raw mode)
 - Only supports 16 concurrent 9P requests (I wanted a static limit,
   and "connections*2" seemed reasonable)
 - Only supports IPv4, not IPv6 (due to limitations in the W5500
   TCP-offload chip; TODO: investigate upgrading to the W6100 or using
   a software TCP/IP stack with the W5500 in MAC-raw mode)