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