Initial port from Google Code

AddingOptibootChipsToIde.md

@@ -0,0 +1,5 @@
+# Not Done yet #
+
+This involves adding or editing a "boards.txt" file somewhere in the Arduino application or user sketch directory hierarchy.
+
+Both the preferred location, and the format, of the file change from version to version of the IDE.

CompilingOptiboot.md

@@ -0,0 +1,16 @@
+# Introduction #
+
+You can compile Optiboot for platforms that do not have pre-existing .hex files, or you can make modifications to the source code and/or Makefile in order to implement "custom" versions of Optiboot.
+
+This will require some relatively deep knowledge of avr-gcc, Atmel AVR hardware and processor details, Makefiles, and the command line environment.  We HAVE tried to take steps to allow Optiboot to be compiled without installing a full AVR development suite.
+
+
+# Details #
+
+Optiboot is designed to be compiled with the same version of avr-gcc that is distributed with the Arduino environment: 4.3.2.  This is actually quite an old version of gcc; some effort has been made to allow the compile to procede with new versions of the compiler.  However, since Optiboot MUST compile to a total size of less than 512 bytes, it is very sensitive to changes in the way the compiler does optimizations, or the way it processes optimization options on the compile command.
+
+In all cases, Optiboot compiles directly from the command line using "make", rather than from within any IDE.  It is currently designed to used compilers installed in one of three different places:
+
+  * Local Development Environment - you have WinAVR (on Windows), CrossPack (on Mac), or an avr-gcc package (linux) installed on your system, with appropriate development tools somewhere in your path.
+  * You have Arduino installed, and are trying to compile Optiboot from its home directory within the Arduino directory structure (hardware/arduino/bootloaders/optiboot/)  The Arduino app includes a pretty complete set of compiler tools, and these can be used to compile optiboot without installing a separate toolchain.
+  * You have downloaded the Arduino Source code, which also includes (binary) copies of avr-gcc toolchains, and a source directory containing the Optiboot source code.

GoodQuestions.md

@@ -0,0 +1,47 @@
+# Good Question! #
+
+Optiboot occasionally generates questions on various forums (Arduino, AVRFreaks, etc), and I thought I'd collect some of the answers here, without spending a lot of time trying to re-organize them as actual "documentation."
+
+  1. Can I put Optiboot on my Arduino MEGA2560 ?
+
+ No.  Optiboot uses "Version 1" of the STK500 communications protocol, which only allows up to 64kwords of flash to be programmed.
+ 
+  1. Why does Optiboot have its own copy of boot.h ?
+
+  The copy of boot.h used by Optiboot has been modified to use "out" instructions instead of "sts."  The out instruction is shorter, but only works if the target registers in withing the first 64 IO addresses.
+  
+  1. What is a "Virtual Boot Partition"
+ 
+ VIRTUAL\_BOOT\_PARTITION is a hack for implementing a bootloader on parts that don't have "start at the bootloader address after reset" support.  So the start vector always has to be at 0, where it will be overwritten by the application's vectors.  Except the bootloader "cleverly substitutes" its own start address for the start of the application during "upload", causing the bootloader to always run first.
+ 
+  1. Why is there an extra `BAUD_RATE * 4L` there? Why is it using 4L and 8L rather than just 4 and 8?
+
+ It's doing rounding.  int(calculated\_divisor + 0.5), except since it's all integers we use algebra and multiply the 0.5 by something big enough to make it an integer.  (Hmm.  This is probably silly; I should just let it use compile-time floating point.  like `__delay_ms()`)
+ 
+  1. What is the difference between `"__boot_page_fill_short" and "__boot_page_write_short"`?
+
+ Flash is written a full page at a time, rather than a byte at a time.  To write a page of flash, you fill a RAM buffer in the flash controller peripheral (boot\_page\_fill), and then give a "boot\_page\_write" to actually write that buffer to the flash memory.  All together, there are three copies (buff, which is filled from the serial comm, the flash page buffer filled by page\_fill, and the flash itself.)
+ 
+  1. What's with the "`#define rstVect (*(uint16_t*)(RAMSTART+SPM_PAGESIZE*2+4))`" ?
+
+ These are "manually defined" variables.  Normally you'd say `"char buff[SPM_PAGESIZE]; int rstvector, wdtvector;"`  But C would want to include code to initialize those variables, which would be "too much" extra code for optiboot to fit in 512 bytes.  So instead we define buff as being where we know the first byte of RAM is and rstvetcor as the first byte after buff, and so on.
+ 
+  1. What is RAMPZ? what is being done in the "`newAddress += newAddress`" line?
+
+ RAMPZ is the "extra byte" of flash addressing for parts with more than 64k words.
+ 
+ The addition (multiply by 2) converts from (16bit) word addresses that Atmel likes to use in various place, to byte addresses used by the hardware and avr-libc in most places.
+ 
+  1. What are "sections" and the ".version" section in particular, and what is optiboot doing with them?
+
+ The "section" attribute is equivalent to the .section gnu assembler directive.    http://tigcc.ticalc.org/doc/gnuasm.html#SEC119 (one source; generic.)  ".version" is an arbitrary name.<br>
+ These are essentially commands that transfer information from the source code to the linker, which will then put together the various bits of information in various places in memory, based on the "linker map" (file provided by the infrastructure) and commands given to it explicitly ("-Wl,--section-start=.version=0x3ffe" in the Makefile.)  The newer code does this in C with attribute instead of using inline assembler, but it does the same thing.
+ 
+  1. How does Optiboot put the code and version number at the correct absolute flash addresses?<br>
+
+ The output from the compiler is in relocatable "sections" that are then relocated and assigned to appropriate addresses by the linker.  The addresses used are normally determined by a "linker map" file that is part of the per-chip definitions included with the compiler, but in the case of Optiboot, they are specified explicitly in the link command using the <code> -Wl,--section-start=.text=0x3e00</code> type commands.<br>
+
+
+  1. Where did 0x3e00 come from?  I don't see that in the data sheet!
+  
+ There are various places where the Atmel documentation uses WORD addresses for flash memory, while most of the gnu tools use BYTE addresses.  0x3e00 comes from the "boot size configuration" in the boot loader support chapter of the datasheet (where it says "0x1F00")

