af7f62717d0ce70af6587b9206249c3a6d7fa8c2
[bbg-swd.git] / README
1 BeagleBoneGreen SWD - a practical tool for computing freedom
2
3                                                         Version 0.03
4                                                           2018-03-22
5                                                         Niibe Yutaka
6                                              Flying Stone Technology
7
8 BeagleBoneGreen SWD
9 ===================
10
11 BeagleBoneGreen SWD (BBG-SWD) is a tool to control SWD protocol by
12 BeagleBoneGreen or PocketBeagle.
13
14
15 Note for release 0.03
16 =====================
17
18 The patch is for OpenOCD 0.10.0.
19
20 The BBG-SWD driver for OpenOCD is by a patch:
21
22         0001-jtag-drivers-bbg-swd-New-SWD-driver.patch
23
24 The BBG-SWD driver is ready for use.  It is tested with FST-01 (STM32F103),
25 FSM-55 (STM32F030) and prototype of FS-BB48 (KL27Z256).
26
27 Use of "bone-kernel" is assumed for UIO user space PRUSS driver.
28
29 It is also tested with PocketBeagle.
30
31
32 Future Works
33 ============
34
35 It would be good to support different speed for communication.
36 Now, it is fixed to 1000kHz.
37
38
39 The purpose
40 ===========
41
42 It gives (back) us the control for our computing (freedom), again.
43
44
45 Pins for SWD access
46 ===================
47
48 For BBG
49 -------
50
51 SWD-DIO         P8_11
52 SWD-CLK         P8_12
53 SRST            P8_15
54
55 Pinmux Configuration
56
57     # echo gpio >/sys/devices/platform/ocp/ocp:P8_11_pinmux/state
58     # echo gpio >/sys/devices/platform/ocp/ocp:P8_12_pinmux/state
59     # echo gpio_pu >/sys/devices/platform/ocp/ocp:P8_15_pinmux/state
60
61
62 For PocketBeagle
63 ----------------
64
65 SWD-DIO         P2_33
66 SWD-CLK         P2_24
67 SRST            P2_18
68 3V3             P2_23
69 GND             P2_21
70
71 Pinmux Configuration
72
73     # echo gpio >/sys/devices/platform/ocp/ocp:P2_24_pinmux/state
74     # echo gpio >/sys/devices/platform/ocp/ocp:P2_33_pinmux/state
75     # echo gpio_pu >/sys/devices/platform/ocp/ocp:P2_18_pinmux/state
76
77
78
79 The methodology
80 ===============
81
82 It takes advantage of using PRUSS (Programmable Realtime Unit
83 SubSytem) on the processor, so that the SWD communication could be
84 reliable, accurate and fast.
85
86 It assumes use of PRUSSDRV user space library with UIO user space
87 PRUSS driver.
88
89 I use "bone-kernel" for that.
90
91
92 Software License
93 ================
94
95 The program pru-swd.p is distributed under GPLv3+.
96
97 The OpenOCD patch  is under GPLv2+.
98
99
100 Patch for OpenOCD
101 =================
102
103 The patch is: 
104         0001-Add-new-SWD-driver-bbg-swd.patch
105
106 You can configure BBG-SWD driver by the --enable-bbg-swd option.
107
108     ./configure --enable-bbg-swd
109
110 You can use it with a configuration like:
111
112 -------------------------- File: bbg-swd.cfg
113 interface bbg-swd
114 transport select swd
115 --------------------------
116
117 The invacatio of command is something like this:
118
119     $ openocd -f  bbg-swd.cfg -f target/stm32f1x.cfg
120
121 The above is the case for FST-01.
122
123
124 For FS-BB48 (which uses Freescale's KL27Z256), I use following configuration.
125
126 -------------------------- File: kl27-bbg-swd.cfg
127 interface bbg-swd
128 set CHIPNAME kl27
129 source [find target/klx.cfg]
130 reset_config srst_only separate srst_nogate srst_push_pull connect_assert_srst
131 --------------------------
132
133
134 Request-Response
135 ================
136
137 FORMAT:
138   Request:
139         1-byte: CMD
140         arg...
141
142   Response:
143         value...
144
145 Last three bits are valid for CMD.
146
147         HALT            0
148         BLINK           1
149         GPIO_OUT        2
150         GPIO_IN         3
151         SIG_IDLE        4
152         SIG_GEN         5
153         READ_REG        6
154         WRITE_REG       7
155
156
157 HALT(): none
158         finish execution of PRU
159
160 BLINK(delay, counts, led-bit): none
161         Blink LED
162
163 SIG_IDLE(count): none
164         submit idle(=LOW) for COUNT cycles, strobing SWD-CLK
165
166 SIG_GEN(bit-len, data...): none
167         submit signal pattern to SWD-DIO, strobing SWD-CLK
168
169 READ_REG(cmd): parity-and-ack, value
170         execute SWD read register transaction
171
172 WRITE_REG(cmd,value): ack
173         execute SWD write register transaction
174
175 GPIO_OUT(bit, value): none
176         control GPIO signal directly, output
177
178 GPIO_IN(): value
179         control GPIO signal directly, input
180
181
182 Enjoy,
183 --