git.rot13.org Git - simavr/blob - README.md

   1 simavr - lean and mean Atmel AVR simulator for linux
   2 ======
   3
   4 _simavr_ is a new AVR simulator for linux, or any platform that uses avr-gcc. It uses
   5 avr-gcc own register definition to simplify creating new targets for supported AVR
   6 devices. The core was made to be small and compact, and hackable so allow quick
   7 prototyping of an AVR project. The AVR core is now stable for use with parts
   8 with <= 128KB flash, and with preliminary support for the bigger parts. The
   9 simulator loads ELF files directly, and there is even a way to specify simulation
  10 parameters directly in the emulated code using an .elf section. You can also
  11 load multipart HEX files.
  12
  13 Supported IOs
  14 --------------
  15 * _eeprom_
  16 * _watchdog_
  17 * _IO ports_ (including pin interrupts)
  18 * _Timers_, 8 &16 (Normal, CTC and Fast PWM, the overflow interrupt too)
  19 * The _UART_, including tx & rx interrupts (there is a loopback/local echo test mode too)
  20 * _SPI_, master/slave including the interrupt
  21 * _i2c_ Master & Slave
  22 * External _Interrupts_, INT0 and so on.
  23 * _ADC_
  24 * Self-programming (ie bootloaders!)
  25
  26 Emulated Cores (very easy to add new ones!)
  27 --------------
  28 + AT90USB162 (with USB!)
  29 + ATMega1280
  30 + ATMega128
  31 + ATMega16M1
  32 + ATMega164/324/644
  33 + ATMega48/88/168/328
  34 + ATMega8
  35 + ATTiny25/45/85
  36 + ATTIny44/84
  37 + ATTiny2313
  38 + ATTiny13
  39
  40 Extras:
  41 -------
  42 * _gdb_ support fully work (gdb server) including some pretty cool “passive modes”.
  43 * There is also very easy support for “VCD” (Value Change Dump) that can be visualized
  44 graphicaly as “waveforms” with tools like _gtkwave_ (see bellow).
  45 * There are a few examples of real life firmwares running on simavr, including OpenGL rendering of the display…
  46 * There is support _Arduino_, but no integration to the IDE
  47
  48 *Note:* a mailinglist/google group now exists
  49 You can also join *#simavr* on Freenode for a very quiet IRC channel.
  50
  51 VCD Support -- built in logic analyzer
  52 -----------
  53 _simavr_ can output most of it's pins, firmware variables, interrupts and a few other
  54 things as signals to be dumped into a file that can be plotted using gtkwave for
  55 further, precise analysis.
  56 A firmware can contain instructions for _simavr_ to know what to trace, and the file is
  57 automatically generated.
  58 Example:
  59
  60 `const struct avr_mmcu_vcd_trace_t _mytrace[]  _MMCU_ = {
  61         { AVR_MCU_VCD_SYMBOL("UDR0"), .what = (void*)&UDR0, },
  62         { AVR_MCU_VCD_SYMBOL("UDRE0"), .mask = (1 << UDRE0), .what = (void*)&UCSR0A, },
  63 };`
  64
  65 Will tell _simavr_ to generate a trace everytime the UDR0 register changes and everytime
  66 the interrupt is raised (in UCSR0A). The *_MMCU_* tag tells gcc that it needs compiling,
  67 but it won't be linked in your program, so it takes literally zero bytes, this is a code
  68 section that is private to _simavr_, it's free!
  69 A program running with these instructions and writing to the serial port will generate
  70 a file that will display:
  71 `$ ./simavr/run_avr tests/atmega88_example.axf
  72 AVR_MMCU_TAG_VCD_TRACE 00c6:00 - UDR0
  73 AVR_MMCU_TAG_VCD_TRACE 00c0:20 - UDRE0
  74 Loaded 1780 .text
  75 Loaded 114 .data
  76 Loaded 4 .eeprom
  77 Starting atmega88 - flashend 1fff ramend 04ff e2end 01ff
  78 atmega88 init
  79 avr_eeprom_ioctl: AVR_IOCTL_EEPROM_SET Loaded 4 at offset 0
  80 Creating VCD trace file 'gtkwave_trace.vcd'
  81 Read from eeprom 0xdeadbeef -- should be 0xdeadbeef..
  82 Read from eeprom 0xcafef00d -- should be 0xcafef00d..
  83 simavr: sleeping with interrupts off, quitting gracefully`
  84
  85 And when the file is loaded in gtkwave, you see:
  86 ![gtkwave](https://github.com/buserror-uk/simavr/raw/master/doc/img/gtkwave1.png)
  87
  88 You get a very precise timing breakdown of any change that you add to the trace, down
  89 to the AVR cycle.
  90
  91 Example:
  92 --------
  93 _simavr_ is really made to be the center for emulating your own AVR projects, not just
  94 a debugger, but also the emulating the peripherals you will use in your firmware, so
  95 you can test and develop offline, and now and then try it on the hardware.
  96
  97 You can also use _simavr_ to do test units on your shipping firmware to validate it
  98 before you ship a new version, to prevent regressions or mistakes.
  99
 100 _simavr_ has a few 'complete projects/ that demonstrate this, most of them were made
 101 using real hardware at some point, and the firmware binary is _exactly_ the one that
 102 ran on the hardware. The key here is to emulate the _parts_ or peripherals that
 103 are hooked to the AVR. Of course, you don't have to emulate the full hardware, you just
 104 need to generate the proper stimulus so that the AVR is fooled.
 105
 106 HD77480 LCD Board Demo
 107 ----------------------
 108 ![lcd](https://github.com/buserror-uk/simavr/raw/master/doc/img/hd77480.png)
 109
 110 This example board hooks up an Atmega48 to an emulated HD77480 LCD and display a running
 111 counter in the 'lcd'. Everything is emulated, the firmware runs exactly like this
 112 on a real hardware.
 113 ![lcd-gtkwave](https://github.com/buserror-uk/simavr/raw/master/doc/img/hd77480.png)
 114
 115 And this is a gtkwave trace of what the firmware is doing. You can zoom in, measure etc
 116 in gtkwave, select trades to see etc.
 117
 118 Quite a few other examples are available!