We have detected your current browser version is not the latest one. Xilinx.com uses the latest web technologies to bring you the best online experience possible. Please upgrade to a Xilinx.com supported browser:Chrome, Firefox, Internet Explorer 11, Safari. Thank you!

AR# 15346

8.1i BSDLAnno - What is BSDLAnno? How do I use it to create a post-configuration BSDL file?


Keywords: Boundary Scan

This Answer Record provides documentation information for BSDLAnno.


Modified September, 2006:
- Updated supported architectures
- Updated description of how BSDLAnno modifies files
- Updated Known Issues

The BSDLAnno utility is compatible with the following families:
Virtex, Virtex-E, Virtex-II, Virtex-II Pro, Virtex-II Pro X, Virtex-4, Virtex-5, Spartan-II, Spartan-IIE, Spartan-3, Spartan-3E, XC9500, XC9500XL, XC9500XV, XPLA3 (CoolRunner), XBR (CoolRunner-II)

This document contains the following sections:
- BSDLAnno Overview
- BSDLAnno Syntax
- BSDLAnno Input Files
- BSDLAnno Output Files
- BSDLAnno Options
- BSDL File Composition and Overview
- Boundary Scan Behavior in Configured Xilinx Devices
- Known Issues and Limitations for BSDLAnno 5.1i

BSDLAnno Overview
The Boundary Scan Description Language is defined by IEEE specification 1149.1 as "a common way of defining device boundary scan architecture." Xilinx provides both 1149.1 and 1532 (for applicable devices only) BSDL files that describe pre-configuration boundary scan architecture. For most Xilinx device families, the boundary scan architecture changes after the device is configured because the boundary scan registers sit behind the I/O buffer and sense amplifier:

BSCAN Register -> IO buffer/sense amp -> PAD

The hardware is arranged in this way so that the boundary scan logic operates at the I/O standard specified by the design. This allows boundary scan testing across the entire range of available I/O standards.

Because certain connections between the boundary scan registers and pad might change, the boundary scan architecture is effectively changed when the device is configured. These changes often need to be communicated to the boundary scan tester through a post-configuration BSDL file. If the changes to the boundary scan architecture are not reflected in the BSDL file, boundary scan tests might fail.

Xilinx now offers the BSDLAnno utility to automatically modify the BSDL file for post-configuration interconnect testing. BSDLAnno obtains the necessary design information from either the routed ".ncd" file (FPGAs) or the "design.pnx" file (CPLDs), and generates a BSDL file that reflects the post-configuration boundary scan architecture of the device.

BSDLAnno Syntax
Use the following syntax to generate a post-configuration BSDL file with BSDLAnno:

bsdlanno [options] infile outfile[.bsd]

The infile is the design source file for the specified design. For FPGA designs, the "infile" is the routed (post-PAR) NCD file, and it must have an ".ncd" extension. For CPLD designs, the "infile" is the "design.pnx" file.

The outfile[.bsd] is the destination for the design-specific BSDL file. The ".bsd" extension is optional. The length of the BSDL file name, including the ".bsd" extension, cannot exceed 24 characters.

For example:
bsdlanno -s IEEE1149 design.ncd xcv50e_pq240_design.bsd

BSDLAnno Input Files
BSDLAnno requires two input files to generate a post-configuration BSDL file:
- Pre-configuration BSDL file that is automatically read from the Xilinx installation area
- Either the routed ".ncd" file (FPGAs) or the ".pnx" file (CPLDs) , which is specified by you as the infile

BSDLAnno Output Files
The output from BSDLAnno is an ASCII (text) formatted BSDL file that has been modified to reflect signal directionality (input/output/bidirectional), unused I/Os, and other design-specific boundary scan behavior.

BSDLAnno Options
This section provides information on the BSDLAnno command line options.

[-s IEEE1149|IEEE1532]

"-s" indicates which version of the BSDL file to modify. (Most users require the IEEE1149 file.)

BSDLAnno Modifications
Manufacturers of JTAG-compliant devices must provide BSDL files for those devices. BSDL files describe the Boundary Scan architecture of a JTAG-compliant device, and are written in a subset of VHDL. The five main parts of an IEEE 1149.1 BSDL file follow, along with an explanation of how BSDLAnno modifies each section.

1. Entity Declaration
The Entity Declaration is a VHDL construct that is used to identify the name of the device that is described by the BSDL file.

