From 384c05c8b984ea5462bbf0f14591e8ee10923c77 Mon Sep 17 00:00:00 2001 From: stefanrueger Date: Sat, 29 Aug 2026 00:30:39 +0200 Subject: [PATCH] Update documentation for -x holes --- src/avrdude.1 | 51 +++++++++++++++++++++++++++++++--------- src/doc/avrdude.texi | 20 +++++++++++----- src/dryrun_part.c | 55 ++++++++++++++++++++++++++++---------------- 3 files changed, 89 insertions(+), 37 deletions(-) diff --git a/src/avrdude.1 b/src/avrdude.1 index 0e7656f2..f8411cd9 100644 --- a/src/avrdude.1 +++ b/src/avrdude.1 @@ -1607,24 +1607,53 @@ versions of the bootloader. .It Ar dryboot Dryrun emulates external programming without the need to connect a programmer or a part while dryboot emulates bootloader programming without -the need to connect the target part. They accept the following parameters: +the need to connect the target part. +.Pp +Lock and fuse memories are initialised with with factory values as far as +known, 0xff otherwise. The signature memory is set from the configuration +file; the calibration memory is filled with U (for uncalibrated); osc16err +with e and osc20err with E (for error); osccal16 with o and osccal20 with +O; sib with S; tempsense with T; sernum with the downward letter sequence +UTSRQP...; and the volatile io memory with reset values if known, 0x00 +otherwise. +.Pp +If either the init or random parameters are set, then the flash memory is +randomly configured in terms of bootloader sections, code and application +data sections, and the fuses updated accordingly. In either case, flash +(including ATxmega submemories of application, apptable and boot), eeprom, +and all other existing memories such as prodsig/sigrow, userrow/usersig +and bootrow are updated with random data. Flash is always initialised with +benign code, that is its opcodes will not access I/O memories, SRAM or +flash. +.Pp +If none of init or random parameters are set, these memories are +initialised with 0xff. Note that init and random are not meant to be both +set at the same time. +.Pp +The dryrun and dryboot programmers accept the following parameters: .Bl -tag -offset indent -width indent .It Ar init -Initialise memories with human-readable patterns. Flash memory will be -randomly configured with respect to bootloader, data and code length. -Patterns can best be seen with fixed-width font and the :I format -by inspecting the generated hex file or by using, eg, -U flash:r:-:I. -Patterns in flash memory are executable and represent benign AVR code, ie, -no I/O memory access. Choose a fixed seed for reproducible results. +The patterns that are used for initialising memories as detailed above are +human-readable. These patterns can best be seen with a fixed-width font +and the :I format by inspecting the generated hex file or by using, eg, -U +flash:r:-:I to dump the patterns on screen. eeprom, userrow/usersig and +bootrow memories are filled with pangrams such as The quick brown fox +jumps over the lazy dog. Choose a fixed seed for reproducible results. .It Ar init= Shortcut for -x init -x seed= (see below) .It Ar random -Initialise memories with random code and values. Flash memory will be -randomly configured with respect to bootloader, data and code length. -Random code in flash will be benign, that is, not accessing I/O memories, -SRAM or flash. Choose a fixed seed for reproducible results. +Initialise flash with random opcodes and, if applicable, random +application table data. The sernum memory, if it exists, will be +initialised with a random upper-letter sequence. Other memories are +initialised with a random sequence of at-signs and spaces. Choose a fixed +seed for reproducible results. .It Ar random= Shortcut for -x random -x seed= +.It Ar holes +Put holes into larger memories, ie, longer sequences of 0xff, and add +small islands of code or data. Some of these holes can pose problems for +programmers that do not anticipate them. As such these can be used for +hardened testing, which is the main purpose of the dryrun programmers. .It Ar seed= Seed random number generator with ; the default is time(NULL). Setting this option with a fixed n > 0 will make the random choices diff --git a/src/doc/avrdude.texi b/src/doc/avrdude.texi index e1b3e7fb..22ec5b4f 100644 --- a/src/doc/avrdude.texi +++ b/src/doc/avrdude.texi @@ -1363,6 +1363,7 @@ with @code{T}; @code{sernum} with the downward letter sequence @code{UTSRQP...}; and the volatile @code{io} memory with reset values if known, @code{0x00} otherwise. +@cindex benign code If either the @code{init} or @code{random} parameters are set, then the @code{flash} memory is randomly configured in terms of bootloader sections, code and application data sections, and the fuses updated @@ -1370,7 +1371,7 @@ accordingly. In either case, @code{flash} (including ATxmega submemories of @code{application}, @code{apptable} and @code{boot}), @code{eeprom}, and all other existing memories such as @code{prodsig}/@code{sigrow}, @code{userrow}/@code{usersig} and @code{bootrow} are updated with random -data. @code{flash} is always initialised with benign code, that is its +data. @code{flash} is always initialised with benign code, that is, its opcodes will not access I/O memories, SRAM or flash. If none of @code{init} or @code{random} parameters are set, these memories @@ -1398,15 +1399,22 @@ Shortcut for @code{-x init -x seed=@var{n}} (see below) @cindex @code{flash} @item random Initialise @code{flash} with random opcodes and, if applicable, random -application table data. Random code in flash will be benign, that is, not -accessing I/O memories, SRAM or flash. The @code{sernum} memory, if it -exists, will be initialised with a random upper-letter sequence. Other -memories are initialised with a random sequence of at-signs and spaces. -Choose a fixed seed for reproducible results. +application table data. The @code{sernum} memory, if it exists, will be +initialised with a random upper-letter sequence. Other memories are +initialised with a random sequence of at-signs and spaces. Choose a fixed +seed for reproducible results. +@cindex @code{flash} @item random=@var{n} Shortcut for @code{-x random -x seed=@var{n}} +@cindex @code{flash} +@item holes +Put holes into larger memories, ie, longer sequences of @code{0xff}, and +add small islands of code or data. Some of these holes can pose problems +for programmers that do not anticipate them. As such these can be used for +hardened testing, which is the main purpose of the dryrun programmers. + @item seed=@var{n} Seed random number generator with @var{n}; the default is @code{time(NULL)}. Setting this option with a fixed positive @var{n} will diff --git a/src/dryrun_part.c b/src/dryrun_part.c index 4a91e241..774484a6 100644 --- a/src/dryrun_part.c +++ b/src/dryrun_part.c @@ -23,28 +23,43 @@ * Returns a duplicate of the part structure that is known from the * configuration file under the given id (eg, m328p). Lock and fuse * memories are initialised with with factory values as far as known, 0xff - * otherwise; the signature memory is set from the configuration file; the - * calibration memory is filled with U (for uncalibrated), osc16err with e - * and osc20err with E (for error), osccal16 with o and osccal20 with O, - * sib with S, tempsense with T, sernum with the downward letter sequence - * UTSRQP..., and the volatile io memory with reset values if known, 0x00 + * otherwise. The signature memory is set from the configuration file; the + * calibration memory is filled with U (for uncalibrated); osc16err with e + * and osc20err with E (for error); osccal16 with o and osccal20 with O; + * sib with S; tempsense with T; sernum with the downward letter sequence + * UTSRQP...; and the volatile io memory with reset values if known, 0x00 * otherwise. * - * If either init or random are set, then the flash memory is randomly - * configured in terms of bootloader sections, code and application data - * sections, and the fuses updated accordingly. In either case, flash - * (including ATxmega submemories of application, apptable and boot), - * eeprom, userrow and bootrow memories, if any, are updated with random - * data. If random is set then random valid opcodes of the AVR-model are - * chosen for flash; the code is meant to be benign, that is, it will not - * access I/O memories, SRAM or flash. The other memories are filled with - * random sequences of @ and spaces. If init is set then the flash opcodes - * are restricted to those forming a human-readable ASCII banner that is - * visible with a terminal dump and fixed-width fonts. Other memories are - * initialised with pangrams such as The quick brown fox jumps over the - * lazy dog. Init and random are not meant to be both set at the same - * time. If random is set then the sernum memory, if it exists, will be - * initialised with a random upper-letter sequence. + * If either the init or random parameters are set, then the flash memory + * is randomly configured in terms of bootloader sections, code and + * application data sections, and the fuses updated accordingly. In either + * case, flash (including ATxmega submemories of application, apptable and + * boot), eeprom, and all other existing memories such as prodsig/sigrow, + * userrow/usersig and bootrow are updated with random data. Flash is + * always initialised with benign code, that is its opcodes will not + * access I/O memories, SRAM or flash. + * + * If none of init or random parameters are set, these memories are + * initialised with 0xff. Note that init and random are not meant to be + * both set at the same time. + * + * If init is set then, the patterns that are used for initialising + * memories as detailed above are human-readable. These patterns can best + * be seen with a fixed-width font and the :I format by inspecting the + * generated hex file or by using, eg, -U flash:r:-:I to dump the patterns + * on screen. eeprom, userrow/usersig and bootrow memories are filled with + * pangrams such as The quick brown fox jumps over the lazy dog. + * + * If random is set flash is initialised with random opcodes and, if + * applicable, random application table data. The sernum memory, if it + * exists, will be initialised with a random upper-letter sequence. Other + * memories are initialised with a random sequence of at-signs and spaces. + * + * If holes is set then dryrun_parts() puts holes into larger memories, + * ie, longer sequences of 0xff, and adds small islands of code or data. + * Some of these holes can pose problems for programmers that do not + * anticipate them. As such these can be used for hardened testing, which + * is the main purpose of the dryrun programmers * * The argument seed, if positive, initialises the seed of the pseudo * random number generator. If seed is zero, time(NULL) is used for