Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
Last revision Both sides next revision
en:xboot:readme [2011/12/18 22:45]
alex [4.1 Using the API]
en:xboot:readme [2012/03/03 22:51]
alex [3.5 Bootloader communication]
Line 13: Line 13:
 Currently, XBoot should work on any XMEGA processor and any ATMEGA with sufficient memory (4K boot NRWW block). ​ The following list of processors are currently supported. ​ An asterisk denotes the MCU has been tested and confirmed XBoot compatible. Currently, XBoot should work on any XMEGA processor and any ATMEGA with sufficient memory (4K boot NRWW block). ​ The following list of processors are currently supported. ​ An asterisk denotes the MCU has been tested and confirmed XBoot compatible.
  
-  * XMEGA+  * XMEGA 
     * atxmega16a4 *     * atxmega16a4 *
     * atxmega32a4 *     * atxmega32a4 *
Line 20: Line 20:
     * atxmega64a4     * atxmega64a4
     * atxmega128a1 *     * atxmega128a1 *
-    * atxmega128a3+    * atxmega128a3 ​*
     * atxmega128a4     * atxmega128a4
     * atxmega192a1     * atxmega192a1
Line 49: Line 49:
     * atxmega128b3     * atxmega128b3
   * ATMEGA   * ATMEGA
 +    * atmega324
 +    * atmega324pa
 +    * atmega325
 +    * atmega3250
     * atmega328p *     * atmega328p *
 +    * atmega329
 +    * atmega3290
 +    * atmega64
 +    * atmega640
 +    * atmega644
 +    * atmega644pa
 +    * atmega645
 +    * atmega6450
 +    * atmega649
 +    * atmega649p
 +    * atmega6490
 +    * atmega128
 +    * atmega1280
 +    * atmega1281
     * atmega1284p *     * atmega1284p *
 +    * atmega2560
 +    * atmega2561
  
 ===== - Using XBoot ===== ===== - Using XBoot =====
Line 56: Line 76:
 ==== - Configure ==== ==== - Configure ====
  
-Before building XBoot, please configure it so it will interface properly with your system. ​ This will involve ​editing some parameters ​in the makefile ​and some parameters ​in xboot.h.  The main parameters that need to be set in the makefile ​are the target chip (MCU) and the frequency (F_CPU). ​ For ATMEGA chips, the boot size (BOOTSZ) must also be set, generally to the largest setting. ​ All you need to do is make sure the only line that's not commented out is the one for your chip and the proper frequency. ​ For the simplest bootloader configuration on the XMEGA, you may only choose 2000000 and 32000000 for the clock speed, corresponding to the two internal RC oscillator frequencies. ​ For ATMEGA chips, the specific start up clock speed (based on the fuse settings and/or external crystal or other clock source) must be specifically entered manually. ​ For the rest of the configuration,​ see the section 3, "​Configuring XBoot"​.+Before building XBoot, please configure it so it will interface properly with your system. ​ This will involve ​selecting a .conf.mk file in the conf directory ​and then editing ​some parameters. ​ The main parameters that need to be set in the .conf.mk file are the target chip (MCU) and the frequency (F_CPU). ​ For ATMEGA chips, the boot size (BOOTSZ) must also be set, generally to the largest setting. ​ All you need to do is make sure the only line that's not commented out is the one for your chip and the proper frequency. ​ For the simplest bootloader configuration on the XMEGA, you may only choose 2000000 and 32000000 for the clock speed, corresponding to the two internal RC oscillator frequencies. ​ For ATMEGA chips, the specific start up clock speed (based on the fuse settings and/or external crystal or other clock source) must be specifically entered manually. ​ For the rest of the configuration,​ see the section 3, "​Configuring XBoot"​.
  
 ==== - Build XBoot and Program to Chip ==== ==== - Build XBoot and Program to Chip ====
  
-To build XBoot, ​open up the Makefile ​and make sure the MCU line for the target processor is the only one uncommented.  Then type "​make"​. ​ This will compile the whole package and generate xboot.hex, which can be downloaded with any programming cable capable of programming AVR chips. ​ If you have and XMEGA and want to save some time and just program the boot section, type "make xboot-boot.hex"​ and then write the new file xboot-boot.hex to the boot section directly with avrdude. ​ The makefile includes built-in support for avrdude, so all you need to do is modify the avrdude parameters in the makefile ​for the programmer you have and type "make program"​.  ​+To build XBoot, ​select a .conf.mk file from the conf directory ​and make sure the settings are appropriate ​for your chip, programmer, and configuration.  Then type "​make ​[file].conf.mk"​. ​ This will copy [file].conf.mk to config.mk, generate config.h, ​compile the whole packageand generate xboot.hex, which can be downloaded with any programming cable capable of programming AVR chips. ​ If you have an XMEGA and want to save some time and just program the boot section, type "make xboot-boot.hex"​ and then write the new file xboot-boot.hex to the boot section directly with avrdude. ​ The makefile includes built-in support for avrdude, so all you need to do is modify the avrdude parameters in the .conf.mk file for the programmer you have and type "make program"​.   
 + 
 +Note that after typing "make [file].conf.mk",​ the settings from [file].conf.mk will remain active until either a new .conf.mk file is selected or "make clean" is run.  ​
  
 ==== - Write Main Application Program ==== ==== - Write Main Application Program ====