Home.md

@@ -1 +1,9 @@
-Welcome to the optiboot wiki!
+Welcome to the optiboot wiki!<br>
+##Wiki pages:##
+
+* Installing
+* CompilingOptiboot
+* HowOptibootWorks
+
+* AddingOptibootChipsToIde
+* GoodQuestions - Frequently asked technical questions

HowOptibootWorks.md

@@ -0,0 +1,44 @@
+# Introduction #
+
+Optiboot implements a small subset of the  "STK500 communications protocol" (version 1) defined by Atmel in their [Application Note AVR061](http://www.atmel.com/Images/doc2525.pdf)  In order to conserve code space, many of the protocol commands are ignored and receive "lies" rather than correct response codes, leading to the possibility that the bootloader may not operate correctly with all host-side software.  It is known to work with versions of "avrdude" supporting the "-c arduino" programmer type.
+
+Optiboot is designed to reside in the bootloader section, and chip fuses should be set appropriately for the size of optiboot (normally 256 words) (BOOTSZx) and to reset to the bootloader start address (BOOTRST)  Note that BOOTSZx values are chip-dependent, and some of the chips suppored by Optiboot have a 512word minimum bootloader size.)
+
+## Basic Operation ##
+  1. On reset, Optiboot starts and reads the reset reason from MCUSR.  For any cause other than "external reset", the application is started immediately.  Otherwise, optiboot attempts to download new application software:
+  1. The "start LED" is flashed to indicate that optiboot is running. (which pin is used, and how many times it flashes, is configurable.)
+  1. The (configurable) UART is configured and the WDT is enabled with a 1s timeout.
+  1. Optiboot attempts to read commands from the (configurable) serial port.  Valid characters will cause the WDT to be reset, and the application flash area to be programmed (hopefully.)
+  1. With no valid UART traffic, or after programming, the WDT is allowed to expire, causing the chip to reset.
+  1. Since the WDT reset is NOT an 'external reset', the application is started as in (1) - the AVR at the time the application is run has all IO registers except MCUSR and SP in their pristine, reset, state.
+
+# Details #
+## Implemented Commands ##
+The following core commands are "supported"; they actually do something useful WRT loading code via the bootloader:
+
+|Cmd Name | Value  | Description |
+|:--------|-------|:------------|
+|STK\_LOAD\_ADDRESS|0x55,'U'| Note: 16bit word address, 128kb flash max.|
+|STK\_PROG\_PAGE|0x64,'d'|  Flash only|
+|STK\_READ\_PAGE|0x74,'t'|  Flash only|
+|STK\_READ\_SIGN|0x75,'u'|  Reads compiled-in signature.|
+|STK\_LEAVE\_PROGMODE|0x51,'Q'| Starts application code via WDT reset.|
+|STK\_GET\_PARAMETER|0x41,'A'| Supports "minor SW version" and "major SW version"  Returns 3 for all other parameters.|
+
+The following commands will have their arguments correctly read, and produce in a "success" response, but they don't actually do anything:
+
+|Cmd Name | Value |
+|:------------- |:-------- |
+|STK\_UNIVERSAL|0x56, 'V'| |
+|STK\_SET\_DEVICE|0x41, 'B'| |
+|STK\_SET\_DEVICE\_EXT|0x45, 'E'| |
+
+All other commands will result in a success response if they are immediate followed by CRC\_EOP (0x20, ' ') (ie they are ignored), or a WDT reset (start applicatin) otherwise.
+
+## Space Saving Techniques ##
+In order to save space, Optiboot utilizes a couple of techniques that may be of general interest:
+
+  * The Vector table are normal startup code are omitted by using linker options "-nostdlib -nostartfiles"
+  * This requires that main() be declared with attribute OS\_main and manually placed in the .init9 section.
+  * and thus main() has to initialize the known-zero register (r1) and SP on chips that don't automatically set SP to end-of-ram.
+  * inlining of functions is carefully controlled.

