avrfuse 5 2011-12-11 avrfuse

NAME

avrfuse AVR fuse manipulation tool - file formats

DESCRIPTION

There are two file formats used by avrfuse: device maps and fuse configuration files.

Device maps contain information about all bits of fuse bytes implemented in the given model, among with their textual interpretation and default value. These files are model-specific, normally installed in /usr. Content of these files are derived from AVR datasheets.

Fuse configuration file contains actual setting of fuse bits. This file is a per project (or even per instance, in case a project is programmed in multiple models or with multiple fuse configuration). The syntax is an easy to read textual configuration file format, and the configuration file may be embedded in source files. Note: It is not guaranteed that fuse configuration written for a model will translate to another model without modification, as models may have different features.

Syntax of device maps

The device map file is read and parsed line by line. Lines starting with '#' and empty lines are ignored. After reading a line, the line is split in fields at "|" character and whitespace at the beginning and end of fields are deleted.

A line starting with '@' is a section start (that automatically closes any previous section). There are two sections available: "fuse" and "value".

A "fuse" section defines a fuse byte. First field is "@fuse", second file is the name of the fuse byte (i.e. "hfuse"). A fuse section contains exactly 8 fuse bit descriptions (each in a new line). A fuse bit description has the following 4 fields:
name textual name of the bit (i.e. DWEN)
bit index integer between 0 and 7 (order of lines in a fuse section does not matter, but as a convention, lines are ordered 7 down to 0)
description textual description; it must contain at least one control sequence
default value 0 or 1

Control sequences direct avrfuse bout possible values and their meanings (textual representation). A control sequence is a single character immediately followed by text enclosed in curly braces, i.e. 0{text}. Available sequences are:
0{text1} and 1{text2} used for individual bits; must be in pair (both 0{} and 1{} used in the same description). Text within the braces is connected to bit value preceding the brace. Example: description of EESAVE may be "EEPROM memory is 0{preserved} 1{not preserved} through the Chip Erase"
f{1} or f{0} fuse bit has a fixed value, 1 or 0
v{var:bit} fuse bit is part of a multi-bit variable (var is name of the variable, bit is bit index in variable). For example description of CKSEL2 may be "v{CKSEL:2}" with a separate @values section called "CKSEL". Note: no textual description is required for these bits, as description of the @values section will appear in fuse config file.

Multi-bit selections should grouped in @values sections, allowing the user to select a single textual setting for the variable instead of selecting bits one by one. For example, CKSEL typically has 4 bits; the 16 possible values semi-randomly translate to "external, 4 MHz, 8 MHz", etc. If CKSEL bits are marked to be part of a @values section, all the available settings with their textual name and corresponding bit pattern may be listed in @values and at the end the user is presented with a single setting, i.e. "CKSEL = 4 MHz" in the above example.

A @values section line has 3 fields: "@values", name of the variable and textual description of the variable. The following lines are value descriptions in arbitrary order. Each value line has the following fields:
bit pattern in binary (0b010101 format); must be exactly as long as many bits reference the variable with v{}. Instead of 0 or 1, "." may be written for those bit places that can take both values. Must be unique in the current section. Using a "!" instead of bit pattern means "anything else", a catch-all rule when decomposing bits into textual settings.
name short name of the setting; this is what the user will type as value for the setting. Must be unique in the current section.
description long, textual description of the setting (will end up as explanation in comment)

Syntax of fuse configuration files

Each line of the fuse configuration is a key=value pair, unless the line is ignored (empty lines and lines starting with '#' are ignored).

Keys are derived from the device map file. There are one instance of each @values section and each 0{}/1{} bit setting. Value is always the textual form (derived from the "name" field of a value description in the "@values" section or the text in braces for 0{}/1{}).

Order of keys does not matter. When generating a default configuration (avrfuse --default), keys are sorted by their appearance in fuse bytes. When manipulating existing configuration file, avrfuse ill keep exact order of keys.

EXAMPLE

Device map file file (hfuse of attiny2313):

@values | BODLEVEL | Brown-Out Detector trigger level
 0b111 | disabled | BOD disabled
 0b110 | 1.8 | BOD at 1.8 V
 0b101 | 2.7 | BOD at 2.7 V
 0b100 | 4.3 | BOD at 4.3 V
 ! | ! | reserved

@fuse | hfuse
# name | No | Description | Default Value
 DWEN | 7 | debugWIRE 1{enable} 0{disable} | 1
 EESAVE | 6 | EEPROM memory is 0{preserved} 1{not preserved} through the Chip Erase | 1
 SPIEN | 5 | Serial Program and Data Downloading 0{enabled} 1{disabled} | 0
 WDTON | 4 | Watchdog Timer always on 0{enabled} 1{disabled} | 1
 BODLEVEL2 | 3 | v{BODLEVEL:2} | 1
 BODLEVEL1 | 2 | v{BODLEVEL:1} | 1
 BODLEVEL0 | 1 | v{BODLEVEL:0} | 1
 RSTDISBL | 0 | External Reset 0{disabled} 1{enabled} | 1
Fuse configuration (generated with --default, using the above map):

# --- fuse byte hfuse
# External Reset disabled/enabled 
# disabled (0)
# enabled (1)
RSTDISBL=enabled

# Brown-Out Detector trigger level
# disabled (0b111) BOD disabled
# 1.8 (0b110) BOD at 1.8 V
# 2.7 (0b101) BOD at 2.7 V
# 4.3 (0b100) BOD at 4.3 V
BODLEVEL=disabled

# Watchdog Timer always on enabled/disabled 
# enabled (0)
# disabled (1)
WDTON=disabled

# Serial Program and Data Downloading enabled/disabled 
# enabled (0)
# disabled (1)
SPIEN=enabled

# EEPROM memory is preserved/not preserved through the Chip Erase
# preserved (0)
# not preserved (1)
EESAVE=not preserved

# debugWIRE enable/disable 
# enable (0)
# disable (1)
DWEN=disable

SEE ALSO

avrfuse 5 2011-12-11 avrfuse