1 | .. SPDX-License-Identifier: CC-BY-SA-4.0 |
---|
2 | |
---|
3 | .. Copyright (C) 2019 Vijay Kumar Banerjee |
---|
4 | |
---|
5 | .. _BSP_arm_beagle: |
---|
6 | .. _BSP_arm_beagleboardorig: |
---|
7 | .. _BSP_arm_beagleboardxm: |
---|
8 | .. _BSP_arm_beagleboneblack: |
---|
9 | .. _BSP_arm_beaglebonewhite: |
---|
10 | |
---|
11 | beagle |
---|
12 | ====== |
---|
13 | |
---|
14 | This BSP supports four variants, `beagleboardorig`, `beagleboardxm`, |
---|
15 | `beaglebonewhite` and `beagleboneblack`. The basic hardware initialization is |
---|
16 | not performed by the BSP. A boot loader with device tree support must be used |
---|
17 | to start the BSP, e.g., U-Boot. |
---|
18 | |
---|
19 | TODO(These drivers are present but not documented yet): |
---|
20 | |
---|
21 | * Clock driver. |
---|
22 | * Network Interface Driver. |
---|
23 | * SDcard driver. |
---|
24 | * GPIO Driver. |
---|
25 | * Console driver. |
---|
26 | * PWM Driver. |
---|
27 | * RTC driver. |
---|
28 | |
---|
29 | Boot via U-Boot |
---|
30 | --------------- |
---|
31 | To boot via uboot, the ELF must be converted to a U-Boot image like below: |
---|
32 | |
---|
33 | .. code-block:: none |
---|
34 | |
---|
35 | arm-rtems@rtems-ver-major@-objcopy hello.exe -O binary app.bin |
---|
36 | gzip -9 app.bin |
---|
37 | mkimage -A arm -O linux -T kernel -a 0x80000000 -e 0x80000000 -n RTEMS -d app.bin.gz rtems-app.img |
---|
38 | |
---|
39 | Getting the Device Tree Blob |
---|
40 | ---------------------------- |
---|
41 | |
---|
42 | The Device Tree Blob (DTB) is needed to load the device tree while starting up |
---|
43 | the kernel. We build the dtb from the FreeBSD source matching the commit hash |
---|
44 | from the libbsd HEAD of freebsd-org. For example if the HEAD is at |
---|
45 | "19a6ceb89dbacf74697d493e48c388767126d418" |
---|
46 | Then the right Device Tree Source (DTS) file is: |
---|
47 | https://github.com/freebsd/freebsd/blob/19a6ceb89dbacf74697d493e48c388767126d418/sys/gnu/dts/arm/am335x-boneblack.dts |
---|
48 | |
---|
49 | Please refer to the :ref:`DeviceTree` to know more about building and applying |
---|
50 | the Device Trees. |
---|
51 | |
---|
52 | Writing the uEnv.txt file |
---|
53 | ------------------------- |
---|
54 | |
---|
55 | The uEnv.txt file is needed to set any environment variable before the kernel is |
---|
56 | loaded. Each line is a u-boot command that the uboot will execute during start |
---|
57 | up. |
---|
58 | |
---|
59 | Add the following to a file named uEnv.txt: |
---|
60 | |
---|
61 | .. code-block:: none |
---|
62 | |
---|
63 | setenv bootdelay 5 |
---|
64 | uenvcmd=run boot |
---|
65 | boot=fatload mmc 0 0x80800000 rtems-app.img ; fatload mmc 0 0x88000000 am335x-boneblack.dtb ; bootm 0x80800000 - 0x88000000 |
---|
66 | |
---|
67 | I2C Driver |
---|
68 | ---------- |
---|
69 | |
---|
70 | The Beagle i2c initialization is based on the device tree. To initialize a i2c |
---|
71 | device, the user has to enable the respective node in the device tree using |
---|
72 | overlays. |
---|
73 | |
---|
74 | For registering an I2C device with a custom path (say `/dev/i2c-eeprom`) an |
---|
75 | overlay has to be provided. The overlay must add an additional attribute |
---|
76 | `rtems,path` with the custom path as value to the respective i2c node. |
---|
77 | |
---|
78 | For example, |
---|
79 | |
---|
80 | .. code-block:: none |
---|
81 | |
---|
82 | /dts-v1/; |
---|
83 | |
---|
84 | / { |
---|
85 | compatible = "ti,am335x-bone-black", "ti,am335x-bone", "ti,am33xx"; |
---|
86 | |
---|
87 | fragment@0 { |
---|
88 | target = <0xffffffff>; |
---|
89 | |
---|
90 | __overlay__ { |
---|
91 | compatible = "rtems,bsp-i2c", "ti,omap4-i2c"; |
---|
92 | status = "okay"; |
---|
93 | rtems,path = "/dev/i2c-eeprom"; |
---|
94 | }; |
---|
95 | }; |
---|
96 | |
---|
97 | __fixups__ { |
---|
98 | i2c0 = "/fragment@0:target:0"; |
---|
99 | }; |
---|
100 | }; |
---|
101 | |
---|
102 | The above example registers a custom path `/dev/i2c-eeprom` for i2c0. |
---|
103 | |
---|
104 | SPI Driver |
---|
105 | ---------- |
---|
106 | |
---|
107 | The SPI device `/dev/spi-0` can be registered with ``bbb_register_spi_0()`` |
---|
108 | |
---|
109 | For registering with a custom path, the ``bsp_register_spi()`` can be used. |
---|
110 | |
---|
111 | The function prototype is given below: |
---|
112 | |
---|
113 | .. code-block:: c |
---|
114 | |
---|
115 | rtems_status_code bsp_register_spi( |
---|
116 | const char *bus_path, |
---|
117 | uintptr_t register_base, |
---|
118 | rtems_vector_number irq |
---|
119 | ); |
---|
120 | |
---|
121 | Debugging using libdebugger |
---|
122 | --------------------------- |
---|
123 | |
---|
124 | RTEMS's ``libdebugger`` requires the ARM debug resources be enabled for it to |
---|
125 | work. The TI SOC used on the ``beagleboneblack`` board provides no access for |
---|
126 | software to the ARM defined debug enable signal ``DBGEN``. The signal is |
---|
127 | negated on power up locking software out of the ARM debug hardware. The signal |
---|
128 | can only be accessed via the JTAG interface. |
---|
129 | |
---|
130 | The ``beagleboneblack`` BSP provides a low level solution to enable the |
---|
131 | ``DBGEN`` signal via the JTAG interface if the board has the following |
---|
132 | hardware modification installed. The modification requires the addition of two |
---|
133 | small wire links soldered to the pads of the JTAG connect on the underside of |
---|
134 | the board. A small length of fine wire, a fine tip soldering iron, some good |
---|
135 | quality solder and a pair of fine tip pliers are required. If you are new to |
---|
136 | soldering I suggest you find something to practice on first. |
---|
137 | |
---|
138 | The modification details and software driver can be found in the BSP in the |
---|
139 | file ``bsps/arm/beagle/start/bspdebug.c``. The driver is automatically run |
---|
140 | and the ``DBGEN`` is asserted via JTAG when ``libdebugger`` is started. |
---|
141 | |
---|
142 | The modification is: |
---|
143 | |
---|
144 | 1. Locate P2 on the bottom side of the board. It is the JTAG connector |
---|
145 | pads. If you look at the underside of the board with the SD card holder to |
---|
146 | the right the pads are top center left. There are 20 pads in two |
---|
147 | columns. The pads are numbered 1 at the top left then 2 top right, 3 is |
---|
148 | second top on the left, 4 is second top to the right, then the pin number |
---|
149 | increments as you move left then right down the pads. |
---|
150 | |
---|
151 | 2. Connect P2 to P5. |
---|
152 | |
---|
153 | 3. Connect P7 to P13. |
---|
154 | |
---|
155 | The resulting wiring is: |
---|
156 | |
---|
157 | .. code-block:: none |
---|
158 | |
---|
159 | 1 === /--=== 2 |
---|
160 | 3 === | === 4 |
---|
161 | 5 ===--/ === 6 |
---|
162 | 7 ===--\ === 8 |
---|
163 | 9 === | === 10 |
---|
164 | 11 === | === 12 |
---|
165 | 13 ===--/ === 14 |
---|
166 | 15 === === 16 |
---|
167 | 17 === === 18 |
---|
168 | 19 === === 20 |
---|
169 | |
---|
170 | .. figure:: ../../../images/user/bbb-p2-debug-mod.jpg |
---|
171 | :width: 50% |
---|
172 | :align: center |
---|
173 | :alt: BeagleBone Black JTAG Hardware Modification |
---|
174 | |
---|
175 | BeagleBone Black JTAG Hardware Modification |
---|
176 | |
---|
177 | If ``libdebugger`` fails to detect the registers open the ``bspdebug.c`` |
---|
178 | source and change ``has_tdo`` to ``1``, save then rebuild and install the |
---|
179 | BSP. This will turn on an internal feeback to check the JTAG logic. Discard |
---|
180 | the edit once the hardware is working. |
---|
181 | |
---|
182 | Debugging Beagle Bone Black using a JTAG debugger and gdb |
---|
183 | --------------------------------------------------------- |
---|
184 | |
---|
185 | Debugging a Beagle Bone Black (or variants) is also possible using a hardware |
---|
186 | JTAG debugger. The JTAG is available via P2. The footprint is for an ARM 20 pin |
---|
187 | cTI connector. That connector should be used, if it is necessary to have access |
---|
188 | to commercially available adapters. |
---|
189 | |
---|
190 | For hand-made cables and adapters a standard 1.27mm pitch header and a 0.635mm |
---|
191 | ribbon cable can be much cheaper. But note that even if it looks compatible, |
---|
192 | it's not the same pin out as a ARM Cortex 20 pin connector! |
---|
193 | |
---|
194 | A lot of JTAG adapters that are working together with OpenOCD will work. There |
---|
195 | are also commercially available systems (like Segger J-Link) that work well with |
---|
196 | the Beagle. Note that the JTAG debugger has to be compatible with ARM Cortex A8. |
---|
197 | Cortex M only debuggers (like the Segger J-Link Edu Mini) won't work. |
---|
198 | |
---|
199 | If the debugger offers a gdb server (like OpenOCD or Segger J-Link) the |
---|
200 | following gdb start script can be used: |
---|
201 | |
---|
202 | .. code-block:: none |
---|
203 | |
---|
204 | define reset |
---|
205 | echo -- Reset target and wait for U-Boot to start kernel.\n |
---|
206 | monitor reset |
---|
207 | # RTEMS U-Boot starts at this address. |
---|
208 | tbreak *0x80000000 |
---|
209 | # Linux starts here. |
---|
210 | tbreak *0x82000000 |
---|
211 | continue |
---|
212 | |
---|
213 | echo -- Disable watchdog.\n |
---|
214 | set *(uint32_t*)0x44e35048=0xAAAA |
---|
215 | while (*(uint32_t*)0x44e35034 != 0) |
---|
216 | end |
---|
217 | set *(uint32_t*)0x44e35048=0x5555 |
---|
218 | while (*(uint32_t*)0x44e35034 != 0) |
---|
219 | end |
---|
220 | |
---|
221 | echo -- Overwrite kernel with application to debug.\n |
---|
222 | load |
---|
223 | end |
---|
224 | |
---|
225 | target remote :2331 |
---|
226 | |
---|
227 | Note that you might have to replace the ``monitor reset`` by some other command |
---|
228 | that resets the target using your specific debugger. You also have to replace |
---|
229 | the ``target remote :2331`` to match the port of your gdb server. |
---|
230 | |
---|
231 | The script expects that the Beagle Bone Black starts some application from an SD |
---|
232 | card or from eMMC. It defines a ``reset`` command that does the following: |
---|
233 | |
---|
234 | * reset the target |
---|
235 | * let U-Boot run, initialize the base system, load an FDT and an application |
---|
236 | * break at the application entry point |
---|
237 | * disable the watchdog |
---|
238 | * overwrite the application that has been loaded by U-Boot with the application |
---|
239 | provided as an command line argument to gdb |
---|
240 | |
---|
241 | This method has the advantage that the application is executed in nearly the |
---|
242 | same environment like it would be executed if loaded by U-Boot directly (except |
---|
243 | for the watchdog). |
---|