Line 79: Line 101:
  
 Here are a few tips for your main application that will make using XBoot a much more pleasant experience. Here are a few tips for your main application that will make using XBoot a much more pleasant experience.
- 
-=== - Program UART Bits Properly === 
- 
-If you select the ''​USE_UART''​ option, XBoot will program the UART.  If your program uses the same UART as XBoot, you should not assume any of the UART registers are blank! ​ Manually force all bits to the desired state. ​ In particular, the 2x bit is often left out of UART configuration routines, but is set by XBoot. 
  
 === - Catch the "Enter Bootloader"​ command === === - Catch the "Enter Bootloader"​ command ===
Line 103: Line 121:
 </​code>​ </​code>​
  
-In many cases, this allows you to use the AVRDude program command without having to manually reset the AVR.  Alternatively, ​if the API is used, calling ​''​xboot_reset()''​ will have the same effect.  ​+In many cases, this allows you to use the AVRDude program command without having to manually reset the AVR.  Alternatively,​ the API call ''​xboot_reset()''​ will have the same effect.   
 + 
 +=== - Combine hex files === 
 + 
 +To streamline programming multiple chips for a production run, the tool ''​srec_cat''​ can be used to combine the hex files. ​ Use the command as follows: 
 + 
 +<​code>​ 
 +srec_cat xboot.hex -intel main.hex -intel -o mergedfile.hex -intel 
 +</​code>​ 
 + 
 +This will concatenate the two hex files together with the proper offsets. ​ Please make sure to use xboot.hex and not xboot-boot.hex to ensure tha the correct offset is used (xboot.hex is relative to address 0 while xboot-boot.hex is relative to the start of the boot section). ​ Note that the combined hex file cannot be programmed with xboot; it is intended to be written with an ISP programmer so both xboot and the application are written in one step.  ​
  
 ===== - Configuring XBoot ===== ===== - Configuring XBoot =====
  
-XBoot is designed to be reconfigured to suit specific needs. ​ Out of the box, everything is turned on.  Turning off features and reassigning pins is easy, open up xboot.and change ​the #defines.  ​+XBoot is designed to be reconfigured to suit specific needs. ​ Out of the box, all of the standard features are turned on.  Turning off features and reassigning pins is easy, just pick a .conf.mk file in the .conf folder, make a copy of it, and edit the appropriate parameters. ​ Then build xboot with your parameters by running ''​make [file].conf.mk''​.  ​
  
 Recommended configuration:​ Recommended configuration:​
  
 <code c> <code c>
-// bootloader entrace +# Entry 
-#​define ​USE_ENTER_DELAY +USE_ENTER_DELAY ​= yes 
-#​define ​USE_ENTER_UART+USE_ENTER_UART ​= yes
  
-// bootloader communication +# Communication 
-#​define ​USE_LED +USE_LED ​= yes 
-#​define ​USE_UART+USE_UART ​= yes
  
-// bootloader features +# Bootloader Features 
-#​define ​ENABLE_BLOCK_SUPPORT +ENABLE_BLOCK_SUPPORT ​= yes 
-#​define ​ENABLE_FLASH_BYTE_SUPPORT +ENABLE_FLASH_BYTE_SUPPORT ​= yes 
-#​define ​ENABLE_EEPROM_BYTE_SUPPORT +ENABLE_EEPROM_BYTE_SUPPORT ​= yes 
-#​define ​ENABLE_LOCK_BITS +ENABLE_LOCK_BITS ​= yes 
-#​define ​ENABLE_FUSE_BITS+ENABLE_FUSE_BITS ​= yes
 </​code>​ </​code>​
  
 This configuration will make the bootloader work similarly to an Arduino. ​ It will blink its light a few times, polling for a character. ​ If none is received, it starts the application. ​ If one shows up, it enters the bootloader and processes it.  ​ This configuration will make the bootloader work similarly to an Arduino. ​ It will blink its light a few times, polling for a character. ​ If none is received, it starts the application. ​ If one shows up, it enters the bootloader and processes it.  ​
 +
 +In fact, the file arduino328p.conf.mk can be used to build XBoot for use on an atmega328p based Arduino.  ​
  
 ==== - Bootloader clock options ==== ==== - Bootloader clock options ====
Line 216: Line 246:
   * ''​UART_U2X''​ turns on the double-rate BRG in ATMEGA parts   * ''​UART_U2X''​ turns on the double-rate BRG in ATMEGA parts
     * Note: this only applies to ATMEGA devices     * Note: this only applies to ATMEGA devices
 +  * ''​UART_RX_PUEN''​ enables a pull-up on the UART RX pin
  
 === - USE_UART_EN_PIN === === - USE_UART_EN_PIN ===
