FPGA DEVICES · ENGINEERING · SOURCING Source-linked information. Clear project requirements.

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

Target matchTarget matchZero: stopOne: check identitySeveral: stopRead with the conditions in this section.
Target match: Zero: stop / One: check identity / Several: stop.
ZedBoard with separate USB connectors, programming labels and board revision marking
ZedBoard photographed by Ordercrazy, CC0. The visible connector and board labels illustrate physical identification. This is a Zynq board, not an Artix-7 wiring reference or a tested lab setup.

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

Job stagesJob stagesPreparationProgrammingAcceptanceRead with the conditions in this section.
Job stages: Preparation / Programming / 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

Failure recordFailure recordOriginal errorCleanup resultNonzero failure exitRead with the conditions in this section.
Failure record: Original error / Cleanup result / Nonzero failure exit.

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 0

The 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

Test boundariesTest boundariesMissing fileAmbiguous targetInterrupted operationRead with the conditions in this section.
Test boundaries: Missing file / Ambiguous target / Interrupted operation.

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

Release identityRelease identityScript versionJob versionTest recordRead with the conditions in this section.
Release identity: Script version / Job version / Test record.

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.

Review-item highlight: Release identity

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.

Back to Tutorials →

Related evidence and next tasks

Continue the task with the relevant source scope. These reading paths do not establish interchangeability or current supply.

Source addresses and citation trail

Full source addresses are retained below. Read each citation with its document revision, page, table and applicability conditions above.

  1. https://commons.wikimedia.org/wiki/File:Embedded_World_2014_Xilinx_ZedBoard_Developer_Board.jpg
  2. https://creativecommons.org/publicdomain/zero/1.0/
  3. https://docs.amd.com/r/en-US/ug894-vivado-tcl-scripting/Handling-Tcl-Errors
  4. https://docs.amd.com/r/2024.1-English/ug908-vivado-programming-debugging/Opening-a-New-Hardware-Target
  5. https://docs.amd.com/r/2024.1-English/ug908-vivado-programming-debugging/Programming-a-Configuration-Memory-Device
  6. https://docs.amd.com/r/2024.1-English/ug835-vivado-tcl-commands/write_cfgmem