1 |
%% -*-texinfo-*- |
2 |
\input texinfo |
3 |
@c |
4 |
@c $Id: simulavr.texi,v 1.18 2002/11/14 06:54:22 troth Exp $ |
5 |
@c |
6 |
@c %**start of header |
7 |
@setfilename simulavr.info |
8 |
@settitle Simulavr |
9 |
@c %**end of header |
10 |
|
11 |
@include version.texi |
12 |
|
13 |
@c This is a dir.info fragment to support semi-automated addition of |
14 |
@c manuals to an info tree. |
15 |
@dircategory AVR Programming & development tools. |
16 |
@direntry |
17 |
* Simulavr: (simulavr). A simulator for Atmel AVR microcontrollers. |
18 |
@end direntry |
19 |
|
20 |
@ifinfo |
21 |
This file documents the simulavr program. |
22 |
|
23 |
For simulavr version @value{VERSION}, @value{UPDATED}. |
24 |
|
25 |
Copyright @copyright{} 2001, 2002 Theodore A. Roth |
26 |
|
27 |
Permission is granted to make and distribute verbatim copies of |
28 |
this manual provided the copyright notice and this permission notice |
29 |
are preserved on all copies. |
30 |
|
31 |
@ignore |
32 |
Permission is granted to process this file through TeX and print the |
33 |
results, provided the printed document carries copying permission |
34 |
notice identical to this one except for the removal of this paragraph |
35 |
(this paragraph not being relevant to the printed manual). |
36 |
|
37 |
@end ignore |
38 |
Permission is granted to copy and distribute modified versions of this |
39 |
manual under the conditions for verbatim copying, provided that the entire |
40 |
resulting derived work is distributed under the terms of a permission |
41 |
notice identical to this one. |
42 |
|
43 |
Permission is granted to copy and distribute translations of this manual |
44 |
into another language, under the above conditions for modified versions, |
45 |
except that this permission notice may be stated in a translation approved |
46 |
by the Free Software Foundation. |
47 |
@end ifinfo |
48 |
|
49 |
@titlepage |
50 |
@title Simulavr |
51 |
@subtitle A simulator for the Atmel AVR family of microcontrollers. |
52 |
@subtitle For simulavr version @value{VERSION}, @value{UPDATED}. |
53 |
@author by Theodore A. Roth |
54 |
|
55 |
@page |
56 |
@hfill Send bugs and comments on Simulavr to@* |
57 |
@hfill @w{@email{Simulavr-devel@@mail.freesoftware.fsf.org}} |
58 |
@vskip 0pt plus 1filll |
59 |
Copyright @copyright{} 2001, 2002 Theodore A. Roth |
60 |
@sp 2 |
61 |
Permission is granted to make and distribute verbatim copies of |
62 |
this manual provided the copyright notice and this permission notice |
63 |
are preserved on all copies. |
64 |
|
65 |
Permission is granted to copy and distribute modified versions of this |
66 |
manual under the conditions for verbatim copying, provided that the entire |
67 |
resulting derived work is distributed under the terms of a permission |
68 |
notice identical to this one. |
69 |
|
70 |
Permission is granted to copy and distribute translations of this manual |
71 |
into another language, under the above conditions for modified versions, |
72 |
except that this permission notice may be stated in a translation approved |
73 |
by the Free Software Foundation. |
74 |
@end titlepage |
75 |
|
76 |
@comment @shortcontents |
77 |
@contents |
78 |
|
79 |
@c |
80 |
@c Top Node |
81 |
@c |
82 |
@node Top, Introduction, (dir), (dir) |
83 |
@comment node-name, next, previous, up |
84 |
|
85 |
@ifinfo |
86 |
This file documents the simulavr program for simulating Atmel |
87 |
AVR microcontrollers. |
88 |
|
89 |
For simulavr version @value{VERSION}, @value{UPDATED}. |
90 |
@end ifinfo |
91 |
|
92 |
@menu |
93 |
* Introduction:: What is simulavr? |
94 |
* Invoking:: How to run simulavr |
95 |
* Using with GDB:: How to use simulavr with gdb |
96 |
* Display Coprocesses:: How to display the processors state |
97 |
* Internals:: Developing simulavr |
98 |
* Problems:: Reporting bugs |
99 |
* Concept Index:: |
100 |
@end menu |
101 |
|
102 |
@c |
103 |
@c Introduction |
104 |
@c |
105 |
@node Introduction, Invoking, Top, Top |
106 |
@comment node-name, next, previous, up |
107 |
@chapter Introduction: What is simulavr? |
108 |
@cindex introduction |
109 |
|
110 |
@quotation |
111 |
It's just a model. |
112 |
@sp 1 |
113 |
--- Monty Python |
114 |
@end quotation |
115 |
@sp 1 |
116 |
|
117 |
The Simulavr program is a simulator for the Atmel AVR family of |
118 |
microcontrollers. Simulavr can be used either standalone or as a remote |
119 |
target for gdb. When used in gdbserver mode, the simulator is used as a |
120 |
backend so that gdb can be used as a source level debugger for AVR |
121 |
programs. |
122 |
|
123 |
The official website for Simulavr is |
124 |
@uref{http://savannah.gnu.org/projects/simulavr/}. |
125 |
|
126 |
Because it is protected by the GNU General Public License, users are |
127 |
free to share and change it. |
128 |
|
129 |
Simulavr was written by Theodore A. Roth |
130 |
|
131 |
@c |
132 |
@c Invoking |
133 |
@c |
134 |
@node Invoking, Using with GDB, Introduction, Top |
135 |
@comment node-name, next, previous, up |
136 |
@chapter Invoking Simulavr |
137 |
@cindex invoking |
138 |
@cindex running |
139 |
|
140 |
The format for running the simulavr program is: |
141 |
|
142 |
@example |
143 |
simulavr @var{options} @dots{} [flash_image] |
144 |
@end example |
145 |
|
146 |
If the optional @file{flash_image} file is supplied, it will be loaded |
147 |
into the flash program memory space of the virtual device. |
148 |
|
149 |
@menu |
150 |
* Aliasing:: Simplifying invokation by aliasing. |
151 |
* Options:: Command line options for simulavr. |
152 |
@end menu |
153 |
|
154 |
@c |
155 |
@c Aliasing |
156 |
@c |
157 |
@node Aliasing, Options, Invoking, Invoking |
158 |
@comment node-name, next, previous, up |
159 |
@section Aliasing |
160 |
@cindex aliasing |
161 |
@cindex symbolic linking |
162 |
|
163 |
On most systems, if the simulavr executable is renamed to the name of an |
164 |
available device, it can be started without specifying the device |
165 |
type. The easiest way to achieve this is to create symbolic links for |
166 |
all the supported devices which point to the simulavr executable. For |
167 |
instance, this command will create a sym link for the at90s8515 device |
168 |
on a Unix system: |
169 |
|
170 |
@example |
171 |
ln -s simulavr at90s8515 |
172 |
@end example |
173 |
|
174 |
Once the links have been created, the following two commands are |
175 |
equivalent: |
176 |
|
177 |
@example |
178 |
simulavr -d at90s8515 myprog.bin |
179 |
at90s8515 myprog.bin |
180 |
@end example |
181 |
|
182 |
@c |
183 |
@c Options |
184 |
@c |
185 |
@node Options, , Aliasing, Invoking |
186 |
@comment node-name, next, previous, up |
187 |
@section Options |
188 |
@cindex options |
189 |
|
190 |
@noindent |
191 |
simulavr supports the following options: |
192 |
|
193 |
@table @code |
194 |
@cindex @code{--help} |
195 |
@item --help |
196 |
@itemx -h |
197 |
Print an informative help message describing the options and available |
198 |
device types, then exit. |
199 |
|
200 |
@cindex @code{--debug} |
201 |
@item --debug |
202 |
@itemx -D |
203 |
Print assembly instruction mnemonics and program counter (@samp{PC}) to |
204 |
output as device program is running. |
205 |
|
206 |
@cindex @code{--version} |
207 |
@item --version |
208 |
@itemx -v |
209 |
Print out the version number and exit. |
210 |
|
211 |
@cindex @code{--gdbserver} |
212 |
@item --gdbserver |
213 |
@itemx -g |
214 |
Run as a gdbserver process. |
215 |
|
216 |
@cindex @code{--gdb-debug} |
217 |
@item --gdb-debug |
218 |
@itemx -G |
219 |
Print out messages for debugging the gdb remote serial protocol interface. |
220 |
|
221 |
@cindex @code{--port} |
222 |
@item --port=@var{port} |
223 |
@itemx -p |
224 |
Listen for gdb connection on TCP port. If not specified, a default will |
225 |
be used. Run @samp{simulavr --help} to see what the default is. This |
226 |
option is ignored if the @option{--gdbserver} is not specified. |
227 |
|
228 |
@cindex @code{--device=@var{dev}} |
229 |
@item --device=@var{dev} |
230 |
@itemx -d |
231 |
Specify device type. The device types available for use with a specific |
232 |
version of simulavr can be obtained using the @option{--help} option. |
233 |
|
234 |
@cindex @code{--eeprom-image=@var{file}} |
235 |
@item --eeprom-image=@var{img} |
236 |
@itemx -e |
237 |
Specify an optional eeprom image file to be loaded into the device's |
238 |
eeprom memory space. |
239 |
|
240 |
@cindex @code{--eeprom-type=@var{type}} |
241 |
@item --eeprom-type=@var{type} |
242 |
@itemx -E |
243 |
Specify the type of the eeprom image file. If not specified, the default |
244 |
is binary. |
245 |
|
246 |
@cindex @code{--flash-type=@var{type}} |
247 |
@item --flash-type=@var{type} |
248 |
@itemx -F |
249 |
Specify the type of the flash image file. If not specified, the default |
250 |
is binary. |
251 |
|
252 |
@cindex @code{--list-devices} |
253 |
@item --list-devices |
254 |
@itemx -L |
255 |
Prints a list of supported devices to stdout and exits. |
256 |
|
257 |
@cindex @code{--disp-prog} |
258 |
@item --disp-prog=@var{prog} |
259 |
@itemx -P |
260 |
Specify a program to be used to display register and memory information |
261 |
in real time as a child process. The display program can also be |
262 |
specified by setting the @code{SIM_DISP_PROG} environment variable. |
263 |
|
264 |
@cindex @code{--without-xterm} |
265 |
@item --without-xterm |
266 |
@itemx -X |
267 |
Don't start display coprocess program in an xterm. This is useful if |
268 |
the display coprocess supplies it's own window for input and output, |
269 |
such as a process which uses a GUI. |
270 |
|
271 |
@cindex @code{--core-dump} |
272 |
@item --core-dump |
273 |
@itemx -C |
274 |
Dump a core memory image to file on exit. This isn't as useful as it |
275 |
sounds. The display coprocess mechanism is much more informative. |
276 |
|
277 |
@end table |
278 |
|
279 |
@c |
280 |
@c Using with GDB |
281 |
@c |
282 |
@node Using with GDB, Display Coprocesses, Invoking, Top |
283 |
@comment node-name, next, previous, up |
284 |
@chapter Using with GDB |
285 |
@cindex gdb |
286 |
@cindex gdbserver |
287 |
|
288 |
If you want to use gdb as a source-level debugger with |
289 |
simulavr running as a remote target, start simulavr with the |
290 |
@option{--gdbserver} or @option{-g} option. This will put simulavr |
291 |
into gdbserver mode. simulavr will then act as a TCP server |
292 |
program on the localhost listening for a connection from gdb. |
293 |
|
294 |
Once simulavr has accepted a connection from gdb, the two programs |
295 |
communicate via gdb's remote serial protocol (@pxref{Top, GDB Remote |
296 |
Serial Protocol, Protocol, gdb, Debugging with GDB}). |
297 |
|
298 |
Here's how you would start up simulavr in gdbserver mode: |
299 |
|
300 |
@example |
301 |
@cartouche |
302 |
$ simulavr -d at90s8515 -g |
303 |
@end cartouche |
304 |
@end example |
305 |
|
306 |
Here's a sample gdb session showing what to do on the gdb |
307 |
side to get gdb to talk to simulavr: |
308 |
|
309 |
@example |
310 |
@cartouche |
311 |
This GDB was configured as "--host=i686-pc-linux-gnu --target=avr". |
312 |
(gdb) file demo_kr.elf |
313 |
Reading symbols from demo_kr.elf...done. |
314 |
(gdb) target remote localhost:1212 |
315 |
Remote debugging using localhost:1212 |
316 |
0x0 in .__start_of_init__ () |
317 |
(gdb) load |
318 |
Loading section .text, size 0x76 lma 0x0 |
319 |
Start address 0x0 , load size 118 |
320 |
Transfer rate: 944 bits in <1 sec, 29 bytes/write. |
321 |
(gdb) break main |
322 |
Breakpoint 1 at 0x6e: file demo_kr.c, line 17. |
323 |
(gdb) continue |
324 |
Continuing. |
325 |
|
326 |
Breakpoint 1, main () at demo_kr.c:17 |
327 |
17 sbi(DDRC, ( |
328 |
(gdb) quit |
329 |
The program is running. Exit anyway? (y or n) y |
330 |
@end cartouche |
331 |
@end example |
332 |
|
333 |
Notice that simulavr knew nothing about the program to debug when it |
334 |
was started. Gdb was told which file to debug with the @samp{file} |
335 |
command. After gdb has read in the program and connected to simulavr, |
336 |
the program's instructions are downloaded into the simulator via the |
337 |
@samp{load} command. The @samp{load} command is not necessary if |
338 |
simulavr already has the program loaded into it's flash memory area. It |
339 |
is ok to issue multiple @samp{load} commands. |
340 |
|
341 |
Also, notice that no @samp{run} command was given to gdb. Gdb assumes |
342 |
that the simulator has started and is ready to continue. Giving gdb the |
343 |
@samp{run} command, will cause it to stop the current debug session and |
344 |
start a new one, which is not likely to be what you want to do. |
345 |
|
346 |
When specifying the remote target to connect to, it is sufficient to |
347 |
write ``target remote :1212'' instead of ``target remote :1212''. |
348 |
|
349 |
Hitting @kbd{CTRL-c} in gdb can be used to interrupt the simulator while it is |
350 |
processing instructions and return control back to gdb. This is most |
351 |
useful when gdb is waiting for a response from the simulator and the |
352 |
program running in the simulator is in an infinite loop. |
353 |
|
354 |
Issuing a @samp{signal SIGxxx} command from gdb will send the signal to |
355 |
the simulator via a @i{continue with signal} packet. The simulator will |
356 |
process and interpret the signal, but will not pass it on to the AVR |
357 |
program running in the simulator since it really makes no sense to do |
358 |
so. In some circumstances, it may make sense to use the gdb signal |
359 |
mechanism as a way to initiate some sort of external stimulus to be |
360 |
passed on to the virtual hardware system of the simulator. Signals from |
361 |
gdb which are processed have the following meanings: |
362 |
|
363 |
@table @code |
364 |
@cindex SIGHUP, from gdb |
365 |
@item SIGHUP |
366 |
Initiate a reset of the simulator. (Simulates a hardware reset). |
367 |
|
368 |
@end table |
369 |
|
370 |
@c |
371 |
@c GDB Hints |
372 |
@c |
373 |
@menu |
374 |
* GDB Hints:: |
375 |
* Building GDB:: |
376 |
@end menu |
377 |
|
378 |
@node GDB Hints, Building GDB, Using with GDB, Using with GDB |
379 |
@comment node-name, next, previous, up |
380 |
@section GDB Hints |
381 |
@cindex gdb, hints |
382 |
|
383 |
Since debugging an AVR program with gdb requires gdb to connect to a |
384 |
remote target (either simulavr or some other debugging tool, such as |
385 |
avarice), a series of commands must be issued every time gdb is started. |
386 |
The easiest way around this is to put the commands into a |
387 |
@file{.gdbinit} file in the project directory. The following example is |
388 |
from a @file{.gdbinit} which I use for many projects. |
389 |
|
390 |
@example |
391 |
@cartouche |
392 |
|
393 |
## Print out structures in a sane way |
394 |
|
395 |
echo (gdb) set print pretty |
396 |
set print pretty |
397 |
|
398 |
## Use this for debugging the remote protocol. (Don't use unless |
399 |
## debugging simulavr or avr-gdb) |
400 |
|
401 |
#echo (gdb) set debug remote 1\n |
402 |
#set debug remote 1 |
403 |
|
404 |
## If you don't want specify the program to debug when invoking gdb, |
405 |
## you can tell gdb to read it in here. The file should be an elf file |
406 |
## compiled with debugging information (-g for C files and -gstabs for |
407 |
## asm files). |
408 |
|
409 |
#echo (gdb) file myprog.elf\n |
410 |
#file myprog.elf |
411 |
|
412 |
## Connect to the remote target via a TCP socket on host:port. |
413 |
|
414 |
echo (gdb) target remote localhost:1212\n |
415 |
target remote localhost:1212 |
416 |
|
417 |
## If you are using simulavr as the remote target, this will upload |
418 |
## the program into flash memory for you. |
419 |
|
420 |
echo (gdb) load\n |
421 |
load |
422 |
|
423 |
## Set a break point at the beginning of main(). |
424 |
|
425 |
echo (gdb) break main\n |
426 |
break main |
427 |
|
428 |
## Run the program up to the first break point. Gdb's `run` command |
429 |
## does not work when using a remote target, must use continue. |
430 |
|
431 |
echo (gdb) continue\n |
432 |
continue |
433 |
|
434 |
@end cartouche |
435 |
@end example |
436 |
|
437 |
As you can see, I @code{echo} every command so I can see what gdb has |
438 |
done when it runs the commands in the @file{.gdbinit} file. |
439 |
|
440 |
@c |
441 |
@c Building GDB for AVR |
442 |
@c |
443 |
@node Building GDB, , GDB Hints, Using with GDB |
444 |
@comment node-name, next, previous, up |
445 |
@section Patching GDB for AVR |
446 |
@cindex gdb, building |
447 |
@cindex avr-gdb |
448 |
|
449 |
In order to use simulavr as a backend to gdb, you must build a special |
450 |
AVR patched version of gdb. The source code for simulavr contains the |
451 |
needed patches and instructions for patching and building avr-gdb on a |
452 |
Unix system. |
453 |
|
454 |
Check @uref{http://freesoftware.fsf.org/download/simulavr/gdb-patches/} |
455 |
for the latest gdb patch. |
456 |
|
457 |
@b{NOTE: As of 12 Feb 2002, I'm working to get AVR support merged into |
458 |
the mainline of the gdb source tree. The latest patches must be applied |
459 |
against the current cvs version of gdb |
460 |
(@uref{http://www.gnu.org/software/gdb/current/}). TRoth.} |
461 |
|
462 |
@b{NOTE: Starting with gdb-5.2.1, gdb offcially supports the avr |
463 |
target. There is no need to patch gdb to get avr support, just configure |
464 |
with the @code{--target=avr} option to build avr-gdb.} |
465 |
|
466 |
@c |
467 |
@c Display Coprocesses |
468 |
@c |
469 |
@node Display Coprocesses, Internals, Using with GDB, Top |
470 |
@comment node-name, next, previous, up |
471 |
@chapter Display Coprocesses |
472 |
@cindex display |
473 |
@cindex display protocol |
474 |
@cindex @code{SIM_DISP_PROG} |
475 |
@cindex @code{SIM_PIPE_FD} |
476 |
|
477 |
This chapter documents the protocol that simulavr uses to pass register |
478 |
and memory information to a display coprocess. |
479 |
|
480 |
A display coprocess is a separate program started by simulavr for the |
481 |
sole purpose of displaying register and memory information while an AVR |
482 |
program is running in the simulator. Using a separate program and a |
483 |
standardized communication protocol, keeps the simulavr code simpler and |
484 |
allows for a variety of display programs to be used. |
485 |
|
486 |
When the user asks simulavr to display register and memory information |
487 |
during execution, simulavr will start a coprocess to perform the display |
488 |
work. A pipe will be opened in simulavr into which the data will be |
489 |
written using the following commands: |
490 |
|
491 |
@multitable @columnfractions .30 .70 |
492 |
|
493 |
@item @samp{q} |
494 |
@tab Quit. |
495 |
|
496 |
@item @samp{r<reg>:<val>} |
497 |
@tab Set register to val. |
498 |
|
499 |
@item @samp{p<val>} |
500 |
@tab Set program counter to val. |
501 |
|
502 |
@item @samp{i<reg>:<val>} |
503 |
@tab Set io register to val. |
504 |
|
505 |
@item @samp{I<reg>:<name>} |
506 |
@tab Set io register name. |
507 |
|
508 |
@item @samp{s<addr>,<len>:XX} |
509 |
@tab Set sram addrs to values (one XX pair per addr). |
510 |
|
511 |
@item @samp{e<addr>,<len>:XX} |
512 |
@tab Set eeprom addrs to values (one XX pair per addr). |
513 |
|
514 |
@item @samp{f<addr>,<len>:XXXX} |
515 |
@tab Set flash addrs to values (one XXXX quad per addr). |
516 |
|
517 |
@item @samp{n<clock_ticks>} |
518 |
@tab Update the number of clock ticks. |
519 |
|
520 |
@end multitable |
521 |
|
522 |
All values are hexidecimal numbers, except for <name> which is a string. |
523 |
|
524 |
In order for the display process to know which pipe to read the |
525 |
information, it must handle either the @samp{--pfd <fd>} option or check |
526 |
the @code{SIM_PIPE_FD} enviroment variable. The value passed using |
527 |
either method will be the file descriptor number of the pipe from which |
528 |
the display prgram will read the informtion. |
529 |
|
530 |
Simulavr will start all display programs like so (sizes are decimal |
531 |
numbers of bytes and sram_start is just the decimal address of the |
532 |
first byte of sram, usually 0x60 [96] or 0x100 [256]): |
533 |
|
534 |
@samp{<prog> --pfd <fd> <flash_size> <sram_size> <sram_start> <eeprom_size>} |
535 |
|
536 |
The user can specify the display program to use via the |
537 |
@samp{--disp-prog} option to simulavr or using the @code{SIM_DISP_PROG} |
538 |
environment variable. If both are not specified, then no display will be |
539 |
used. |
540 |
|
541 |
@c |
542 |
@c Simulavr Internals |
543 |
@c |
544 |
@node Internals, Problems, Display Coprocesses, Top |
545 |
@comment node-name, next, previous, up |
546 |
@chapter Simulavr Internals |
547 |
@cindex internals |
548 |
@cindex developing |
549 |
|
550 |
Simulavr internals are documented using the doxygen system to automate |
551 |
generation of the documentation from the source code comments. The |
552 |
documentation for the latest release is always available at: |
553 |
|
554 |
@uref{http://freesoftware.fsf.org/download/simulavr/internals_html/} |
555 |
|
556 |
The most up-to-date documents will most likely be those in the source |
557 |
code itself. If you wish to help develop simulavr, it is highly |
558 |
recommended that you get the latest source from cvs and consult the |
559 |
internals documents there. |
560 |
|
561 |
@c |
562 |
@c Problems |
563 |
@c |
564 |
@node Problems, Concept Index, Internals, Top |
565 |
@comment node-name, next, previous, up |
566 |
@chapter Reporting Bugs |
567 |
@cindex bugs |
568 |
@cindex problems |
569 |
|
570 |
If you find a bug in simulavr, please send electronic mail to@* |
571 |
@w{@email{Simulavr-devel@@mail.freesoftware.fsf.org}}. Include the |
572 |
version number, which you can find by running @w{@samp{simulavr |
573 |
--version}}. Also include in your message the output that simulavr |
574 |
produced, a simple AVR program which reproduces the bug, and the |
575 |
output you expected. |
576 |
|
577 |
If you have other questions, comments or suggestions about simulavr, |
578 |
contact me via electronic mail at the above address. |
579 |
|
580 |
@c |
581 |
@c Concept Index |
582 |
@c |
583 |
@node Concept Index, , Problems, Top |
584 |
@comment node-name, next, previous, up |
585 |
@unnumbered Concept Index |
586 |
|
587 |
@printindex cp |
588 |
|
589 |
@bye |