Line 252: Line 283:
   * ''​I2C_AUTONEG_DIS_PROMISC''​ will disable I2C promiscuous mode after completion of autonegotiation routine if nonzero   * ''​I2C_AUTONEG_DIS_PROMISC''​ will disable I2C promiscuous mode after completion of autonegotiation routine if nonzero
   * ''​I2C_AUTONEG_DIS_GC''​ will disable I2C general call detection after completion of autonegotiation routine if nonzero   * ''​I2C_AUTONEG_DIS_GC''​ will disable I2C general call detection after completion of autonegotiation routine if nonzero
-  * ''​I2C_AUTONEG_PORT''​ defines the port in which the autonegotiation pin is located, e.g. ''​PORTA''​+  * ''​I2C_AUTONEG_PORT_NAME''​ defines the port in which the autonegotiation pin is located, e.g. ''​A''​
   * ''​I2C_AUTONEG_PIN''​ defines the pin, e.g. 2   * ''​I2C_AUTONEG_PIN''​ defines the pin, e.g. 2
  
Line 325: Line 356:
  
 Erase each page before writing. ​ This allows the device to be reprogrammed without a complete erase sequence. Erase each page before writing. ​ This allows the device to be reprogrammed without a complete erase sequence.
 +
 +=== - ENABLE_CRC_SUPPORT ===
 +
 +Enables commands for computing the CRC of various sections of Flash memory.  ​
  
 ==== - API Support ==== ==== - API Support ====
Line 355: Line 390:
   * ''​xboot_app_temp_erase''​   * ''​xboot_app_temp_erase''​
   * ''​xboot_app_temp_write_page''​   * ''​xboot_app_temp_write_page''​
 +
 +==== - Code Protection ====
 +
 +The code protection features built into xboot keep your code safe from reverse engineering. ​ Protected areas will read the same as unprogrammed flash or EEPROM (0xff).  ​
 +
 +=== - ENABLE_CODE_PROTECTION ===
 +
 +Enable basic code protection. ​ Code protection prevents reading of the flash memory via xboot'​s interface. ​ Code protection is temporarily disabled by an erase command, allowing verification of newly written firmware. ​ Code protection does not disable CRC commands.
 +
 +=== - ENABLE_EEPROM_PROTECTION ===
 +
 +Enable EEPROM protection. ​ EEPROM protection prevents reading of the EEPROM memory via xboot'​s interface. ​ Like code protection, EEPROM protection is temporarily disabled by an erase command, allowing verification of newly written firmware.  ​
 +
 +=== - ENABLE_BOOTLOADER_PROTECTION ===
 +
 +Enable bootloader protection. ​ Bootloader protection prevents reading of the boot block via xboot'​s interface. ​ Unlike code protection, bootloader protection is not disabled by an erase command.  ​
  
 ===== - XBoot API ===== ===== - XBoot API =====
Line 362: Line 413:
 XBoot provides three different types of API calls. ​ The first type are informational and are required for operation of the API.  The second type are for low-level Flash programming access. ​ The third are for controlled firmware updating. ​ The low-level Flash programming calls and the firmware update calls can be selectively disabled separately.  ​ XBoot provides three different types of API calls. ​ The first type are informational and are required for operation of the API.  The second type are for low-level Flash programming access. ​ The third are for controlled firmware updating. ​ The low-level Flash programming calls and the firmware update calls can be selectively disabled separately.  ​
  
-**Note:** XBoot automatically disables interrupts during Flash programming operations. ​ This is necessary because, despite the name, RWW flash cannot be read and written at the same time.  The interrupt bit will be automatically restored on return from an API call.+**Note:** XBoot automatically disables interrupts during Flash programming operations. ​ This is necessary because, despite the name, RWW flash cannot be read and written at the same time (NRWW can be read while RWW is written, though).  The interrupt bit will be automatically restored on return from an API call.
  
 ==== - Using the API ==== ==== - Using the API ====
Line 581: Line 632:
 </​code>​ </​code>​
  
-Calculating the crc for a new firmware must be done before it is sent to the chip for an update. ​ As the crc passed to ''​xboot_install_firmware''​ must match the crc that XBoot calculates over the entire application temporary section, the firmware must be padded to the size of the application temporary section with 0xff when the crc is calculated beforehand.  ​+Calculating the crc for a new firmware must be done before it is sent to the chip for an update. ​ As the crc passed to ''​xboot_install_firmware''​ must match the crc that XBoot calculates over the entire application temporary section, the firmware must be padded to the size of the application temporary section ​(''​XB_APP_TEMP_SIZE''​) ​with 0xff when the crc is calculated beforehand.  ​
  
 This checksum will be the same as the one calculated by ''​xboot_app_temp_crc16''​. ​ The temptation to simply pass the output of this function back to ''​xboot_install_firmware''​ is great. ​ However, this is where a device can be bricked with ease if the firmware is copied into the application section incorrectly. ​ Therefore, make sure the precalculated crc is the one passed to ''​xboot_install_firmware''​. This checksum will be the same as the one calculated by ''​xboot_app_temp_crc16''​. ​ The temptation to simply pass the output of this function back to ''​xboot_install_firmware''​ is great. ​ However, this is where a device can be bricked with ease if the firmware is copied into the application section incorrectly. ​ Therefore, make sure the precalculated crc is the one passed to ''​xboot_install_firmware''​.