Repository files navigation

This repository contains a bootloader, derived from Atmel's SAM-BA,which in addition to the USB CDC (serial) protocol, also supportsthe USB MSC (mass storage).

UF2 (USB Flashing Format) is a name of a file format, developed by Microsoft, that is particularlysuitable for flashing devices over MSC devices. The file consistsof 512 byte blocks, each of which is self-contained and independentof others.

Each 512 byte block consist of (seeuf2format.h for details):

• magic numbers at the beginning and at the end
• address where the data should be flashed
• size of data
• data (up to 476 bytes; for SAMD it's 256 bytes so it's easy to flash in one go)

Thus, it's really easy for the microcontroller to recognize a block ofa UF2 file is written and immediately write it to flash.

• UF2 specification repo:https://github.com/Microsoft/uf2
• #DeskOfLadyada UF24U ! LIVE @adafruit #adafruit #programming

• USB CDC (Serial emulation) monitor mode compatible with Arduino(including XYZ commands) and BOSSA flashing tool
• USB MSC interface for writing UF2 files
• reading of the content of the flash as an UF2 file via USB MSC
• UART Serial (real serial wire) monitor mode (typically disabled due to space constraints)
• In-memory logging for debugging - use thelogs target to extract the logs usingopenocd
• double-tap reset to stay in the bootloader mode
• automatic reset after UF2 file is written

Configuration files for boardfoo are inboards/foo/board_config.h andboard.mk. You canbuild it withmake BOARD=foo. You can also createMakefile.user file withBOARD=footo change the default.

The board configuration specifies the USB vendor/product name and ID,as well as the volume label (main thing that the operating systems show).

There is alsoBOARD_ID, which is meant to be machine-readable and specificto a given version of board hardware. The programming environment might usethis to suggest packages to be imported (i.e., a package for a particularexternal flash chip, SD card etc.).

These configuration values can be read fromINFO_UF2.TXT file.Presence of this file can be tested to see if the board supportsUF2 flashing,while the contents, particularlyBoard-ID field, can be used for feature detection.

The current flash contents of the board is exposed asCURRENT.UF2 file.This file includes the bootloader address space. The last word of bootloaderspace points to the string holding theINFO_UF2.TXT file, so it can be parsedby a programming environment to determine which board does the.UF2 file comes from.

When the user space application implements the USB MSC protocol, it's possible tohandover execution to the bootloader in the middle of MSC file transfer,when the application detects that a UF2 block is written.

Details are being finalized.

The bootloader will never write to its own flash area directly.However, the user code can write there.Thus, to update the bootloader, one can ship a user-space program,that contains the new version of the bootloader and copies it to theappropriate place in flash.

Such a program is generated during build in filesupdate-bootloader*.uf2.If you're already running UF2 bootloader, the easiest way to updateit, is to just copy this file to the exposed MSD drive.

The build also generatesupdate-bootloader*.ino with an equivalent Arduinosketch. You can copy&paste it into Arduino IDE and upload it to the device.

The SAMD21 supports aBOOTPROT fuse, which write-protects the flash area ofthe bootloader. Changes to this fuse only take effect after device reset.

OpenOCD exposesat91samd bootloader command to set this fuse.This command is buggy.It seems to reset both fuse words to0xffffffff, which prevents the devicefrom operating correctly (it seems to reboot very frequently).Inscripts/fuses.tcl there is an OpenOCD scriptwhich correctly sets the fuse. It's invoked bydbgtool.js fuses. It can be alsoused to reset the fuses to sane values - just look at the comment at the top.

The bootloader update programs (both the.uf2 file and the Arduino sketch)clear theBOOTPROT (i.e., set it to0x7) before trying to flash anything.After flashing is done, they setBOOTPROT to 8 kilobyte bootloader size (i.e,0x2).

The SAMD51s bootloader protection can be temporarily disabled through an NVMcommand rather than a full erase and write of the AUX page. The boot protectionwill be checked and set by the self updaters.

So, if you've used self-updaters but want to load it directly, then you'll needto temporarily turn off the protection. In gdb the command is:

set ((Nvmctrl *)0x41004000UL)->CTRLB.reg = (0xA5 << 8) | 0x1a

• make and an Unix environment
• node.js in path (optional)
• arm-none-eabi-gcc in the path (the one coming with Yotta will do just fine). You can get the latest version from ARM:https://developer.arm.com/open-source/gnu-toolchain/gnu-rm/downloads
• openocd - you can use the one coming with Arduino (after your install the M0 board support)

Atmel Studio is not supported.

You will need a board withopenocd support.

Arduino Zero (or M0 Pro) will work just fine as it has an integrated USB EDBGport. You need to connect both USB ports to your machine to debug - one is forflashing and getting logs, the other is for the exposed MSC interface.

Otherwise, you can use other SAMD21 board and an externalopenocd compatibledebugger. IBDAP is cheap and seems to work just fine. Another option is to useRaspberry Pi and native bit-banging.

openocd will flash 16k, meaning that on SAMD21 the beginning of user program (if any) willbe overwritten with0xff. This also means that after fresh flashing of bootloaderno double-tap reset is necessary, as the bootloader will not try to start applicationat0xffffffff.

The default board iszero. You can build a different one using:

make BOARD=metro_m0

If you're working on different board, it's best to createMakefile.userwith sayBOARD=metro to change the default.The nameszero andmetro refer to subdirectories ofboards/.

There are various targets:

• all - just compile the board
• burn orb - compile and deploy to the board using openocd
• logs orl - shows logs
• run orr - burn, wait, and show logs

Typically, you will do:

make r

There is a number of configuration parameters at the top ofuf2.h file.Adjust them to your liking.

By default, you cannot enable all the features, as the bootloader would exceedthe 8k(SAMD21)/16k(SAMD51) allocated to it by Arduino etc. It will assert on startup that it's not biggerthan 8k(SAMD21)/16k(SAMD51). Also, the linker script will not allow it.

Three typical configurations are:

• HID, WebUSB, MSC, plus flash reading via FAT; UART and CDC disabled;logging optional;recommended
• USB CDC and MSC, plus flash reading via FAT; UART disabled;logging optional; this may have Windows driver problems
• USB CDC and MSC, no flash reading via FAT (or at leastindex.htm disabled); UART enabled;logging disabled; no handover; no HID;only this one if you need the UART support in bootloader for whatever reason

CDC and MSC together will work on Linux and Mac with no drivers.On Windows, if you have drivers installed for the USB ID chosen,then CDC might work and MSC will not work;otherwise, if you have no drivers, MSC will work, and CDC will work on Windows 10 only.Thus, it's best to set the USB ID to one for which there are no drivers.

The bootloader sits at 0x00000000, and the application starts at 0x00002000 (SAMD21) or 0x00004000 (SAMD51).

This project has adopted theMicrosoft Open Source Code of Conduct. For more information see theCode of Conduct FAQ or contactopencode@microsoft.com with any additional questions or comments.

See THIRD-PARTY-NOTICES.txt for the original SAM-BA bootloader license from Atmel.

The new code is licensed under MIT.