[fw/altos] / ao-tools / ao-dbg / ao-dbg.1
1 .\"
2 .\" Copyright © 2009 Keith Packard <keithp@keithp.com>
3 .\"
4 .\" This program is free software; you can redistribute it and/or modify
5 .\" it under the terms of the GNU General Public License as published by
6 .\" the Free Software Foundation; either version 2 of the License, or
7 .\" (at your option) any later version.
8 .\"
9 .\" This program is distributed in the hope that it will be useful, but
10 .\" WITHOUT ANY WARRANTY; without even the implied warranty of
12 .\" General Public License for more details.
13 .\"
14 .\" You should have received a copy of the GNU General Public License along
15 .\" with this program; if not, write to the Free Software Foundation, Inc.,
16 .\" 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
17 .\"
18 .\"
19 .TH AO-DBG 1 "ao-dbg" ""
21 ao-dbg \- hex debugger for cc1111 processors
23 .B "ao-dbg"
24 [\-t \fIcpu-type\fP]
25 [\-X \fIfrequency\fP]
26 [\-c]
27 [\-r \fIlisten-port\fP]
28 [\-Z \fIlisten-port\fP]
29 [\-s]
30 [\-S]
31 [\-p \fIprompt\fP]
32 [\-V]
33 [\-v]
34 [\-H]
35 [\-h]
36 [\-m]
37 [\-T \fItty-device\fP]
38 [\--tty \fItty-device\fP]
39 [\-D \fIaltos-device\fP]
40 [\--device \fIaltos-device\fP]
42 .I ao-dbg
43 connects to a cc1111 processor through either a suitable cc1111 board
44 or a cp2103 usb to serial converter board, using the GPIO pins
45 available on that chip. It provides an interface compatible with the
46 8051 emulator from sdcc called s51, but communicating with the real
47 chip instead of an emulation. Using a modified version of the SDCC
48 debugger (sdcdb), you can control program execution on the target
49 machine at source-level.
52 The command line options are designed to be compatible with the 8051
53 emulator so that it can be used with sdcdb. As such, they're all one letter
54 long.
55 .IP "\-t \fIcpu-type\fP"
56 The 8051 emulator can operate as one of several different chips. Oddly, the
57 real hardware cannot, so this option is ignored.
58 .IP "\-X \fIfrequency\fP"
59 Similarly, the emulator can pretend to run at an arbitrary frequency
60 which the real hardware cannot do. Ignored.
61 .IP "\-c"
62 .IP "\-s"
63 .IP "\-S"
64 .IP "\-v"
65 .IP "\-V"
66 All ignored.
67 .IP "\-r \fIlisten-port\fP, -Z \fIlisten-port\fP"
68 The emulator and sdcdb communicate through a network socket. This option
69 switches the debugger from communicating through stdin/stdout to listening
70 on a specific network port instead. Once a connection is made, the debugger
71 continues on, using that network port for command input and output. The
72 debugger uses port 9756, and attempts to connect before launching ao-dbg, so if
73 ao-dbg is listening on this port before sdcdb is started, sdcdb will end up
74 talking to the existing ao-dbg instance. That's often useful for debugging ao-dbg
75 itself.
76 .IP "\-p \fIprompt\fP"
77 This sets the command prompt to the specified string.
78 .IP "\-P"
79 This sets the command prompt to a single NUL character. This is for use by
80 sdcdb.
81 .IP "\-h"
82 This should print a usage message, but does nothing useful currently.
83 .IP "\-m"
84 This option is not present in the original 8051 emulator, and causes ao-dbg to
85 dump all commands and replies that are received from and sent to sdcdb.
86 .TP
87 \-T tty-device | --tty tty-device
88 This selects which tty device the debugger uses to communicate with
89 the target device. The special name 'BITBANG' directs ao-dbg to use
90 the cp2103 connection, otherwise this should be a usb serial port
91 connected to a suitable cc1111 debug node.
92 .TP
93 \-D AltOS-device | --device AltOS-device
94 Search for a connected device. This requires an argument of one of the
95 following forms:
96 .IP
97 TeleMetrum:2
98 .br
99 TeleMetrum
100 .br
101 2
102 .IP
103 Leaving out the product name will cause the tool to select a suitable
104 product, leaving out the serial number will cause the tool to match
105 one of the available devices.
107 Once started, ao-dbg connects to the cc1111 and then reads and
108 executes commands, either from stdin, or the nework connection to
109 sdcdb.
110 .PP
111 Unlike the command line, ao-dbg contains built-in help for each of these
112 commands, via the 'help' command. Most of the commands are available in a
113 long form and a single character short form. Below, the short form follows
114 the long form after a comma.
115 .IP "help, ? {command}"
116 Without arguments, prints a list of available commands. With an argument
117 prints more detail about the specific command
118 .IP "quit, q"
119 Terminates the application, without changing the state of the target
120 processor.
121 .IP "di [start] [end]"
122 Dumps imem (256 bytes of "internal" memory) from start to end (inclusive).
123 .IP "ds [start] [end]"
124 Dumps sprs from start to end (inclusive). Note that while most sprs are
125 visible in the global address space, some are not, so use this command
126 instead of "dx" to read them.
127 .IP "dx [start] [end]"
128 Dump external (global) memory from start to end (inclusive).
129 .IP "set, t <prefix> [start] {data ...}"
130 Store to the memory space specified by prefix where prefix is one of "xram",
131 "rom", "iram", or "sfr". Store bytes starting at start.
132 .IP "dump, d <prefix> [start] [end]"
133 Dump from the memory space specified by prefix, where prefix is one of
134 "xram", "rom", "iram" or "sfr". Dumps from start to end (inclusive).
135 .IP "file [filename]"
136 Specifies an intel-format hex file (ihx) that contains the contents of the
137 rom area loaded into the cc1111. This is used to respond to requests to dump
138 rom memory contents without getting them from the cc1111 (which is slow).
139 .IP "pc, p {address}"
140 If the address argument is given, this sets the program counter to the
141 specified value. Otherwise, the current program counter value is displayed.
142 .IP "break, b [address]"
143 Sets a breakpoint at the specified address. This uses the built-in hardware
144 breakpoint support in the cc1111. As a result, it supports no more than four
145 breakpoints at once. You must therefore use a modified version of sdcdb which
146 changes how program execution is controlled to work within this limit.
147 .IP "clear, c [address]"
148 Clear a breakpoint from the specified address.
149 .IP "run, r, go, g {start} {stop}"
150 Resumes execution of the program. If the start argument is present, then it
151 begins at that address, otherwise it continues running at the current pc. If
152 a stop argument is present, then a temporary breakpoint is set at that
153 address. This temporary breakpoint will be removed when execution hits it.
154 .IP "next, n"
155 Step one instruction. In the original s51 program this would ignore
156 subroutines, but as sdcdb doesn't require this functionality, it's not
157 available here.
158 .IP "step, s"
159 Step one instruction.
160 .IP "load, l [filename]"
161 This is not implemented, but it is supposed to load a hex file into flash.
162 Use the ccload program instead.
163 .IP "halt, h"
164 Halt the processor. This is the only command which can be sent while the
165 program is running. It is ignored at other times.
166 .IP "reset, res"
167 Reset the processor. This pulls the reset pin low and re-enables debug mode.
168 Check the cc1111 documentation to see precisely what this does.
169 .IP "status"
170 This dumps the cc1111 debug status register.
171 .IP "info, i breakpoints, b"
172 List the current breakpoints.
173 .IP "info, i help, ?"
174 List the things you can get info on.
175 .IP "stop"
176 This doesn't do anything and is present only to retain compatibility with
177 the original 8051 emulator.
179 .PP
180 While the original purpose for this program was to connect the source
181 debugger with the hardware, it can also be used as a low-level hex debugger
182 all on its own. In particular, all of the cc1111 peripherals can be
183 manipulated directly from the ao-dbg command line.
184 .IP "Starting ao-dbg"
185 First ensure that the target cc1111 device and intermediate cp2103 or
186 cc111 board are all hooked up correctly.
187 .IP
188 $ ao-dbg
189 .br
190 Welcome to the non-simulated processor
191 .br
192 > status
193 .br
194         CPU halted
195 .br
196         Halted by debug command
197 .br
198 >
199 .IP "Turning on LEDs"
200 Two of the cc1111 GPIO pins, P1_0 and P1_1 are capable of driving external
201 LEDs. To control these, set the Port 1 direction bits to make these output
202 pins and then change the Port 1 data to set them high or low:
203 .IP
204 > set sfr 0xfe 0x02     # set P1DIR to 0x2
205 .br
206 > set sfr 0x90 0x02     # set P1_1 to high
207 .br
208 > set sfr 0x90 0x00     # set P1_1 to low
209 .IP "Reading the A/D converters"
210 The six A/D converter inputs can each be connected to any of the P0 pins,
211 ground, the A/D voltage refernece, an internal temperature sensor or VDD/3.
212 To read one of these values, select an A/D converter to use then start the
213 conversion process. The cc1111 manual has the table for selecting the input
214 on page 144.
215 .IP
216 To configure one of the P0 pins for use by the A/D unit, we program the
217 ADCCFG register, setting the bits in that which match the pins desired:
218 .IP
219 > set sfr 0xf2 0x3f     # enable all 6 A/D inputs
220 .IP
221 To trigger a single conversion, we ask the A/D unit to perform an 'extra'
222 conversion, which means to do a single conversion not a whole sequence of
223 conversions. This is controlled by the ADCCON3 register at 0xB6:
224 .IP
225 > set sfr 0xb6 0xb2     # sample P0_2 using 12 bits of precision
226 .br
227 > ds 0xba 0xbb          # dump the ADC data low and high regs
228 .br
229 > set sfr 0xb6 0xbe     # sample internal temperature sensor
230 .br
231 > ds 0xba 0xbb          # dump the ADC data low and high regs
232 .SH "SEE ALSO"
233 sdcdb(1), ccload(1)
235 Keith Packard