README.md

   1 simavr - a 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's 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 Installation
  14 ------------
  15 On OSX, we recommend using [homebrew](https://brew.sh):
  16
  17     brew tap osx-cross/avr
  18     brew install --HEAD simavr
  19
  20 On Ubuntu, SimAVR is available in the Bionic package source:
  21
  22     apt-get install simavr
  23
  24 (Note that the command is made available under the name `simavr` not `run_avr`.)
  25
  26 Otherwise, `make` is enough to just start using __bin/simavr__. To install the __simavr__ command system-wide, `make install RELEASE=1`.
  27
  28 Supported IOs
  29 --------------
  30 * _eeprom_
  31 * _watchdog_
  32 * _IO ports_ (including pin interrupts)
  33 * _Timers_, 8 &16 (Normal, CTC and Fast PWM, the overflow interrupt too)
  34 * The _UART_, including tx & rx interrupts (there is a loopback/local echo test mode too)
  35 * _SPI_, master/slave including the interrupt
  36 * _i2c_ Master & Slave
  37 * External _Interrupts_, INT0 and so on.
  38 * _ADC_
  39 * Self-programming (ie bootloaders!)
  40
  41 Emulated Cores (very easy to add new ones!)
  42 --------------
  43 + ATMega2560
  44 + AT90USB162 (with USB!)
  45 + ATMega1281
  46 + ATMega1280
  47 + ATMega128
  48 + ATMega128rf1
  49 + ATMega16M1
  50 + ATMega169
  51 + ATMega162
  52 + ATMega164/324/644
  53 + ATMega48/88/168/328
  54 + ATMega8/16/32
  55 + ATTiny25/45/85
  56 + ATTIny44/84
  57 + ATTiny2313/2313v
  58 + ATTiny13/13a
  59
  60 Extras:
  61 -------
  62 * fully working _gdb_ support including some pretty cool “passive modes”.
  63 * There is also very easy support for “VCD” (Value Change Dump) that can be visualized
  64 graphically as “waveforms” with tools like _gtkwave_ (see below).
  65 * There are a few examples of real life firmwares running on simavr, including OpenGL rendering of the display…
  66 * There is support for _Arduino_, but no IDE integration
  67
  68 Documentation And Further Information
  69 -------------------------------------
  70
  71 * Manual / Developer Guide: https://github.com/buserror-uk/simavr/blob/master/doc/manual/manual.pdf?raw=true
  72 * Examples: https://github.com/buserror-uk/simavr/tree/master/examples
  73 * Mailing List: http://groups.google.com/group/simavr
  74 * IRC: _#simavr_ on Freenode
  75
  76 Contributing
  77 ------------
  78
  79 Patches are always welcome! Please submit your changes via Github pull requests.
  80
  81 VCD Support -- built in logic analyzer
  82 -----------
  83 _simavr_ can output most of its pins, firmware variables, interrupts and a few other
  84 things as signals to be dumped into a file that can be plotted using gtkwave for
  85 further, precise analysis.
  86 A firmware can contain instructions for _simavr_ to know what to trace, and the file is
  87 automatically generated.
  88 Example:
  89
  90         const struct avr_mmcu_vcd_trace_t _mytrace[]  _MMCU_ = {
  91                 { AVR_MCU_VCD_SYMBOL("UDR0"), .what = (void*)&UDR0, },
  92                 { AVR_MCU_VCD_SYMBOL("UDRE0"), .mask = (1 << UDRE0), .what = (void*)&UCSR0A, },
  93         };
  94
  95 Will tell _simavr_ to generate a trace everytime the UDR0 register changes and everytime
  96 the interrupt is raised (in UCSR0A). The *_MMCU_* tag tells gcc that it needs compiling,
  97 but it won't be linked in your program, so it takes literally zero bytes, this is a code
  98 section that is private to _simavr_, it's free!
  99 A program running with these instructions and writing to the serial port will generate
 100 a file that will display:
 101
 102         $ ./simavr/run_avr tests/atmega88_example.axf
 103         AVR_MMCU_TAG_VCD_TRACE 00c6:00 - UDR0
 104         AVR_MMCU_TAG_VCD_TRACE 00c0:20 - UDRE0
 105         Loaded 1780 .text
 106         Loaded 114 .data
 107         Loaded 4 .eeprom
 108         Starting atmega88 - flashend 1fff ramend 04ff e2end 01ff
 109         atmega88 init
 110         avr_eeprom_ioctl: AVR_IOCTL_EEPROM_SET Loaded 4 at offset 0
 111         Creating VCD trace file 'gtkwave_trace.vcd'
 112         Read from eeprom 0xdeadbeef -- should be 0xdeadbeef..
 113         Read from eeprom 0xcafef00d -- should be 0xcafef00d..
 114         simavr: sleeping with interrupts off, quitting gracefully
 115
 116 And when the file is loaded in gtkwave, you see:
 117 ![gtkwave](https://github.com/buserror-uk/simavr/raw/master/doc/img/gtkwave1.png)
 118
 119 You get a very precise timing breakdown of any change that you add to the trace, down
 120 to the AVR cycle.
 121
 122 Example:
 123 --------
 124 _simavr_ is really made to be the center for emulating your own AVR projects, not just
 125 a debugger, but also the emulating the peripherals you will use in your firmware, so
 126 you can test and develop offline, and now and then try it on the hardware.
 127
 128 You can also use _simavr_ to do test units on your shipping firmware to validate it
 129 before you ship a new version, to prevent regressions or mistakes.
 130
 131 _simavr_ has a few 'complete projects/ that demonstrate this, most of them were made
 132 using real hardware at some point, and the firmware binary is _exactly_ the one that
 133 ran on the hardware. The key here is to emulate the _parts_ or peripherals that
 134 are hooked to the AVR. Of course, you don't have to emulate the full hardware, you just
 135 need to generate the proper stimulus so that the AVR is fooled.
 136
 137 HD44780 LCD Board Demo
 138 ----------------------
 139
 140 ![lcd](https://github.com/buserror-uk/simavr/raw/master/doc/img/hd44780.png)
 141
 142 This example board hooks up an Atmega48 to an emulated HD44780 LCD and display a running
 143 counter in the 'lcd'. Everything is emulated, the firmware runs exactly like this
 144 on a real hardware.
 145
 146 ![lcd-gtkwave](https://github.com/buserror-uk/simavr/raw/master/doc/img/hd44780-wave.png)
 147
 148 And this is a gtkwave trace of what the firmware is doing. You can zoom in, measure, etc
 149 in gtkwave, select trades to see etc.
 150
 151 Quite a few other examples are available!