Installing.md

@@ -0,0 +1,34 @@
+# Installing optiboot #
+
+There are two aspects to "installing optiboot."  The first problem, which is discussed here, involves getting the optiboot firmware into chips, whether the chips have an older version of a bootloader, or are completely blank.
+
+The second problem is configuring the Arduino IDE to support the optiboot-loaded chips.  This is easy if you're loading up ATmega328x chips, since any 328 chip with optiboot is essentially an Arduino Uno, and you can use the existing Uno configuration.  It is more difficult (and not yet documented) if you're adding a new chip, or putting optiboot on a chip that normally uses a different bootloader.  This is (will be) described at AddingOptibootChipsToIde.
+
+Much information about burning optiboot into ATmega chips for use in Arduino can be found in the Arduino forums, especially in [this thread](http://arduino.cc/forum/index.php/topic,64105.0.html)
+
+There are about three main methods of installing optiboot on an otherwise blank AVR chip.
+
+## Installing using the Arduino IDE ##
+If you are using a chip that is "supported" by the Arduino team, or by some other person who has provided files, you can install optiboot (or for that matter, any other bootloader) directly from the Arduino IDE.  This usually has the following steps:
+
+  1. Install the files as directed, usually (for Arduino 1.0+) in a subdirectory of your personal sketch's ../hardware/ directory.  Note that the formats of various files (notably boards.txt) have changed with different versions of the IDE, and you'll need to make sure that the files you have been provided match the version of the IDE you are using.
+  1. Connect a device programmer to the ISP connector of the target board, or via wires to an avr chip with appropriate support hardware in a protoboard, as per the instructions associated with that programmer.  It will need to be a programmer of a type supported by the Arduino IDE in the tools/programmer Menu.  You can use a 2nd Arduino with the ArduinoISP sketch as a programmer.  The details are beyond the scope of this document, but are often discussed in the Arduino forums.
+  1. Running the Arduino IDE, select the tools/board of the target chip, and the tools/programmer of your programmer, and if necessary the tools/serial port of the programmer.
+  1. Select tools/Burn Bootloader
+
+## Installing using a specialized bootloader loader sketch ##
+There are a couple of Arduino sketches that have been written to make it easier to reprogram Optiboot (or other SW) into other Arduinos, especially in bulk.  One example is WestfW's [OptiLoader](https://github.com/WestfW/OptiLoader).  Similar programs are available from [Adafruit](https://github.com/adafruit/Standalone-Arduino-AVR-ISP-programmer) and [Nick Gammon](http://www.gammon.com.au/forum/?id=11635).  These typically contain a pre-loaded copy of some version of the bootloader for several different chips (OptiLoader supports ATmega8, ATmega168, ATmega328P, and ATmega328.)  It's very fast and easy IF you have one of the supported targets:
+
+  1. Set up an existing Arduino with an Arduino to ISP connector and load the optiLoader sketch using the standard Arduino IDE.
+  1. For each target board, connect the ISP connector and hit the reset button on the optiLoader Arduino, or use the "G" command in the Serial Monitor.  Programming the bootloader takes about 5 seconds, and reports status and information to the Arduino serial port.
+
+## Installing using the optiboot repository Makefile ##
+We might assume that you're here at the optiboot code repository because you want to use optiboot on a chip that is NOT supported by another party, but is supposed to be supported by the optiboot in general.  (An example might be the ATmega1280, which normally runs a different bootloader.)
+
+  1. Compile the appropriate binary target (ie "mega1280"), as described on the CompilingOptiboot page.
+  1. Connect a device programmer to your target as appropriate.
+  1. Edit the Makefile to make the ISPxxx variables correct for your programmer.  Make sure that there is a "target\_isp" make target defined, or create it using the existing targets as examples.
+  1. Use a command like "make mega1280\_isp" to burn the bootloader.
+  1. You can also use avrdude at the command line, manually.  Burning the bootloader is usually a two-step process:
+    * "chip erase" the target and set the fuses and lockbits to allow writing to the bootloader section of the device
+    * burn the bootloader at its defined address, and reset the lockbits to prevent accidental overwriting of the bootloader section.