XBoot Readme

See the XBoot wiki for the latest version of this information: http://alexforencich.com/wiki/en/xboot/

Also, please check the git repository on github: https://github.com/alexforencich/xboot

Table of Contents

1 Introduction
    1.1 Compatibility List
2 Using XBoot
    2.1 Configure
    2.2 Build XBoot and Program to Chip
    2.3 Write Main Application Program
    2.4 Notes for Main Application
3 Configuring XBoot
    3.1 Bootloader clock options
    3.2 AVR 1008 fixes
    3.3 Bootloader entrance options
    3.4 Bootloader exit options
    3.5 Bootloader communication
    3.6 General Options
    3.7 Bootloader features
    3.8 API Support
    3.9 Code Protection
4 XBoot API
    4.1 Using the API
    4.2 Return Values
    4.3 General API Functions
    4.4 Low-level Flash Programming API
    4.5 Firmware Update API
    4.6 Offsets defined in xbootapi.h
    4.7 Using the Firmware Update API

1 Introduction

XBoot is an extensible, modular bootloader for the ATMEL AVR processor series, compatible with both AVR ATMEGA and AVR XMEGA devices with sufficient memory. It is compatible with the AVR109 (butterfly) bootloader protocol with a few XMEGA specific extensions for access to the user and production signature rows. XBoot includes several advanced features including multiple serial busses and an API providing the ability for the running application to update itself without the need for external programming hardware. Many bootloaders only support RS232 for programming from a PC, but XBoot's modularity allows it to support the exact same set of commands over any hardware serial port. Currently, I²C, RS485, and parallel FIFO support have been incorporated. This allows for easy in-system reconfiguration of XBoot equipped chips with little additional time investment. Also, XBoot includes support for I²C address autonegotiation for when multiple, identically configured processors sit on the same I²C bus.

Thanks for using XBoot!

Alex Forencich

1.1 Compatibility List

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
  • atxmega8e5
  • atxmega16a4 *
  • atxmega16e5
  • atxmega32a4 *
  • atxmega32e5 *
  • atxmega64a1
  • atxmega64a3 *
  • atxmega64a4
  • atxmega128a1 *
  • atxmega128a3 *
  • atxmega128a4
  • atxmega192a1
  • atxmega192a3
  • atxmega256a1
  • atxmega256a3b
  • atxmega256a3 *
  • atxmega16d4
  • atxmega32d4
  • atxmega64d3
  • atxmega64d4
  • atxmega128d3
  • atxmega128d4
  • atxmega192d3
  • atxmega256d3
  • atxmega16a4u
  • atxmega32a4u *
  • atxmega64a3u
  • atxmega64a4u
  • atxmega128a3u
  • atxmega128a4u
  • atxmega192a3u
  • atxmega256a3u
  • atxmega256a3bu
  • atxmega64b1
  • atxmega64b3
  • atxmega128b1
  • atxmega128b3
• ATMEGA
  • atmega324
  • atmega324pa
  • atmega325
  • atmega3250
  • atmega328p *
  • atmega329
  • atmega3290
  • atmega64
  • atmega640
  • atmega644
  • atmega644pa
  • atmega645
  • atmega6450
  • atmega649
  • atmega649p
  • atmega6490
  • atmega128
  • atmega1280
  • atmega1281
  • atmega1284p *
  • atmega2560
  • atmega2561

2 Using XBoot

2.1 Configure

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.mkfile 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”.

2.2 Build XBoot and Program to Chip

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 package, and 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.

2.3 Write Main Application Program

To write a program to a device with XBoot installed, use a command like this:

avrdude -p atxmega64a3 -P /dev/ttyUSB0 -c avr109 -b 115200 -U flash:w:main.hex

Or for windows:

avrdude -p atxmega64a3 -P com1 -c avr109 -b 115200 -U flash:w:main.hex

Also, feel free to re-use XBoot's makefile for your own code. Like XBoot, it is reconfigurable and can be used to compile most projects, just make sure to turn off the MAKE_BOOTLOADER flag for regular programs. It also has the configuration options for XBoot as a target built in, all you need to do is switch a couple of comments around.

NOTE: At this time, avrdude (currently 5.10) does NOT support programming the XMEGA flash boot section (see https://savannah.nongnu.org/bugs/?28744) due to the fact that a different programming command must be sent to the chip to write flash pages in the boot section. If you want to use avrdude, you will need to compile it from source with one of the patches listed on the bug report.

2.4 Notes for Main Application

Here are a few tips for your main application that will make using XBoot a much more pleasant experience.

2.4.1 Catch the "Enter Bootloader" command

When AVRDude starts programming the chip, the first character sent out is the the sync command; the “Escape” character, 0x1B. If your program transmits ASCII, or only transmits Binary during certain program states, you can monitor the UART for the escape character and cause a software reset to enter the bootloader, as shown in the following snippet on an XMEGA:

if (rx_byte == 0x1B) {
   CCPWrite( &RST.CTRL, RST_SWRST_bm );
}

Or, if CCPWrite is not available, this should also work:

if (rx_byte == 0x1B) {
   CCP = CCP_IOREG_gc;
   RST.CTRL = RST_SWRST_bm;
}

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.

2.4.2 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:

srec_cat xboot.hex -intel main.hex -intel -o mergedfile.hex -intel

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.

3 Configuring XBoot

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:

# Entry
USE_ENTER_DELAY = yes
USE_ENTER_UART = yes
 
# Communication
USE_LED = yes
USE_UART = yes
 
# Bootloader Features
ENABLE_BLOCK_SUPPORT = yes
ENABLE_FLASH_BYTE_SUPPORT = yes
ENABLE_EEPROM_BYTE_SUPPORT = yes
ENABLE_LOCK_BITS = yes
ENABLE_FUSE_BITS = yes

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.

3.1 Bootloader clock options

3.1.1 USE_DFLL

This will turn on the DFLL for the selected oscillator, improving its accuracy. Recommended for high serial baud rates. This option only applies to XMEGA processors.

3.1.2 USE_32MHZ_RC

This will switch to the 32MHz RC oscillator on start. In the default configuration of xboot.h, this will be defined automatically when F_CPU is set to 32000000. This option only applies to XMEGA processors.

3.2 AVR 1008 fixes

If you're using a device affected by AVR1008, then you may need to enable these for the bootloader to successfully program the chip. Affected chips are the ATXMEGA256A3 rev A, ATXMEGA256A3B rev B, ATXMEGA256A3 rev B, and possibly the ATXMEGA192A3.

3.2.1 USE_AVR1008_EEPROM

This enables the AVR1008 fix for the EEP