/[simulavr]/simulavr/doc/simulavr.texi
ViewVC logotype

Contents of /simulavr/doc/simulavr.texi

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.19 - (show annotations) (download) (as text)
Sat Feb 22 23:00:31 2003 UTC (21 years, 2 months ago) by troth
Branch: MAIN
Changes since 1.18: +2 -2 lines
File MIME type: application/x-texinfo
* doc/simulavr.texi: Fix gdb configure target argument.

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

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26