For example (from the "xcv50e_pq240.bsd" file):
entity XCV50E_PQ240 is

BSDLAnno changes the Entity Declaration to avoid name collisions. The new Entity Declaration matches the design name in the "input .ncd" or ".pnx" file.

2. Generic Parameter
The "Generic" parameter specifies which package is described by the BSDL file.

For example (from the "xcv50e_pq240.bsd" file):
generic (PHYSICAL_PIN_MAP : string := "PQ240" );

BSDLAnno does not modify the Generic Parameter.

3. Logical Port Description
The Logical Port Description lists all I/Os on a device and states whether the pin is an input (in bit;), output (inout bit;), bidirectional (inout bit;), or unavailable for boundary scan (linkage bit;). Pins configured as outputs are described as "inout" because the input boundary scan cell remains connected even when the pin is used only as an output. Describing the output as an "inout" reflects the actual boundary scan capability of the device and allows for greater test coverage.

Not all I/Os on the die are available (or "bonded") in all packages. Unbonded I/Os are defined in the pre-configuration BSDL file as "linkage" bits.

For example (from the "xcv50e_pq240.bsd" file):
port (
CCLK_P179: inout bit;
DONE_P120: inout bit;
GCK0_P92: in bit;
GCK1_P89: in bit;
GCK2_P210: in bit;
GCK3_P213: in bit;
GND: linkage bit_vector (1 to 32);
INIT_P123: inout bit; -- PAD96
IO_P3: inout bit; -- PAD191
IO_P4: inout bit; -- PAD190
IO_P5: inout bit; -- PAD189
IO_P6: inout bit; -- PAD188

BSDLAnno modifies the Logical Port Description so that it matches the capabilities of the boundary scan circuitry after configuration. Modifications are made as follows:

- Dedicated pins (JTAG, mode, done, etc.) are not modified.
- Pins defined by you as bidirectional are left as "inout bit;".
- Pins defined by you as inputs are changed to "in bit;".
- Pins defined by you as outputs are changed to "inout bit;".
- Unused pins remains to be "inout bit;".
- The N-side of differential pairs is changed to "linkage bit;".

4. Package Pin-mapping
The Package Pin-mapping shows how the pads on the device die are wired to the pins on the device package.

For example (from the "xcv50e_pq240.bsd" file):
"CCLK_P179:P179," &
"DONE_P120:P120," &
"GCK0_P92:P92," &
"GCK1_P89:P89," &
"GCK2_P210:P210," &
"GCK3_P213:P213," &
"GND:(P1,P8,P14,P22,P29,P37,P45,P51,P59,P69," &
"P75,P83,P91,P98,P106,P112,P119,P129,P135,P143," &
"P151,P158,P166,P172,P182,P190,P196,P204,P211,P219," &
"P227,P233)," &
"INIT_P123:P123," &
"IO_P3:P3," &
"IO_P4:P4," &
"IO_P5:P5," &
"IO_P6:P6," &

BSDLAnno does not modify the Package Pin-mapping.

5. USE Statements
The USE statement calls VHDL packages that contain attributes, types, constants, etc. that are referenced in the BSDL File.

For example (from the "xcv50e_pq240.bsd" file):
use STD_1149_1_1994.all;

BSDLAnno does not modify USE statements.

6. Scan Port Identification
The Scan Port Identification identifies the following JTAG pins: TDI, TDO, TMS, TCK and TRST (if used). (TRST is an optional JTAG pin that is not used by Xilinx devices.)

For example (from the "xcv50e_pq240.bsd" file):
attribute TAP_SCAN_IN of TDI : signal is true;
attribute TAP_SCAN_MODE of TMS : signal is true;
attribute TAP_SCAN_OUT of TDO : signal is true;
attribute TAP_SCAN_CLOCK of TCK : signal is (33.0e6, BOTH);

BSDLAnno does not modify the Scan Port Identification.

7. TAP Description
The TAP Description provides additional information on the device's JTAG logic. Included are the Instruction Register length, Instruction Opcodes, device IDCODE, etc. These characteristics are device-specific and might vary widely from device to device.

For example (from the "xcv50e_pq240.bsd" file):
attribute COMPLIANCE_PATTERNS of XCV50E_PQ240 : entity is
attribute INSTRUCTION_LENGTH of XCV50E_PQ240 : entity is 5;
attribute INSTRUCTION_OPCODE of XCV50E_PQ240 : entity is
attribute INSTRUCTION_CAPTURE of XCV50E_PQ240 : entity is "XXX01";
attribute IDCODE_REGISTER of XCV50E_PQ240 : entity is

BSDLAnno does not modify the TAP Description.

8. Boundary Register Description
The Boundary Register Description gives the structure of the Boundary Scan cells on the device. Each pin on a device may have up to three Boundary Scan cells, with each cell consisting of a register and a latch. Boundary Scan test vectors are loaded into or scanned from these registers.

For example (from the "xcv50e_pq240.bsd" file):
attribute BOUNDARY_REGISTER of XCV50E_PQ240 : entity is
-- cellnum (type, port, function, safe[, ccell, disval, disrslt])
" 0 (BC_1, *, controlr, 1)," &
" 1 (BC_1, IO_P184, output3, X, 0, 1, PULL0)," & -- PAD48
" 2 (BC_1, IO_P184, input, X)," & -- PAD48

Every IOB has three Boundary Scan registers associated with it: Control, Output, and Input. BSDLAnno modifies the Boundary Register Description as described below:

BSDL File modifications for single-ended pins
If pin 57 has been configured as a single-ended 3-state output pin, no code modifications are required:

-- TRISTATE OUTPUT PIN (three state output with an input component)
" 9 (BC_1, *, controlr, 1)," &
" 10 (BC_1, PAD57, output3, X, 9, 1, Z)," &
" 11 (BC_1, PAD57, input, X)," &

If pin 57 is configured as a single-ended input, modify as follows:
" 9 (BC_1, *, internal, 1)," &
" 10 (BC_1, *, internal, X)," &
" 11 (BC_1, PAD57, input, X)," &

If pin 57 is configured as a single-ended output, it is treated as a single-ended bidirectional pin:
" 9 (BC_1, *, controlr, 1)," &
" 10 (BC_1, PAD57, output3, X, 9, 1, Z)," &
" 11 (BC_1, PAD57, input, X)," &

If pin 57 is unconfigured or not used in the design, do not modify:
" 9 (BC_1, *, controlr, 1)," &
" 10 (BC_1, PAD57, output3, X, 9, 1, PULL0)," &
" 11 (BC_1, PAD57, input, X)," &

The only modification that is made to single-ended pins is when the pin is configured as an input. In this case, the boundary scan logic is disconnected from the output driver and is unable to drive out on the pin. When a pin is configured as an output, the boundary scan input register remains connected to that pin. As a result, the boundary scan logic has the same capabilities as if the pin were configured as a bidirectional pin.

BSDL File Modifications for Differential Pins
If pin 57 is configured as a bidirectional, 3-state output, or output p-side differential pin, modify as follows:
" 9 (BC_1, *, controlr, 1)," &
" 10 (BC_1, PAD57, output3, X, 9, 1, Z)," &
" 11 (BC_1, PAD57, input, X)," &

If pin 57 is configured as a p-side differential input pin, modify as follows:
" 9 (BC_1, *, internal, 1)," &
" 10 (BC_1, *, internal, X)," &
" 11 (BC_1, PAD57, input, X)," &

If pin 57 is configured as an n-side differential pin (all types: input, output, 3-state output, and bidirectional), modify as follows:
" 9 (BC_1, *, internal, 1)," &
" 10 (BC_1, *, internal, X)," &
" 11 (BC_1, *, internal, X)," &

Most boundary scan devices use only three boundary scan registers for each differential pair. Most devices do not offer direct boundary scan control over each individual pin, but rather over the two-pin pair. This makes sense when you consider that the two pins are transmitting only one bit of information, hence, only one input, output, and control register is needed. Confusion arises over how differential pins are handled in Xilinx devices, because there are three boundary scan cells for each pin, or six registers for the differential pair. The N-side registers remain in the boundary scan register but are not connected to the pin in any way, which is why the N-side registers are listed as "internal" registers in the post-configuration BSDL file. Because the boundary registers sit behind the output buffer and input sense amp, the P-side registers also control the behavior of the N-side pin. For example, when a value is placed in the P-side output scan register and the output is enabled, the inverse value is driven onto the N-side pin by the output driver. This is independent from the Boundary Scan logic.

In summary, all interactions with differential pin pairs are handled by the boundary scan cells connected to the P-side pin. To capture the value on a differential pair, scan the P-side input register. To drive a value on a differential pair, shift the value into the P-side output register. The values in the N-side scan registers have no effect on that pin.

9. Modifications to the DESIGN_WARNING Section
BSDLAnno adds the following DESIGN_WARNING to the BSDL file:
"This BSDL file has been modified to reflect post-configuration"&
behavior by BSDLAnno. BSDLAnno does not modify the USER1,"&
USER2, or USERCODE registers. For details on the features and" &
limitations of BSDLAnno, please consult the Xilinx Development" &
System Reference Guide.";

10. Header Comments
Remove the "beta" designation from the header comments added by BSDLAnno to read as follows:
-- BSDLAnno Post-Configuration File for design <entity name>
-- BSDLAnno <BSDLAnno version number>

Post-Configuration Boundary Scan Behavior
BSDL files provided by Xilinx reflect the Boundary Scan behavior of an unconfigured device.
- After configuration, the boundary scan behavior of a device may change. I/O pins that were bidirectional before configuration may now be input-only.
- Boundary Scan test vectors are typically derived from BSDL files; therefore, if boundary scan tests are going to be performed on a configured Xilinx device, the BSDL file should be modified to reflect the device's configured Boundary Scan behavior.
- Whenever possible, boundary scan tests should be performed on an unconfigured Xilinx device. Unconfigured devices allow for better test coverage, because all I/Os are available for bidirectional scan vectors.

Boundary Scan tests on configured Xilinx devices should only be performed under the following circumstances:
- When configuration cannot be prevented
- When differential signaling standards are used (unless the differential signal(s) are located between Xilinx devices, in which case both devices can be tested pre-configuration. Each side of the differential pair will behave as a single-ended signal.)

Known Issues, Limitations, and Notes for 5.1i BSDLAnno

1. Handling of the N-side of differential pairs needs improvement.
An earlier version of this document stated that, "BSDLAnno currently removes the N-side of differential pairs from the Boundary Register. A future version of BSDLAnno will be modified to annotate the differential pair in the BSDL file as a "grouped port" and to include N-side differential pins in the Boundary Register, per IEEE 1149.1 section B.8.8."

Xilinx has reversed the decision on this point. Xilinx believes that the current handling of differential pin pairs is the best way to describe the BSCAN architecture of a configured Xilinx device.

The argument against marking the N-side as a linkage bit is that you lose the ability to individually test that pin. However, the BSCAN cells on Xilinx N-side pins get disconnected from the pin, so there is no use for these cells when the pin is configured as the N-side of a differential pair. Therefore, BSDLAnno correctly marks these cells as "linkage." The confusion arises because it is very uncommon for the N-side pin of a differential pair to have its own boundary scan cells--most devices use a single set of boundary scan cells (input, output, 3-state) for each differential pair. Marking the N-side as "linkage" results in one set of BSCAN cells for the pair of pins, which is exactly what most devices with differential pairs offer. To control the differential pair, you need access to the P-side BSCAN cells, which is what the modifications made by BSDLAnno provide.

2. User-defined Boundary Scan registers (USER1 and USER2 registers) are not annotated.
BSDLAnno cannot annotate user-defined boundary scan registers in the post-configuration BSDL file. There are no plans to add this functionality.

3. Control register "safe" values are not handled correctly.
Please see (Xilinx Answer 15419) for more information.

4. Incorrect modification of Boundary Scan cell types
BSDLAnno incorrectly modifies the boundary scan cell type to BC_1 in all cases. BSDLAnno should not change the cell type. To correct this problem, check the unmodified BSDL file to determine what the correct cell type is, then perform a "find and replace" with a text editor to change all instances of BC_1 to the correct cell type.

5. Annotation of pin directionality
The treatment of configured pin directionality is the subject of some debate. For example, BSDLAnno does not treat pins that are configured as outputs as outputs--they are treated as bidirectional pins because this reflects the true boundary scan structure that is available in the configured device. This might be problematic for some customers who expect the directionality of the circuit as described in the FPGA design to be reflected in the BSDL file. However, if BSDLAnno were to treat outputs simply as outputs (rather than as bidirectionals), it would reduce the overall test coverage, which would be problematic for other customers.

The mission of BSDLAnno is to reflect the true boundary scan structure in a configured Xilinx device to maximize test coverage. Although this might be inconvenient for some customers, Xilinx believes that this serves the greater good by allowing the full use of the device's boundary scan resources.
AR# 15346
Date Created 08/06/2002
Last Updated 09/12/2006
Status Active
Type General Article