LUFA/Build/DMBS/DMBS/avrdude.md

   1 DMBS - Dean's Makefile Build System
   2 ===================================
   3
   4
   5 Module: AVRDUDE
   6 -----------------
   7
   8 The AVRDUDE module provides build targets for use with the official
   9 open source `AVRDUDE` programmer utility, for the reprogramming of Atmel devices
  10 using a wide variety of official and non-official programming devices and
  11 bootloaders.
  12
  13 ## Importing This Module into a Makefile:
  14
  15 To use this module in your application makefile, add the following code to your
  16 makefile:
  17
  18     include $(DMBS_PATH)/avrdude.mk
  19
  20 ## Prerequisites:
  21
  22 This module requires the `avrdude` utility to be available in your
  23 system's `PATH` variable. The `avrdude` utility is distributed on the project's
  24 [official site](https://savannah.nongnu.org/projects/avrdude) but is also
  25 made available in many *nix operating system's package managers.
  26
  27 ## Build Targets:
  28
  29 The following targets are supported by this module:
  30
  31 <table>
  32  <tbody>
  33    <tr>
  34     <td>avrdude-lfuse</td>
  35     <td>Program the device low fuse. Requires AVRDUDE_LFUSE variable set.</td>
  36    </tr>
  37    <tr>
  38     <td>avrdude-hfuse</td>
  39     <td>Program the device high fuse. Requires AVRDUDE_HFUSE variable set.</td>
  40    </tr>
  41    <tr>
  42     <td>avrdude-efuse</td>
  43     <td>Program the device extended fuse. Requires AVRDUDE_EFUSE variable set.</td>
  44    </tr>
  45    <tr>
  46     <td>avrdude-lock</td>
  47     <td>Program the device lock bits. Requires AVRDUDE_LOCK variable set.</td>
  48    </tr>
  49    <tr>
  50     <td>avrdude-fuses</td>
  51     <td>
  52      Program the device fuses (lfuse, hfuse, efuse, lock bits).<br>
  53      Requires AVRDUDE_LFUSE, AVRDUDE_HFUSE and AVRDUDE_LOCK variable set. AVRDUDE_EFUSE is optional.
  54     </td>
  55    </tr>
  56    <tr>
  57     <td>avrdude</td>
  58     <td>Program the device FLASH memory with the application's executable data.</td>
  59    </tr>
  60    <tr>
  61     <td>avrdude-ee</td>
  62     <td>Program the device EEPROM memory with the application's EEPROM data.</td>
  63    </tr>
  64    <tr>
  65     <td>avrdude-all</td>
  66     <td>Same as avrdude + avrdude-fuses.</td>
  67    </tr>
  68    <tr>
  69     <td>avrdude-all-ee</td>
  70     <td>Same as avrdude + avrdude-ee + avrdude-fuses.</td>
  71    </tr>
  72  </tbody>
  73 </table>
  74
  75 ## Mandatory Variables:
  76
  77 The following variables must be defined (with a `NAME = VALUE` syntax, one
  78 variable per line) in the user makefile to be able to use this module:
  79
  80 <table>
  81  <tbody>
  82    <tr>
  83     <td>MCU</td>
  84     <td>Name of the Atmel processor model (e.g. `at90usb1287`).</td>
  85    </tr>
  86    <tr>
  87     <td>TARGET</td>
  88     <td>Name of the application output file prefix (e.g. `TestApplication`).</td>
  89    </tr>
  90  </tbody>
  91 </table>
  92
  93 ## Optional Variables:
  94
  95 The following variables may be defined (with a `NAME = VALUE` syntax, one
  96 variable per line) in the user makefile. If not specified, a default value will
  97 be assumed.
  98
  99 <table>
 100  <tbody>
 101    <tr>
 102     <td>AVRDUDE_MCU</td>
 103     <td>Override the `MCU` variable for `avrdude`. On some controllers, `avrdude` expects another spelling than the compiler needs. Default is `MCU`.</td>
 104    </tr>
 105    <tr>
 106     <td>AVRDUDE_PROGRAMMER</td>
 107     <td>Name of the programmer/debugger tool or bootloader to communicate with (e.g. `jtagicemkii`). Default is `jtagicemkii`.</td>
 108    </tr>
 109    <tr>
 110     <td>AVRDUDE_PORT</td>
 111     <td>Name of the communication port to use when when programming with a serially connected tool (e.g. `COM2`). Default is `usb`.</td>
 112    </tr>
 113    <tr>
 114     <td>AVRDUDE_FLAGS</td>
 115     <td>Additional flags to pass to `avrdude` when invoking the tool. Default is empty (no additional flags).</td>
 116    </tr>
 117    <tr>
 118     <td>AVRDUDE_MEMORY</td>
 119     <td>Memory space to program when executing the `avrdude` target (e.g. 'application` for an XMEGA device). Default is `flash`.</td>
 120    </tr>
 121    <tr>
 122     <td>AVRDUDE_BAUD</td>
 123     <td>Baud rate to use when executing the `avrdude` target (e.g. '115200` for an Optiboot device). Default is empty.</td>
 124    </tr>
 125    <tr>
 126     <td>AVRDUDE_BITCLK</td>
 127     <td>ISP bit clock period in microseconds to use when executing the `avrdude` target (format: float). Must be minimum 4x longer than MCU clock period. Default is 1 us.</td>
 128    </tr>
 129    <tr>
 130     <td>AVRDUDE_HFUSE</td>
 131     <td>Fuse setting to use when executing the `avrdude-hfuse` target (format: 0x??). Default is empty.</td>
 132    </tr>
 133    <tr>
 134     <td>AVRDUDE_EFUSE</td>
 135     <td>Fuse setting to use when executing the `avrdude-efuse` target (format: 0x??). Default is empty.</td>
 136    </tr>
 137    <tr>
 138     <td>AVRDUDE_LFUSE</td>
 139     <td>Fuse setting to use when executing the `avrdude-lfuse` target (format: 0x??). Default is empty.</td>
 140    </tr>
 141    <tr>
 142     <td>AVRDUDE_LOCK</td>
 143     <td>Bit bits setting to use when executing the `avrdude-lock` target (format: 0x??). Default is empty.</td>
 144    </tr>
 145  </tbody>
 146 </table>
 147
 148 ## Provided Variables:
 149
 150 The following variables may be referenced in a user makefile (via `$(NAME)`
 151 syntax) if desired, as they are provided by this module.
 152
 153 <table>
 154  <tbody>
 155    <tr>
 156     <td>N/A</td>
 157     <td>This module provides no variables.</td>
 158    </tr>
 159  </tbody>
 160 </table>
 161
 162 ## Provided Macros:
 163
 164 The following macros may be referenced in a user makefile (via
 165 `$(call NAME, ARG1, ARG2, ...)` syntax) if desired, as they are provided by
 166 this module.
 167
 168 <table>
 169  <tbody>
 170    <tr>
 171     <td>N/A</td>
 172     <td>This module provides no macros.</td>
 173    </tr>
 174  </tbody>
 175 </table>
 176
 177 ## Module Changelog:
 178
 179 The changes to this module since its initial release are listed below, as of the
 180 DMBS version where the change was made.
 181
 182 ### 20200412
 183 Made `AVRDUDE_EFUSE` optional for `avrdude-fuses` because not every AVR has this fuse.
 184
 185 ### 20171231
 186 Added `AVRDUDE_BAUD`, `AVRDUDE_HFUSE`, `AVRDUDE_EFUSE`, `AVRDUDE_LFUSE` and
 187 `AVRDUDE_LOCK` optional variables.
 188
 189 ### 20160403
 190 Initial release.