Tutorials
Vivado Batch Programming in Tcl: Fail Clearly and Keep Logs
Published · Updated
A batch programmer must fail in a way the calling process can recognize. A script that catches an error, prints it and then returns success can mislead a production runner. Build the job around explicit target selection, staged results and a nonzero failure exit before adding throughput optimizations.
Make target selection unambiguous

Require an expected target identity, device identity, tool release and programming file. If discovery returns no match, stop. If it returns several matches, stop and ask for a more specific selection. Taking the first object is not a reliable way to choose a board in a shared rack.
Keep the selected cable and chain position in the job record. A successful operation against the wrong board remains a failed job. The preflight should make that distinction possible before any programming command is issued.
Before a batch job can choose safely, identify the programming target and keep its selection rule.
Separate preparation, programming and acceptance
Preparation checks file availability, target selection and the job's required metadata. Programming performs the explicitly approved operation. Acceptance checks the relevant observations after that operation. Give each stage a separate outcome rather than using one final success message.
For an initial script, restrict the scope to a documented volatile JTAG configuration workflow. Flash erase, security provisioning and irreversible device settings require different procedures and should not appear as convenient default options.
Do not call a preparation-only run a hardware validation. A dry run can show which target rule and file would be used; it cannot prove that the device will configure or that the application will work.
If discovery returns a different FPGA, check device identity; do not merely accept the first object.
Return failure to the calling process
Use Tcl error handling to retain the original failure and propagate it to the process that launched the script. AMD's UG894 discussion explains catch and error propagation. The exact handling of every hardware command still needs to be checked against the selected Vivado release.
Clean up resources without replacing the primary error with a secondary cleanup failure. A useful log contains the stage, selected target, image identity, original message and final process result. Never put access credentials or device secrets in a public example log.
Check command flags individually. A quiet option can change what the caller observes; its behavior is not necessarily identical across commands. Test a known failure and inspect the actual process exit status, not just text printed by the script.
This small Tcl example makes the failure behavior visible without opening hardware. The program stage deliberately raises an error. Running it with Tcl returns failure, even when cleanup also fails; changing the hardware body belongs in a separately reviewed job.
set stage preflight
set failed [catch {
# Insert reviewed preflight checks here.
set stage program
error "demonstration operation failure"
} message options]
set cleanup_failed [catch {
# Insert release-specific cleanup here.
} cleanup_message]
if {$failed} {
puts stderr [list stage $stage result failed message $message]
if {$cleanup_failed} {
puts stderr [list cleanup failed message $cleanup_message]
}
exit 1
}
if {$cleanup_failed} {
puts stderr [list cleanup failed message $cleanup_message]
exit 1
}
puts [list result completed acceptance pending]
exit 0The list construction keeps spaces in a message from changing its field boundaries. This is an error-handling demonstration, not a ready-to-run Vivado programming job. The worksheet below exports job requirements and expected failure cases; it does not execute this code.
After configuration, verify runtime identity using a fresh application observation.
Test failures before using the job
Exercise a missing file, zero target matches, multiple matches and an unexpected device identity before testing a permitted programming operation. Then test an operation failure and an interrupted session under controlled conditions. Preserve the expected and observed result for each case.
Keep mocked control-flow tests distinct from hardware execution. A simulated exception can validate the error path without establishing how a specific cable or board behaves during a disconnect.
Add fixture traceability to the per-board record so a failure can be tied to a physical station.
Keep the script and test record together
Version the script with its job schema, README, supported tool release and test record. Give the release package an identity that can be tied to each board's result. A revised script can change production behavior even when the bitstream is unchanged.
A runtime build read belongs in the acceptance record when the design supports it. It is separate from the file identity and programming log. Define what happens when that observation is unavailable instead of copying an expected value into the observed field.
Use the job worksheet to specify the preflight and failure criteria before implementing the hardware commands. It is a preparation aid, not an executable programming script. A downloadable hardware script should be released only with its actual validation record.
Technical references for this scope: AMD UG894 — Handling Tcl Errors(本次页面为 2026.1); AMD UG908 2024.1 — Opening a New Hardware Target; AMD UG908 2024.1 — Programming a Configuration Memory Device; AMD UG835 2024.1 — write_cfgmem.
Highlight the three review items
Each highlight marks one item to review, not elapsed hardware time. The static figure contains the same information.

Enable JavaScript for the local Batch-job preflight and log example. The article above provides the manual procedure; no data is submitted automatically.
Review and export your result before opening the engineering discussion entry. Attach the exported text yourself; opening the entry does not submit it.
Reference scope checked 15 November 2026. Calculations and conceptual diagrams describe the stated model. Commands and board behavior require validation in the actual tool and board environment.