U-Boot env import: Bound Replacement with an Explicit Variable List

A provisioning snapshot contains two configuration variables.
Importing it changes those variables but leaves an obsolete value
behind. Adding deletion mode fixes that omission, then unexpectedly
removes unrelated settings. The problem is not necessarily malformed
input: import mode and the selected variable list define different
replacement scopes.

This walkthrough uses upstream U-Boot v2025.01 with
CONFIG_CMD_IMPORTENV enabled. It proposes tests with harmless marker
variables in a disposable environment. It does not instruct a technician
to replace a production boot environment or claim that any import has
been executed. For a Buildroot-based product, trace these mechanisms in
the U-Boot revision and board configuration selected by that product;
Buildroot integration does not replace that check.

Write the intended change as
a set

Before choosing command options, list which variables the operation
is allowed to affect. Separate three categories: variables present in
the input, variables intentionally removed by omission, and variables
outside the operation’s responsibility. This small inventory is more
useful than describing the input as a “complete configuration” without
defining complete for whom.

Consider invented markers demo_mode,
demo_rate and other_owner. The current
environment contains all three; a new snapshot contains only demo_mode.
If the operation owns both demo variables, omission of demo_rate might
mean deletion. If it owns only demo_mode, the same omission must not
alter demo_rate. The file contents alone cannot express which
interpretation the operator intended.

Compare merge and
replacement behavior

The env
command reference documents a variable list that restricts which
names are imported. Without a list, the whole input is considered.
Deletion mode adds another dimension: without selected names it clears
existing environment state before import; with selected names it deletes
listed variables that are absent from the input.

The tagged command
implementation passes H_NOCLEAR when deletion is disabled and
forwards the selected-name list to the importer. Review that call rather
than assuming that a snapshot import always means wholesale replacement
or always means a merge.

A practical review should therefore name both decisions: the allowed
set and the omission policy. “Import these settings” is incomplete when
absent keys have consequences. Put the intended behavior in a fixture so
a future script change cannot silently broaden it.

Keep input framing explicit

The command accepts different formats, and text input needs a
specified length or proper termination. For a script that has already
loaded a file into memory, preserve the actual file length and the load
result. Do not replace that evidence with a guessed buffer size or an
address copied from an unrelated example.

Text created on another system may also use CRLF line endings. The
documented -r behavior applies with text mode. Treat
line-ending handling as a separate fixture from variable-selection
behavior; changing both at once makes a surprising result harder to
explain.

In a review, identify the producer of the input, the expected format
and the exact parser invocation. An extension such as .txt
is not a framing guarantee. Check the bytes supplied to the importer,
especially when a transfer utility or generation script can add
termination, padding or encoding changes.

Do not
confuse restricted names with trusted content

An explicit list limits the names considered by that invocation. It
does not authenticate the input or make every allowed value safe. A
permitted boot-related variable can still contain an inappropriate
command, device name or address. Keep validation of values and authority
to change them as separate product requirements.

Similarly, a successful import does not mean the environment was
saved. Review the persistence step independently and avoid adding an
unconditional save merely to make a test survive reboot. The distinction
lets the engineer inspect a proposed change before committing it to the
selected storage backend.

Do not assume failed imports automatically restore all previous
state. If the workflow needs transactional behavior, qualify the failure
paths and design an explicit recovery strategy. This article establishes
the documented selection semantics, not an atomic-update guarantee.

Build a four-case marker
test

Use a recoverable test environment and names that no boot script
consumes. Record the initial marker values and preserve the input bytes.
Then compare four invocations with the same logical input:

1. Import without deletion and without a selected-name list.
2. Import with deletion and without a selected-name list.
3. Import without deletion while selecting both demo variables.
4. Import with deletion while selecting both demo variables.

For each case, inspect demo_mode, demo_rate and other_owner. Write
the expected result before executing the test. The contrast between a
missing selected name and an unselected name is the central observation;
do not hide it in a transcript containing hundreds of unrelated
variables.

Repeat the relevant cases with a bounded input length, supported
line-ending handling and an intentionally rejected input. Preserve the
return result and resulting in-memory state. Keep persistence disabled
during these semantic tests so each run can begin from the same
controlled baseline.

Put the boundary
in the maintenance interface

A maintenance tool should explain the scope of its operation before
applying it. Show the allowed names, new values and intended deletions
in a reviewable form. Distinguish a component-owned snapshot from a
complete board environment. That makes it harder for a future caller to
accidentally reuse a broad replacement mode for a narrow update.

The final regression should assert both positive and negative
effects: the intended value changed, the intended omission was handled
correctly, and unrelated state survived. A test that checks only the new
value can pass while the operation erases another component’s
configuration. Bounded replacement is useful precisely because its
unchanged state is part of the contract.