UG111 (v14.5) March 20, 2013 [optional] UG111 (v14.5) March 20, 2013

Xilinx is disclosing this user guide, manual, release note, and/or specification (the "Documentation") to you solely for use in the development of designs to operate with Xilinx hardware devices. You may not reproduce, distribute, republish, download, display, post, or transmit the Documentation in any form or by any means including, but not limited to, electronic, mechanical, photocopying, recording, or otherwise, without the prior written consent of Xilinx. Xilinx expressly disclaims any liability arising out of your use of the Documentation. Xilinx reserves the right, at its sole discretion, to change the Documentation without notice at any time. Xilinx assumes no obligation to correct any errors contained in the Documentation, or to advise you of any corrections or updates. Xilinx expressly disclaims any liability in connection with technical support or assistance that may be provided to you in connection with the Information.

THE DOCUMENTATION IS DISCLOSED TO YOU "AS-IS" WITH NO WARRANTY OF ANY KIND. XILINX MAKES NO OTHER WARRANTIES, WHETHER EXPRESS, IMPLIED, OR STATUTORY, REGARDING THE DOCUMENTATION, INCLUDING ANY WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NONINFRINGEMENT OF THIRD-PARTY RIGHTS. IN NO EVENT WILL XILINX BE LIABLE FOR ANY CONSEQUENTIAL, INDIRECT, EXEMPLARY, SPECIAL, OR INCIDENTAL DAMAGES, INCLUDING ANY LOSS OF DATA OR LOST PROFITS, ARISING FROM YOUR USE OF THE DOCUMENTATION.

© Copyright 2002 - 2013 Xilinx, Inc. XILINX, the Xilinx logo, Virtex, Spartan, ISE, and other designated brands included herein are trademarks of Xilinx in the United States and other countries. All other trademarks are the property of their respective owners.

The following table shows the revision history for this document.

GDB Command Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193 Additional Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

This chapter describes the architecture of the embedded system tools and flows provided in the Xilinx® Embedded Development Kit (EDK) for developing systems based on the MicroBlaze™ embedded processors and the PowerPC® (405 and 440) processors.

The Xilinx Embedded Development Kit (EDK) system tools enable you to design a complete embedded processor system for implementation in a Xilinx FPGA device.

EDK is a component of the Integrated Software Environment (ISE®) Design Suite Embedded and System Editions. ISE is a Xilinx development system product that is required to implement designs into Xilinx programmable logic devices. EDK includes:

• The Xilinx Platform Studio (XPS) system tools suite with which you can develop your embedded processor hardware.
• The Software Development Kit (SDK), based on the Eclipse open-source framework, which you can use to develop your embedded software application. SDK is also available as a standalone program.
• Embedded processing Intellectual Property (IP) cores including processors and peripherals.

While the EDK environment supports creating and implementing designs, the recommended flow is to begin with an ISE project, then add an embedded processor source to the ISE project. EDK depends on ISE components to synthesize the microprocessor hardware design, to map that design to an FPGA target, and to generate and download the bitstream.

For information about ISE, refer to the ISE software documentation. For links to ISE documentation and other useful information see Appendix E, Additional Resources.

8

The tools provided with EDK are designed to assist in all phases of the embedded design process, as illustrated in Figure 1-1.

Figure 1-1: Embedded Design Process Flow

Xilinx FPGA technology allows you to customize the hardware logic in your processor subsystem. Such customization is not possible using standard off-the-shelf microprocessor or controller chips.

The term "Hardware platform" describes the flexible, embedded processing subsystem you are creating with Xilinx technology for your application needs.

The hardware platform consists of one or more processors and peripherals connected to the processor buses. XPS captures the hardware platform description in the Microprocessor Hardware Specification (MHS) file.

The MHS file is the principal source file that maintains the hardware platform description and represents in ASCII text the hardware components of your embedded system.

When the hardware platform description is complete, the hardware platform can be exported for use by SDK.

A board support package (BSP) is a collection of software drivers and, optionally, the operating system on which to build your application. The created software image contains only the portions of the Xilinx library you use in your embedded design. You can create multiple applications to run on the BSP.

The hardware platform must be imported into SDK prior to creation of software applications and BSP.

EDK provides both hardware and software verification tools. The following subsections describe the verification tools available for hardware and software.

To verify the correct functionality of your hardware platform, you can create a simulation model and run it on an Hardware Design Language (HDL) simulator. When simulating your system, the processor(s) execute your software programs. You can choose to create a behavioral, structural, or timing-accurate simulation model.

ISim (the ISE simulator) now supports simulation of embedded designs. When you create a project in ISE and add an embedded project source, you can launch ISim from within ISE. When no ISE project is used, you can launch the ISim software directly from within Platform Studio.

The following options are available for software verification:

• You can load your design on a supported development board and use a debugging tool to control the target processor.
• You can gauge the performance of your system by profiling the execution of your code.

When your hardware and software platforms are complete, you then create a configuration bitstream for the target FPGA device.

• For prototyping, download the bitstream along with any software you require to run on your embedded platform while connected to your host computer.
• For production, store your configuration bitstream and software in a non-volatile memory connected to the FPGA.

X-Ref Target - Figure 1-2

An embedded hardware platform typically consists of one or more processors, peripherals and memory blocks, interconnected via processor buses. It also has port connections to the outside world. Each of the processor cores (also referred to as pcores or processor IPs) has a number of parameters that you can adjust to customize its behavior. These parameters also define the address map of your peripherals and memories. XPS lets you select from various optional features; consequently, the FPGA needs only implement the subset of functionality required by your application.

Figure 1-2 provides an overview of the EDK architecture structure of how the tools operate together to create an embedded system.

The following table describes the tools and utilities supported in EDK. The subsections that follow provide an overview of each tool, with references to the chapters that contain additional information.

Table 1-1: EDK Tools and Utilities

Table 1-1: EDK Tools and Utilities (Cont'd)

Xilinx Platform Studio (XPS) offers the following features:

• Ability to add processor and peripheral cores, edit core parameters, and make bus and signal connections to generate an MHS file.
• Support for tools described in Table 1-1, page 11.
• Ability to generate and view a system block diagram and/or design report.
• Project management support.
• Process and tool flow dependency management.
• Ability to export hardware specification files for import into SDK.

For more information on files and their formats see the Platform Specification Format Reference Manual, which is linked in Additional Resources, page 281.

Refer to the Xilinx Platform Studio Help for details on using the XPS GUI. The following subsections describe the tool and utility components of XPS.

The Base System Builder (BSB) wizard helps you quickly build a working system. Some embedded design projects can be completed using the BSB wizard alone. For more complex projects, the BSB wizard provides a baseline system that you can then customize to complete your embedded design. The BSB wizard can generate a single-processor design for the supported processor types, and dual processor designs for MicroBlaze. For efficiency in project creation, Xilinx recommends using the BSB wizard in every scenario.

Based on the board you choose, the BSB wizard allows you to select and configure basic system elements such as processor type, debug interface, cache configuration, memory type and size, and peripheral selection. The BSB provides functional default values pre-selected in the wizard that you can modify as needed.

If your target development board is not available or not currently supported by the BSB wizard, you can select the Custom Board option instead of selecting a target board. Using this option, you can specify the individual hardware devices that you expect to have on your custom board. To run the generated system on a custom board, you enter the FPGA pin location constraints into the User Constraints File (UCF). If a supported target board is selected, the BSB wizard inserts these constraints into the UCF automatically.

For detailed information on using the features provided in the BSB wizard, see the Xilinx Platform Studio Help.

When you use the Base System Builder, it automatically creates a .bsb settings file upon exit that stores all of the selections that you made in that wizard session. When you load this file in a subsequent session, the wizard pre-loads all the interface selections that were stored in the file rather than the usual defaults. This option is useful if you have an existing design generated by the BSB and want to create another identical or similar to it.

Note: This feature is intended to help you create a new design that is similar to one in another project, not to modify an existing project. The BSB can only be invoked on a new project. After you have created a design, either with the wizard or manually, you cannot re-run the BSB to modify that design.

Figure X-Ref Target - Figure 1-3

The .bsb settings file stores only BSB wizard selections and does not reflect any changes made to the system outside of the BSB, such as adding or editing a peripheral in XPS or manually editing the Microprocessor Hardware Specification (MHS) file.

To use a .bsb settings file that you created in an earlier session of the Base System Builder:

• 1. Start the Base System Builder by selecting Create New Project Using Base System Builder from the Welcome page, or by selecting File > New BSB Project.
• 2. In the Create New XPS Project Using BSB Wizard screen, name your new project.
• 3. In the Select Existing .bsb Settings File field, browse to the saved .bsb settings file. When you select the file, details about the project display in the information window.

Figure 1-3: Viewing .bsb Settings File Information

The Create and Import Peripheral (CIP) wizard helps you create your own peripherals and import them into XPS-compliant repositories or projects.

In the Create mode, the CIP wizard creates templates that help you implement your peripheral without requiring detailed understanding of the bus protocols, naming conventions, or the formats of special interface files required by XPS. By referring to the examples in the template file and using various auxiliary design support files that are output by the wizard, you can start quickly on designing your custom logic.

In the Import mode, this tool creates the interface files and directory structures that are necessary to make your peripheral visible to the various tools in XPS. For the Import operation mode, it is assumed that you have followed the required XPS naming conventions. Once imported, your peripheral is available in the XPS peripherals library.

When you create or import a peripheral, XPS generates the Microprocessor Peripheral Definition (MPD) and Peripheral Analyze Order (PAO) files automatically:

• The MPD file defines the interface for the peripheral.
• The PAO file specifies to Platgen and Simgen what HDL files are required for compilation (synthesis or simulation) for the peripheral and in the order of those files.

For more information about MPD and PAO files, see the Platform Specification Format Reference Manual. A link to the document is available in Additional Resources, page 281. For detailed information on using the features provided in the CIP wizard, see the Xilinx Platform Studio Help.

The PsfUtility enables automatic generation of Microprocessor Peripheral Definition (MPD) files required to create an IP core compliant with EDK. Features provided by this tool can be used with the help of the CIP wizard.

The psf2Edward is a command line program that converts a Xilinx® Embedded Development Kit (EDK) project into Edward, an internal XML format, for use in external programs such as the Software Development Kit (SDK). See Chapter 3, "Psf2Edward Program."

The Configure Coprocessor wizard helps add and connect a coprocessor to a CPU. A coprocessor is a hardware module that implements a user-defined function and connects to the processor through an auxiliary bus. The coprocessor has a Fast Simplex Link (FSL) interface. For MicroBlaze™ processor systems, the coprocessor connects to the FSL interface. For PowerPC® processor systems, the coprocessor connects to the Auxiliary Processor Unit (APU) interface of the PowerPC processor through the fcb2fsl bridge.

For details on the Fast Simplex Link, refer to its data sheet and the MicroBlaze Processor Reference Guide (UG. For information about the APU bus, refer to the PowerPC reference guides. For information on the fcb2fsl bridge, refer to its data sheet. Links to document locations are available in the Additional Resources, page 281.

For instructions on using the Coprocessor wizard, refer to the Xilinx Platform Studio Help.

Platgen compiles the high-level description of your embedded processor system into HDL netlists that can be implemented in a target FPGA device.

Platgen:

• Reads the MHS file as its primary design input.
• Reads various processor core (pcore) hardware description files (MPD, PAO) from the XPS project and any user IP repository.
• Produces the top-level HDL design file for the embedded system that stitches together all the instances of parameterized pcores contained in the system. In the process, it resolves the high-level bus connections in the MHS into the actual signals required to interconnect the processors, peripherals and on-chip memories. (The system-level HDL netlist produced by Platgen is used as part of the FPGA implementation process.)
• Invokes the XST (Xilinx Synthesis Technology) compiler to synthesize each of the instantiated pcores.
• Generates the block RAM Memory Map (BMM) file which contains addresses and configuration of on-chip block RAM memories. This file is used later for initializing the block RAMs with software.

Chapter 4, "Platform Generator (Platgen)," provides a detailed description of the Platgen tool.

XPS includes a "no window" mode that lets you run from an operating system command line. Chapter 5, "Command Line Mode," provides information on the command line feature in XPS.

Bus Functional Model (BFM) simulation simplifies the verification of hardware components that attach to a bus. Chapter 6, "Bus Functional Model Simulation," provides information about BFM simulation.

The Debug Configuration wizard automates hardware and software platform debug configuration tasks common to most designs.

You can instantiate a ChipScope™ analyzer core to monitor the AMBA AXI4 interface, Processor Local Bus (PLB), or any other system-level signals. In addition, you can configure the parameters of an existing ChipScope core for hardware debugging. You can also provide JTAG-based virtual input and output.

To configure the software for debugging you can set the processor debug parameters. When co-debugging is enabled for a ChipScope core, you can set up mutual triggering between the software debugger and the hardware signals. The JTAG interface can be configured to transport UART signals to the Xilinx Microprocessor Debugger (XMD).

For detailed information on using the features provided in the Debug Configuration wizard, see the Xilinx Platform Studio Help.

The Simulation Platform Generation tool (Simgen) generates and configures various simulation models for the hardware. To generate a behavioral model, Simgen takes an MHS file as its primary design input. For generating structural or timing models, Simgen takes its primary design input from the post-synthesis or post-place-and-route design database, respectively. Simgen also reads the embedded application executable (ELF) file for each processor to initialize on-chip memory, thus allowing the modeled processor(s) to execute their software code during simulation.

Simgen also provides simulation models for external memory and has automated support to instantiate memory models in the simulation testbench and perform connection with the design under test. To compile memory model into the user library, Simgen also generates simulator-specific compilation/elaboration commands into respective helper/ setup scripts.

Refer to Chapter 7, Simulation Model Generator (Simgen) for more information.

The Software Development Kit (SDK) provides a development environment for software application projects. SDK is based on the Eclipse open-source standard. SDK has the following features:

• Can be installed independent of ISE and XPS with a small disk footprint.
• Supports development of software applications on single- or multi-processor systems.
• Imports the XPS-generated hardware platform definition.
• Supports development of software applications in a team environment.
• Ability to create and configure board support packages (BSPs) for third-party OS.
• Provides off-the-shelf sample software projects to test the hardware and software functionality.
• Has an easy GUI interface to generate linker scripts for software applications, program FPGA devices, and program parallel flash memory.
• Has feature-rich C/C++ code editor and compilation environment.
• Provides project management.
• Configures application builds and automates the make file generation.
• Supplies error navigation.
• Provides a well-integrated environment for seamless debugging and profiling of embedded targets.

For more information about SDK, see the Software Development ToolKit (SDK) Help.

Libgen configures libraries, device drivers, file systems, and interrupt handlers for the embedded processor system, creating a board support package (BSP). The BSP defines, for each processor, the drivers associated with the peripherals you include in your hardware platform, selected libraries, standard input and output devices, interrupt handler routines, and other related software features. Your SDK projects further define software applications to run on each processor, which are based on the BSP.

Taking libraries and drivers from the installation, along with any custom libraries and drivers for custom peripherals you provide, SDK is able to compile your applications, including libraries and drivers, into Executable Linked Format (ELF) files that are ready to run on your processor hardware platform.

Libgen reads selected libraries and processor core (pcore) software description files (Microprocessor Driver Definition (MDD) and driver code) from the EDK library and any user IP repository.

Refer to Chapter 8, Library Generator (Libgen) and the Xilinx Platform Studio Help for more information. For more information on libraries and device drivers, refer to the Xilinx software components documented in the OS and Libraries Document Collection. Links to the documentation are supplied in the Additional Resources, page 281.

GNU compiler tools (GCC) are called for compiling and linking application executables for each processor in the system. Processor-specific compilers are:

• The mb-gcc compiler for the MicroBlaze processor.
• The powerpc-eabi-gcc compiler for the PowerPC processor.

As shown in the embedded tools architectural overview (Figure 1-2, page 10):

• The compiler reads a set of C-code source and header files or assembler source files for the targeted processor.
• The linker combines the compiled applications with selected libraries and produces the executable file in ELF format. The linker also reads a linker script, which is either the default linker script generated by the tools or one that you have provided.

Refer to Chapter 9, "GNU Compiler Tools,", Chapter 11, "GNU Debugger," and Appendix A, GNU Utilities for more information about GNU compiler tools and utilities.

You can debug your program in software using an Instruction Set Simulator (ISS), or on a board that has a Xilinx FPGA loaded with your hardware bitstream. As shown in Figure 1-2, page 10, the Xilinx Microprocessor Debugger (XMD) utility reads the application executable ELF file. For debugging on a physical FPGA, XMD communicates over the same download cable as used to configure the FPGA with a bitstream. Refer to Chapter 10, "Xilinx Microprocessor Debugger (XMD)," for more information.

The GNU Debugger (GDB) is a powerful yet flexible tool that provides a unified interface for debugging and verifying MicroBlaze and PowerPC processor systems during various development phases.

GDB uses Xilinx Microprocessor Debugger (XMD) as the underlying engine to communicate to processor targets.

Refer to Chapter 11, "GNU Debugger," for more information.

The Compxlib utility compiles the EDK HDL-based simulation libraries using the tools provided by various simulator vendors. The Compxlib operates in both the GUI and batch modes. In the GUI mode, it allows you to compile the Xilinx libraries (in your ISE installation) using the libraries available in EDK.

For more information about Compxlib, see Simulation Models in Chapter 7 and the ISE Command Line Tools User Guide. For instructions on compiling simulation libraries, refer to the Xilinx Platform Studio Help.

The Bitinit tool initializes the on-chip block RAM memory connected to a processor with its software information. This utility reads hardware-only bitstream produced by the ISE tools (system.bit), and outputs a new bitstream (download.bit) which includes the embedded application executable (ELF) for each processor. The utility uses the BMM file, originally generated by Platgen and updated by the ISE tools with physical placement information on each block RAM in the FPGA. Internally, the Bitstream Initializer tool uses the Data2MEM utility to update the bitstream file.

See Figure 1-2, page 10, to see how the Bitinit tool fits into the overall system architecture. Refer to Chapter 12, "Bitstream Initializer (BitInit)," for more information.

XPS generates Xilinx System ACE configuration files from an FPGA bitstream, ELF, and data files. The generated ACE file can be used to configure the FPGA, initialize block RAM, initialize external memory with valid program or data, and bootup the processor in a production system. EDK provides a Tool Command Language (Tcl) script, genace.tcl, that uses XMD commands to generate ACE files. ACE files can be generated for PowerPC processors and MicroBlaze processors with Microprocessor Debug Module (MDM) systems. For more information see Chapter 13, "System ACE File Generator (GenACE)."

The Flash Memory Programming solution is designed to be generic and targets a wide variety of flash hardware and layouts. See Chapter 14, "Flash Memory Programming."

The Format Revision Tool (revup) updates an existing EDK project to the current version. The revup tool performs format changes only; it does not update your design.

Backups of existing files such as the project file (XMP), the MHS and MSS files, are performed before the format changes are applied.

The Version Management wizard appears automatically when an older project is opened in a newer version of EDK (for example, when a project created in EDK 10.1 is opened in version 11.3).

The Version Management wizard is invoked after format revision has been performed. The wizard provides information about any changes in Xilinx Processor IPs used in the design. If a new compatible version of an IP is available, then the wizard also prompts you to update to the new version. For instructions on using the Version Management wizard, see Chapter 15, "Version Management Tools (revup)," and the Xilinx Platform Studio Help.

For board designers not familiar with the IP-XACT tool, a board description can be captured in an ASCII text file similar to the Microprocessor Peripheral Definition (MPD) format that captures a pcore description. This MPD file is known as the Board-MPD. It includes a translation tool, MPDX, which generates the IP-XACT files on disk for the BSB repository. Chapter 16, Microprocessor Peripheral Definition Translation tool (MPDX) describes how to use this tool.

This chapter describes the features and the usage of the Platform Specification Utility (PsfUtility) tool that enables automatic generation of Microprocessor Peripheral Definition (MPD) files. MPD files are required to create IP peripherals that are compliant with the Embedded Development Kit (EDK). The Create and Import Peripheral (CIP) wizard in the Xilinx® Platform Studio (XPS) interface supports features provided by the PsfUtility for MPD file creation (recommended).

Table 2-1 lists the PsfUtility Syntax options and their descriptions.

1. Bus type mb (master that generates burst transactions) is valid for bus standard PLBv4.6 only.

Table 2-1: PsfUtility Syntax Options (Cont'd)

1. Bus type mb (master that generates burst transactions) is valid for bus standard PLBv4.6 only.

You can use the PsfUtility to create MPD specifications from the HDL specification of the core automatically. To create a peripheral and deliver it through EDK:

• 1. Code the IP in VHDL or Verilog using the required naming conventions for Bus, Clock, Reset, and Interrupt signals. These naming conventions are described in detail in "Conventions for Defining HDL Peripherals" on page 25. Note: Following these naming conventions enables the PsfUtility to create a correct and complete MPD file.
• 2. Create an XST (Xilinx Synthesis Technology) project file or a PAO file that lists the HDL sources required to implement the IP.
• 3. Invoke the PsfUtility by providing the XST project file or the PAO file with additional options.

For more information on invoking the PsfUtility with different options, see the following section, Use Models for Automatic MPD Creation, page 23.

You can run the PsfUtility in a variety of ways, depending on the bus standard and bus interface types used with the peripheral and the number of bus interfaces a peripheral contains. Bus standards and types can be one of the following:

• AXI4 MASTER
• AXI4 SLAVE
• AXI4LITE MASTER
• AXI4LITE SLAVE
• AXI STREAMING (same as POINT TO POINT)
• DCR (design control register) SLAVE
• FSL (fast simplex link) SLAVE
• FSL MASTER
• LMB (local memory bus) SLAVE
• PLBV46 (processor local bus version 4.6) SLAVE
• PLBV46 MASTER
• POINT TO POINT BUS (special case)

Most processor peripherals have a single bus interface. This is the simplest model for the PsfUtility. For most such peripherals, complete MPD specifications can be obtained without any additional attributes added to the source code.

The signal names must follow the conventions specified in "Conventions for Defining HDL Peripherals" on page 25. When there is only one bus interface, no bus identifier need be specified for the bus signals.

The command line for invoking PsfUtility is as follows:

psfutil -hdl2mpd <hdlfile> -lang {vhdl|ver} -top <top_entity>
-bus <busstd> <bustype> -o <mpdfile>

For example, to create an MPD specification for an PLB slave peripheral such as UART, the command is:

psfutil -hdl2mpd uart.vhd -lang vhdl -top uart -bus plb s -o uart.mpd

Alternatively, you can use a .prj file as input for invoking PsfUtility, as follows:

psfutil -hdl2mpd uart.prj -lang vhdl -top uart -bus plb s -o uart.mpd

Some peripherals might have multiple associated bus interfaces. These interfaces can be exclusive bus interfaces, non-exclusive bus interfaces, or a combination of both. All bus interfaces on the peripheral that can be connected to the peripheral simultaneously are exclusive interfaces. For example, an OPB Slave bus interface and a DCR Slave bus interface are exclusive because they can be connected simultaneously.

On a peripheral containing exclusive bus interfaces: a port can be connected to only one of the exclusive bus interfaces.

Non-exclusive bus interfaces cannot be connected simultaneously.

Peripherals with non-exclusive bus interfaces have ports that can be connected to multiple non-exclusive interfaces. Non-exclusive interfaces have the same bus interface standard.

Signal names must adhere to the conventions specified in "Conventions for Defining HDL Peripherals" on page 25.

• For non-exclusive bus interfaces, bus identifiers need not be specified.
• For exclusive bus interfaces, identifiers must be specified only when the peripheral has more than one bus interface of the same bus standard and type.

You can specify buses on the command line when the bus signals do not have bus identifier prefixes. The command line for invoking the PsfUtility is as follows:

psfutil -hdl2mpd <hdlfile> -lang {vhdl|ver} -top <top_entity>
[-bus <busstd> <bustype>] -o <mpdfile>

For an example of a non-exclusive bus interface, to create an MPD specification for a peripheral with a PLB slave interface and a PLB Master/Slave interface such as gemac, the command is:

psfutil -hdl2mpd gemac.prj -lang vhdl -top gemac -bus plb s -bus plb ms
-o gemac.mpd

For an example of an exclusive bus identifier, to create an MPD specification for a peripheral with a PLB slave interface and a DCR Slave interface, the command is:

psfutil -hdl2mpd mem.prj -lang vhdl -top mem -bus plb s -bus dcr s -o mem.prj

Some peripherals, such as multi-channel memory controllers, might have point-to-point connections (BUS_STD = XIL_MEMORY_CHANNEL, BUS_TYPE = TARGET).

The signal names must follow conventions such that all signals belonging to the point-to-point connection start with the same bus interface name prefix, such as MCH0_*.

You can specify point-to-point connections in the command line using the bus interface name as a prefix to the bus signals.

The command line for invoking PsfUtil is:

psfutil -hdl2mpd <hdlfile> -lang {vhdl|ver} -top <top_entity>
-p2pbus <busif_name> <bus_std> {target|initiator} -o <mpdfile>

For example, to create an MPD specification for a peripheral with an MCH0 connection, the command is:

psfutil -hdl2mpd mch_mem.prj -lang vhdl -top mch_mem -p2pbus MCH0
XIL_MEMORY_CHANNEL TARGET -o mch_mem.mpd

To enable generation of correct and complete MPD files from HDL sources, the PsfUtility reports DRC errors. The DRC checks are listed in the following subsections in the order they are performed.

The PsfUtility returns a failure status if errors are found in the HDL source files.

For every specified bus interface, the PsfUtility checks and reports any missing or repeated bus signals. It generates an MPD file when all bus interface checks are completed.

The top-level HDL source file for an IP peripheral defines the interface for the design and has the following characteristics:

• Lists ports and default connectivity for bus interfaces
• Lists parameters (generics) and default values
• Parameters defined in the MHS overwrite corresponding HDL source parameters

Individual peripheral documentation contains information on source file options.

For components that have more than one bus interface of the same type, naming conventions must be followed so the automation tools can group the bus interfaces.

A bus interface is a grouping of related interface signals. For the automation tools to function properly, you must adhere to the signal naming conventions and parameters associated with a bus interface.

When the signal naming conventions are correctly specified, the following interface types are recognized automatically, and the MPD file contains the bus interface label shown in

Table 2-2: Recognized Bus Interfaces

For peripherals that contain more than one of the same bus interface, a bus identifier must be used. The bus identifier must be attached to all associated signals and generics.

Generic names must be VHDL-compliant. Additional conventions for IP peripherals are:

• The generic must start with C**_**.
• If more than one instance of a particular bus interface type is used on a peripheral, a bus identifier must be used in the signal.
• If a bus identifier is used for the signals associated with a port, the generics associated with that port can optionally use .
• If no string is used in the name, the generics associated with bus parameters are assumed to be global. For example, C_DOPB_DWIDTH has a bus identifier of D and is associated with the bus signals that also have a bus identifier of D. If only C_OPB_DWIDTH is present, it is associated with all OPB buses regardless of the bus identifier on the port signals.

Note: For the PLBV4.6 bus interface, the bus identifier <BI> is treated as the bus tag (bus interface name). For example, C_SPLB0_DWIDTH has a bus identifier (tag) SPLB0 and is associated with the bus signals that also have a bus identifier of SPLB0 as the prefix.

• For peripherals that have only a single bus interface (which is the case for most peripherals), the use of the bus identifier string in the signal and generic names is optional, and the bus identifier is typically not included.
• All generics that specify a base address must end with _BASEADDR, and all generics that specify a high address must end with _HIGHADDR. Further, to tie these addresses with buses, they must also follow the conventions for parameters, as listed above.
• For peripherals with more than one bus interface type, the parameters must have the bus standard type specified in the name. For example, parameters for an address on the PLB bus must be specified as C_PLB_BASEADDR and C_PLB_HIGHADDR.

The Platform Generator (Platgen) expands and populates certain reserved generics automatically. For correct operation, a bus tag must be associated with these parameters. To have the PsfUtility infer this information automatically, all specified conventions must be followed for reserved generics as well. This can help prevent errors when your peripheral requires information on the platform that is generated.

Table 2-3 lists the reserved generic names.

Table 2-3: Automatically Expanded Reserved Generics

Table 2-4 lists the parameters that Platgen populates automatically.

Table 2-4: Reserved Parameters

This section provides naming conventions for bus interface signal names. The conventions are flexible to accommodate embedded processor systems that have more than one bus interface and more than one bus interface port per component. When peripherals with more than one bus interface port are included in a design, it is important to understand how to use a bus identifier. (As explained previously, a bus identifier must be used for peripherals that contain more than one of the same bus interface. The bus identifier must be attached to all associated signals and generics.)

The names must be HDL compliant. Additional conventions for IP peripherals are:

• The first character in the name must be alphabetic and uppercase.
• The fixed part of the identifier for each signal must appear exactly as shown in the applicable section below. Each section describes the required signal set for one bus interface type.
• If more than one instance of a particular bus interface type is used on a peripheral, the bus identifier must be included in the signal identifier. The bus identifier can be as simple as a single letter or as complex as a descriptive string with a trailing underscore (_) peripheral. must be included in the port signal identifiers in the following cases:
  • The peripheral has more than one slave AXI port
  • The peripheral has more than one master AXI port
  • The peripheral has more than one slave LMB port
  • The peripheral has more than one slave DCR port
  • The peripheral has more than one master DCR port
  • The peripheral has more than one slave FSL port
  • The peripheral has more than one master FSL port
  • The peripheral has more than one slave PLBV4.6 port
  • The peripheral has more than one master PLBV4.6 port
  • The peripheral has more than one port of any type and the choice of or causes ambiguity in the signal names.

For peripherals that have only a single bus interface (which is the case for most peripherals), the use of the bus identifier string in the signal names is optional, and the bus identifier is typically not included.

The names for the global ports of a peripheral, such as clock and reset signals, are standardized. You can use any name for other global ports, such as the interrupt signal.

M_AXI_ACLK M_AXI_ARESETN

S_AXI_ACLK S_AXI_ARESETN

LMB_Clk LMB_Rst

MPLB_Clk MPLB_Rst

SPLB_Clk SPLB_Rst

^1. ACLK and/or ARESETN can be bus interface specific or can be global across bus interfaces. Global ports, must be named ACLK and ARESETN.

Master AXI4 ports must use the naming conventions shown in Table 2-5:

m_axi_sg_awlen : out std_logic_vector(7 downto 0);
m_axi_sg_awsize : out std_logic_vector(2 downto 0);
m_axi_sg_awburst : out std_logic_vector(1 downto 0);

m_axi_sg_awready : in std_logic;
m_axi_sg_bresp : in std_logic_vector(1 downto 0);
m_axi_sg_bvalid : in std_logic;

Slave AXI4 ports must use the naming conventions shown in Table 2-6:

Examples:

Master AXI4LITE ports must use the naming conventions shown in Table 2-7:

Examples:

m_axi_lite_wdata : out std_logic_vector(C_M_AXI_LITE_DATA_WIDTH-1
 downto 0);
m_axi_lite_wstrb : out std_logic_vector((C_M_AXI_LITE_DATA_WIDTH/8)-1
 downto 0);
m_axi_lite_bready : out std_logic;

<BI>_arready : in std_logic;
<BI>_rvalid : in std_logic;
<BI>_rdata : in std_logic_vector(C_<BI>_DATA_WIDTH-1 downto 0);
<BI>_rresp : in std_logic_vector(1 downto 0);
<BI>_awready : in std_logic;
<BI>_wready : in std_logic;
<BI>_bvalid : in std_logic;
<BI>_bresp : in std_logic_vector(1 downto 0);

m_axi_lite_rdata : in std_logic_vector(C_M_AXI_LITE_DATA_WIDTH-1
 downto 0);
m_axi_lite_rresp : in std_logic_vector(1 downto 0);
m_axi_lite_awready : in std_logic;

Slave AXI4LITE ports must use the naming conventions shown in Table 2-8:

Slave DCR ports must follow the naming conventions shown in Table 2-9.

Note: If is present, is optional.

Table 2-9: Slave DCR Port Naming Conventions

For interconnection to the DCR, all slaves must provide the following outputs:

Examples:

For interconnection to the DCR, all slaves must provide the following inputs:

<BI><nDCR>_ABus : in std_logic_vector(0 to C_<BI>DCR_AWIDTH-1);
<BI><nDCR>_DBus : in std_logic_vector(0 to C_<BI>DCR_DWIDTH-1);
<BI><nDCR>_Read : in std_logic;
<BI><nDCR>_Write : in std_logic;

Table 2-10 contains the required Slave FSL port naming conventions:

Table 2-10: Slave FSL Port Naming Conventions

For interconnection to the FSL, slaves must provide the following outputs:

<BI><nFSL_S>_Data : out std_logic_vector(0 to C_<BI>FSL_DWIDTH-1);
<BI><nFSL_S>_Control : out std_logic;
<BI><nFSL_S>_Exists : out std_logic;

FSL_S_Control : out std_logic;
Memcon_FSL_S_Control : out std_logic;
Bus1_timer_FSL_S_Control: out std_logic;
Bus1_timer_FSL_S_Data : out std_logic_vector(0 to C_<BI>FSL_DWIDTH-1);
Bus2_timer_FSL_S_Control: out std_logic;
Bus2_timer_FSL_S_Data : out std_logic_vector(0 to C_<BI>FSL_DWIDTH-1);

For interconnection to the FSL, slaves must provide the following inputs:

Table 2-11 lists the required Master FSL ports naming conventions:

For interconnection to the FSL, masters must provide the following outputs:

<nFSL_M>_Full : out std_logic;

Examples:

FSL_M_Full : out std_logic; Memcon_FSL_M_Full : out std_logic;

For interconnection to the FSL, masters must provide the following inputs:

Slave LMB ports must follow the naming conventions shown in Table 2-12:

Note: If is present, is optional.

For interconnection to the LMB, slaves must provide the following outputs:

<BI><Sln>_DBus : out std_logic_vector(0 to C_<BI>LMB_DWIDTH-1);
<BI><Sln>_Ready : out std_logic;

Examples:

For interconnection to the LMB, slaves must provide the following inputs:

<BI><nLMB>_ABus : in std_logic_vector(0 to C_<BI>LMB_AWIDTH-1);
 <BI><nLMB>_AddrStrobe : in std_logic;
 <BI><nLMB>_BE : in std_logic_vector(0 to C_<BI>LMB_DWIDTH/
   8-1);
 <BI><nLMB>_Clk : in std_logic;
 <BI><nLMB>_ReadStrobe : in std_logic;
 <BI><nLMB>_Rst : in std_logic;
 <BI><nLMB>_WriteDBus : in std_logic_vector(0 to C_<BI>LMB_DWIDTH-1);
 <BI><nLMB>_WriteStrobe : in std_logic;
Examples:

LMB_ABus : in std_logic_vector(0 to C_LMB_AWIDTH-1);
DLMB_ABus : in std_logic_vector(0 to C_DLMB_AWIDTH-1);

Master PLBV4.6 ports must use the naming conventions shown inTable 2-13.

For interconnection to the PLB v4.6, masters must provide the following outputs:

For interconnection to the PLBV4.6, masters must provide the following inputs:

<BI>PLB_MRdDBus : in std_logic_vector(0 to C_<BI|MPLB>_DWIDTH-1);
 <BI>PLB_MRdWdAddr : in std_logic_vector(0 to 3);
 <BI>PLB_MRearbitrate : in std_logic;
 <BI>PLB_MSSize : in std_logic_vector(0 to 1);
 <BI>PLB_MTimeout : in std_logic;
Examples:
 IPLB0_PLB_MBusy : in std_logic;
 Bus1_PLB_MBusy : in std_logic;

Table 2-14 shows the required naming conventions for Slave PLBV4.6 ports.

Table 2-14: Slave PLBV46 Port Naming Conventions

For interconnection to the PLBV4.6, slaves must provide the following outputs:

For interconnection to the PLBV4.6, slaves must provide the following inputs:

The psf2Edward is a command line program that converts a Xilinx® Embedded Development Kit (EDK) project into Edward, an internal XML format, for use in external programs such as the Software Development Kit (SDK).

The DTD for the Edward Format can be found in <EDK installation directory>/data/xml/DTD/Xilinx/Edward.

You can use Psf2Edward to:

• Convert Platform Specification Format (PSF) project to XML format. To do this, use the following command: psf2Edward -inp <psf input source> -xml <*xml output file***>**
• <options> • Synchronize an existing XML file with a PSF project, as follows:
• psf2Edward -inp <psf input source> -sync < XML file to sync> <options>

Psf2Edward has the following options:

The Hardware Platform Generation tool (Platgen) customizes and generates the embedded processor system, in the form of hardware netlists files.

By default, Platgen synthesizes each processor IP core instance found in your embedded hardware design using the XST compiler. Platgen also generates the system-level HDL file that interconnects all the IP cores, to be synthesized later as part of the overall Xilinx® Integrated Software Environment (ISE®) implementation flow.

For more information, refer to the Platform Specification Format Reference Manual. A link to this document is provided in Appendix E, Additional Resources.

The features of Platgen includes the creation of:

• The programmable system on a chip in the form of hardware netlists (HDL and implementation netlist files.)
• A hardware platform using the Microprocessor Hardware Specification (MHS) file as input.
• Netlist files in various formats such as NGC and EDIF.
• Support files for downstream tools and top-level HDL wrappers to allow you to add other components to the automatically generated hardware platform.

After running Platgen, XPS spawns the Project Navigator interface for the FPGA implementation tools to complete the hardware implementation, allowing you full control over the implementation. At the end of the ISE flow, a bitstream is generated to configure the FPGA. This bitstream includes initialization information for block RAM memories on the FPGA chip. If your code or data must be placed on these memories at startup, the Data2MEM tool in the ISE toolset updates the bitstream with code and data information obtained from your executable files, which are generated at the end of the software application creation and verification flow.

Set up your system to use the Xilinx Integrated Development System. Verify that your system is properly configured. Consult the release notes and installation notes for more information.

Run Platgen as follows:

platgen -p * system.*mhs where:

platgen is the executable name.

-p is the option to specify a part.

is the partname.

*system.*mhs is the output file.

Table 4-1: Platgen Syntax Options (Cont'd)

Figure 4-1 shows the peripheral directory structure.

To specify additional directories, use one of the following options:

• Use the current directory (from which Platgen was launched.)
• Set the EDK tool -lp option.

Platgen uses a search priority mechanism to locate peripherals in the following order:

• 1. The pcores directory in the project directory.
• 2. The <Library_Path>/<Library_Name>/pcores as specified by the -lp option.
• 3. The $XILINXEDK/hw/<_Library_Name>/pcores.

Note: Directory path names are case-sensitive in Linux. Ensure that you use pcore and not Pcore.

Figure 4-1: Peripheral Directory Structure

From the pcores directory, the root directory is the <peripheral_name>.

From the root directory, the underlying directory structure is:

data/ hdl/ netlist/

Platgen produces directories and files from the project directory in the following underlying directory structure:

/hdl /implementation /synthesis

The /hdl directory contains the following files:

• system.{vhd|v} is the HDL file of the embedded processor system as defined in the MHS, and the toplevel file for your project.
• system_stub.{vhd|v} is the toplevel template HDL file of the instantiation of the system. Use this file as a starting point for your own toplevel HDL file.
• <inst>_wrapper.{vhd|v} is the HDL wrapper file for the of individual IP components defined in the MHS.

The implementation directory contains implementation netlist files with the naming convention <instance_name>_wrapper.ngc.

The synthesis directory contains the system.[prj|scr] synthesis project file.

Platgen generates the <system>.bmm and the <system>_stub.bmm in the <Project_Name>/implementation directory.

• The <system>.bmm is used by the implementation tools when EDK is the top-level system.
• The <system>_stub is used by the implementation when EDK is a sub-module of the top-level system.

The EDK tools implementation tools flow using Data2MEM is as follows:

ngdbuild -bm <system>.bmm <system>.ngc
map
par
bitgen -bd <system>.elf

Bitgen outputs <system>_bd.bmm, which contains the physical location of block RAMs.

A block RAM Memory Map (BMM) file contains a syntactic description of how individual block RAMs constitute a contiguous logical data space.

The <system>_bd.bmm and <system>.bit files are input to the Data2MEM program. Data2MEM translates contiguous fragments of data into the proper initialization records for the Virtex® series block RAMs.

An IP rebuild is triggered when one of the following changes occur:

• Instance name change
• Parameter value change
• Core version change
• Core is specified with the MPD CORE_STATE=DEVELOPMENT option
• Core license change

This chapter describes the XPS command line (no window) mode.

To invoke the XPS command line or "no window" mode, type the command xps -nw at the LINUX Shell or Windows command prompt. XPS performs the specified operation, then presents a command prompt.

From the command line, you can:

• Generate the make files
• Run the complete project flow in batch mode
• Create an XMP project file
• Load a Xilinx Microprocessor Project (XMP) file created by the XPS GUI
• Read and reload project files
• Execute flow commands
• Archive your project

XPS batch provides the ability to query the EDK design database; Tcl commands are available for this purpose. In batch mode for XPS, you can specify a Tcl script by using the -scr option. You can also provide an existing XMP file as input to XPS.

To create a new project with no components, use the command:

xload new <basename>.xmp

XPS creates a project with an empty Microprocessor Hardware Specification (MHS) file. All of the files have same base name as the XMP file. If XPS finds an existing project in the directory with same base name, then the XMP file is overwritten.

If you are using 6 series architecture or later, refer to answer record 44371, which provides a workaround.

To create a new project, use the command:

xload mhs <basename>.mhs

XPS reads in the MHS file and creates the new project. The project name is the same as the MHS base name. All of the files generated have the same name as MHS. After reading in the MHS file, XPS also assigns various default drivers to each of the peripheral instances, if a driver is known and available to XPS.

If you already have an XMP project file, you can load that file using the command:

xload xmp <basename>.xmp

XPS reads in the XMP file.

To save XMP and make files for your project, use the command:

save [xmp|make|proj]

Command save proj saves the XMP, MHS and make files. To save the make file, use the save make command explicitly.

Using the xset commands, you can set project options and other fields in XPS.

Using the xget commands, you can display the current value of those field; it also returns the result as a Tcl string result, which you can save into a Tcl variable. Table 5-1 shows the options you can use with the xget and xset commands:

xset option xget option

Table 5-1: xset and xget Command Options

You can run various flow tools using the run command with appropriate options. XPS creates a make file for the project and runs that make file with the appropriate target. XPS generates the make file every time the run command is executed. Table 5-2 lists the valid options for the run command:

run <option>

Table 5-2: run Command Options

All EDK design files refer to MHS files. Any changes in MHS files have impact on other design files. If there are any changes in the MHS file after you loaded the design, use the following command to re-read MHS and XMP files:

run resync

You can add or update the ELF files associated with a processor instance using this command:

xadd_elf <procinst> <elf type - sim|imp|both> <elf file>

You can delete the ELF file associated with a processor instance using this command:

xdel_elf <procinst> <elf type - sim|imp|both>

To archive a project, use the command:

The xpsarchiver tool compacts the files into a zip file. Refer to the _XPS Online Help for the list of files that are archived.

You can set various software application options and other fields in XPS using the xset_swapp_prop_value command. You can also display the current value of those fields using the xget_swapp_prop_value command. The xget_swapp_prop_value command also returns the result as a Tcl string result. The following table lists the options available for setting or displaying with these commands:

xset_swapp_prop_value <swapp_name> <option_name> <value>
xget_swapp_prop_value <swapp_name> <option_name>

Table 5-3: xset* and xget* Command Options

For every processor instance, there is a bootloop application provided by default in XPS. For MicroBlaze instances, there is also an XMDStub application provided by XPS.

The only setting available on these special software applications is to "Mark for BRAM Initialization."

When you use the xset_swapp_prop_value, XPS "no window" mode recognizes _bootloop and _xmdstub as special software application names. For example, if the processor instance is "mymblaze," XPS recognizes mymblaze_bootloop and mymblaze_xmdstub as software applications.

You can set the init_bram option on this application.

XPS% xset_swapp_prop_value mymblaze_bootloop init_bram true XPS% xset_swapp_prop_value mymblaze_xmdstub init_bram false

This assumes that there is no software application by the same name. If there is an application with same name, you will not be able to change the settings using the XPS Tcl interface. Therefore, in XPS "no window" mode, you should not create an application with name s or _xmdstub. This limitation is valid only for XPS "no window" mode and does not apply if you are using the GUI interface.

Xilinx® recommends that you do not edit the XMP file manually. The XPS -batch mode supports changing project options through commands. Any other changes must be done from XPS.

This chapter describes Bus Functional Model (BFM) simulation within Xilinx® Embedded System Kit (EDK). You can run BFM simulation with ModelSim, QuestaSim, and ISim.

Bus Functional Simulation provides the ability to generate bus stimulus and thereby simplifies the verification of hardware components that attach to a bus. Bus Functional Simulation circumvents the drawbacks to the two typical validation methods, which are:

• Creating a test bench: This is time-consuming because it involves describing the connections and test vectors for all combinations of bus transactions.
• Creating a larger system with other known-good components that create or respond to bus transactions: This is time-consuming because it requires that you describe the established connections to the device under test, program the added components to generate the bus transactions to which the device will respond, and potentially respond to bus transactions that the device is generating. Such a system usually involves creating and compiling code, storing that code in memory for the components to read, and generating the correct bus transactions.

There are two main BFM use cases:

• IP verification
• Speed Up simulation

When verifying a single piece of IP that includes a bus interface you concern yourself with the internal details of the IP design and the bus interactions. It is inefficient to attach the IP to a large system only to verify that it is functioning properly.

Figure 6-1 shows an example in which a master BFM generates bus transactions to which the device under test responds. The monitor BFM reports any errors regarding the bus compliance of the device under test.

Figure 6-1: Slave IP Verification Use Case

Figure 6-2 shows an example in which a slave BFM responds to bus transactions that the device under test generates. The monitor BFM reports any errors regarding the bus compliance of the device under test.

Figure 6-2: Master IP Verification Use Case

When verifying a large system design, it can be time consuming to simulate the internal details of each IP component that attaches to a bus. There are certain complex pieces of IP that take a long time to simulate and could be replaced by a Bus Functional Model, especially when the internal details of the IP are not of interest. Additionally, some IP components are not easy to program to generate the desired bus transactions.

Figure 6-3 shows how two different IP components that are bus masters have been replaced by BFM master modules. These modules are simple to program and can provide a shorter simulation time because no internal details are modeled.

Figure 6-3: Speed-Up Simulation Use Case

There are two software packages that lets you perform Bus Functional Simulation, and each applies its own methodology:

• PLBv4.6 BFM and the Xilinx EDK BFM package, which is based upon the IBM CoreConnect™ Toolkit.
• AXI BFM, which was provided by Cadence Design Systems, and is available on the Xilinx website.

IBM CoreConnect and AXI BFM are not included with EDK, but are required if you intend to perform bus functional simulation.

EDK includes a BFM package that provides a set of CoreConnect BFMs, the Bus Functional Compiler, and CoreConnect documents tailored for use within EDK. You can use this package after licensing the IBM CoreConnect Toolkit. The EDK BFM package lets you specify bus connections from a high-level description, such as an MHS file. By allowing the EDK tools to write the HDL files that describe the connections, the time and effort required to set up the test environment are reduced.

The IBM CoreConnect Toolkit is a collection of toolkits. Each toolkit includes a collection of HDL files that represents predefined systems, including a bus, bus masters, bus slaves, and bus monitors.

You can modify the predefined systems included in the toolkits manually to connect the hardware components you want to test. This is a labor-intensive process because you must describe all the connections to the bus and ensure there are no errors in setting up the test environment.

Refer to the CoreConnect Toolkit documentation for more information on how to verify your hardware module.You can download IBM CoreConnect™ Toolkit free of charge after you obtain a license for the IBM CoreConnect Bus Architecture. Licensing CoreConnect provides access to documentation, Bus Functional Models, and the Compiler.

Xilinx provides a Web-based licensing mechanism that lets you obtain CoreConnect from the Xilinx website. To license CoreConnect, use an internet browser to access: http://www.xilinx.com/products/ipcenter/dr_pcentral_coreconnect.htm. After the request is approved (typically within 24 hours), you receive an E-mail granting you access to the protected web site from which to download the toolkit.

For further documentation on the CoreConnect Bus Architecture, refer to the IBM CoreConnect web site:

http://www-01.ibm.com/chips/techlib/techlib.nsf/products/CoreConnect_Bus_Architecture

Note: There are differences between IBM CoreConnect and the Xilinx implementation of CoreConnect. These are described in the Processor IP Reference Guide, available in your $XILINX_EDK/doc/usenglish directory. Refer to "Device Control Register Bus (DCR) V2.9" for differences in the DCR bus.

AXI BFMs let you verify and simulate communication with AXI-based, in-development IP. Complete verification of these interfaces and protocol compliance is outside the scope of the AXI BFM solution; for compliance testing and complete system-level verification of AXI interfaces, use the Cadence AXI Universal Verification Component (UVC).

The AXI BFM solution is an optional product that is purchased separate from the ISE® Design Suite software. Licensing is handled through the standard Xilinx licensing scheme.

A license feature, XILINX_AXI_BFM, is required in addition to the standard ISE license features. A license is checked out at simulation run time. While the Xilinx ISE software does not need to be running while the AXI BFM solution is in use, the AXI BFM only operates on a computer that has the Xilinx software installed and licensed.

The BFM solution is encrypted using either the Verilog P1735 IEEE standard or a vendor-specific encryption scheme. To use the AXI BFM with Cadence Incisive Unified Simulator (IUS) and Incisive Enterprise Simulator (IES) products, an export control regulation license feature is required. Contact your Cadence sales office for more information.

See the AXI BFM User Guide (UG783) and the AXI Bus Functional Model Data Sheet (DS824) for more information.

The use of the IBM CoreConnect PLB BFM components requires the acceptance of a license agreement. For this reason, the BFM components are not installed along with EDK. Xilinx provides a separate installer for these called the "Xilinx EDK BFM Package."

To use the Xilinx EDK BFM Package, you must register and obtain a license to use the IBM CoreConnect Toolkit at:

http://www.xilinx.com/products/ipcenter/dr_pcentral_coreconnect.htm

After you register, you receive instructions and a link to download the CoreConnect Toolkit files. You can then install the files using the registration key provided.

After running the installer, you can verify that the files were installed by typing the following command:

xilbfc -check

A Success! message indicates you are ready to continue; otherwise, you will receive instructions on the error.

Bus Functional Simulation usually involves the following components:

• A Bus Functional Model
• A Bus Functional Language
• A Bus Functional Compiler

BFMs are hardware components that include and model a bus interface. There are different BFMs for different buses. For example, PLB BFM components are used to connect to their respective bus.

For each bus, there are different model types. For example the PLB bus has PLB Master, PLB Slave, and PLB Monitor BFM components. The same set of components and more could exist for other busses, or the functionality of BFM components could be combined into a single model.

The BFL describes the behavior of the BFM components. You can specify how to initiate or respond to bus transactions using commands in a BFL file.

The BFC translates a BFL file into the commands that actually program the selected Bus Functional Model.

After you download and install the PLB (IBM CoreConnect Toolkit) BFM Package, you can launch EDK. The following components are available:

• PLB v4.6 Master BFM (plbv46_master_bfm) The PLB v4.6 master model contains logic to initiate bus transactions on the PLB v4.6 bus automatically. The model maintains an internal memory that can be initialized through the Bus Functional Language and may be dynamically checked during simulation or when all bus transactions have completed.

• PLB v4.6 Slave BFM (plbv46_slave_bfm) The PLB v4.6 slave contains logic to respond to PLB v4.6 bus transactions based on an address decode operation. The model maintains an internal memory that can be initialized through the Bus Functional Language and can be dynamically checked during simulation or when all bus transactions have completed.

• PLB v4.6 Monitor (plbv46_monitor_bfm) The PLB v4.6 monitor is a model that connects to the PLB v4.6 and continuously samples the bus signals. It checks for bus compliance or violations of the PLB v4.6 architectural specifications and reports warnings and errors.

• BFM Synchronization Bus (bfm_synch) The BFM Synchronization Bus is a simple bus that connects BFMs in a design and allows communication between them. The BFM Synchronization Bus is required whenever BFM devices are used.

These components can be instantiated in an MHS design file for the EDK tools to create the simulation HDL files.

Note: Xilinx has written an adaptation layer to connect the IBM CoreConnect Bus Functional Models to the Xilinx implementation of CoreConnect. Some of these BFM devices have different data and instruction bus widths.

The following is an example MHS file that instantiates PLB v4.6 BFM components and the BFM synchronization bus.

# Parameters
PARAMETER VERSION = 2.1.0
# Ports
PORT sys_clk = sys_clk, DIR = I, SIGIS = CLK
PORT sys_reset = sys_reset, DIR = IN
# Components
BEGIN plb_v46
PARAMETER INSTANCE = myplb
PARAMETER HW_VER = 1.01.a
PARAMETER C_DCR_INTFCE = 0
PORT PLB_Clk = sys_clk
PORT SYS_Rst = sys_reset
END
BEGIN plb_bram_if_cntlr
PARAMETER INSTANCE = myplbbram_cntlr

PARAMETER HW_VER = 1.00.a
PARAMETER C_BASEADDR = 0xFFFF8000
PARAMETER C_HIGHADDR = 0xFFFFFFFF
BUS_INTERFACE PORTA = porta
BUS_INTERFACE SPLB = myplb
END
BEGIN bram_block
PARAMETER INSTANCE = bram1
PARAMETER HW_VER = 1.00.a
BUS_INTERFACE PORTA = porta
END
BEGIN plbv46_master_bfm
PARAMETER INSTANCE = my_master
PARAMETER HW_VER = 1.00.a
PARAMETER PLB_MASTER_ADDR_LO_0 = 0xFFFF0000
PARAMETER PLB_MASTER_ADDR_HI_0 = 0xFFFFFFFF
BUS_INTERFACE MPLB = myplb
PORT SYNCH_OUT = synch0
PORT SYNCH_IN = synch
END
BEGIN plbv46_slave_bfm
PARAMETER INSTANCE = my_slave
PARAMETER HW_VER = 1.00.a
PARAMETER PLB_SLAVE_ADDR_LO_0 = 0xFFFF0000
PARAMETER PLB_SLAVE_ADDR_HI_0 = 0xFFFF7FFF
BUS_INTERFACE SPLB = myplb
PORT SYNCH_OUT = synch1
PORT SYNCH_IN = synch
END
BEGIN plbv46_monitor_bfm
PARAMETER INSTANCE = my_monitor
PARAMETER HW_VER = 1.00.a
BUS_INTERFACE MON_PLB = myplb
PORT SYNCH_OUT = synch2
PORT SYNCH_IN = synch
END
BEGIN bfm_synch
PARAMETER INSTANCE = my_synch
PARAMETER HW_VER = 1.00.a
PARAMETER C_NUM_SYNCH = 3
PORT FROM_SYNCH_OUT = synch0 & synch1 & synch2
PORT TO_SYNCH_IN = synch

END

The BFM synchronization bus collects the SYNCH_OUT outputs of each BFM component in the design. The bus output is then connected to the SYNCH_IN of each BFM component. Figure 6-4 depicts an example for three BFMs, and the MHS example above shows its instantiation for PLB v4.6 BFMs.

X10850

Figure 6-4: BFM Synchronization Bus Usage

The following is a sample BFL file written for the PLB v4.6 BFM Component Instantiation, page 60, which instantiate the PLB v4.6 BFM components.

-- FILE: sample.bfl
-- This test case initializes a PLB master
-- Initialize my_master
-- Note: The instance name for plb_master is duplicated in the
-- path due to the wrapper level inserted by the tools
   set_device(path=/system/my_master/my_master/
master,device_type=plb_master)
-- Configure as 64-bit master
configure(msize=01)
-- Write and read 64-bit data using byte-enable architecture
mem_update(addr=ffff8000,data=00112233_44556677)
mem_update(addr=ffff8008,data=8899aabb_ccddeeff)
write (addr=ffff8000,size=0000,be=11111111)
write (addr=ffff8008,size=0000,be=11111111)
read (addr=ffff8000,size=0000,be=11111111)
read (addr=ffff8008,size=0000,be=11111111)
-- Write and read 32-bit data using byte-enable architecture
mem_update(addr=ffff8010,data=11111111_22222222)
write (addr=ffff8010,size=0000,be=11110000)
write (addr=ffff8014,size=0000,be=00001111)
read (addr=ffff8010,size=0000,be=11110000)
read (addr=ffff8014,size=0000,be=00001111)
-- Write and read 16-bit data using byte-enable architecture
mem_update(addr=ffff8020,data=33334444_55556666)
write (addr=ffff8020,be=1100_0000)
write (addr=ffff8022,be=0011_0000)

write (addr=ffff8024,be=0000_1100)
write (addr=ffff8026,be=0000_0011)
read (addr=ffff8020,be=1100_0000)
read (addr=ffff8022,be=0011_0000)
read (addr=ffff8024,be=0000_1100)
read (addr=ffff8026,be=0000_0011)
-- Write and read 8-bit data using byte-enable architecture
mem_update(addr=ffff8030,data=778899aa_bbccddee)
write (addr=ffff8030,be=1000_0000)
write (addr=ffff8031,be=0100_0000)
write (addr=ffff8032,be=0010_0000)
write (addr=ffff8033,be=0001_0000)
write (addr=ffff8034,be=0000_1000)
write (addr=ffff8035,be=0000_0100)
write (addr=ffff8036,be=0000_0010)
write (addr=ffff8037,be=0000_0001)
read (addr=ffff8030,be=1000_0000)
read (addr=ffff8031,be=0100_0000)
read (addr=ffff8032,be=0010_0000)
read (addr=ffff8033,be=0001_0000)
read (addr=ffff8034,be=0000_1000)
read (addr=ffff8035,be=0000_0100)
read (addr=ffff8036,be=0000_0010)
read (addr=ffff8037,be=0000_0001)
-- Write and read a 16-word line
mem_update(addr=ffff8080,data=01010101_01010101)
mem_update(addr=ffff8088,data=02020202_02020202)
mem_update(addr=ffff8090,data=03030303_03030303)
mem_update(addr=ffff8098,data=04040404_04040404)
mem_update(addr=ffff80a0,data=05050505_05050505)
mem_update(addr=ffff80a8,data=06060606_06060606)
mem_update(addr=ffff80b0,data=07070707_07070707)
mem_update(addr=ffff80b8,data=08080808_08080808)
write (addr=ffff8080,size=0011,be=1111_1111)
read (addr=ffff8080,size=0011,be=1111_1111)

More information about the PLB Bus Functional Language is in the PlbToolkit.pdf document in the $XILINX_EDK/third_party/doc directory.

The Bus Functional Compiler provided in the CoreConnect toolkit is a Perl script called BFC. The script uses a bfcrc configuration file that specifies to the script which simulator is used and the paths to the BFMs. EDK includes a helper executable, called xilbfc, that enables this configuration.

To compile a BFL file, type the following at a command prompt:

• For ModelSim: xilbfc -s mti sample.bfl
• For ISim: xilbfc -s isim sample.bfl

This creates a script targeted for the selected simulator that initializes the BFM devices. In the case of ModelSim, it creates a file called sample.do. In the case of ISim, it creates a file called sample.tcl.

The following subsections provide examples for the supported simulators.

The following is an example ModelSim or QuestaSim script called run.do that you can write to perform the BFM simulation steps:

do system.do
vsim system
do sample.do
do wave.do
force -freeze sim:/system/sys_clk 1 0, 0 {10 ns} -r 20 ns
force -freeze sim:/system/sys_reset 0, 1 {200 ns}
run 2 us

Note: If your design has an input reset that is active high, replace the reset line with: force -freeze sim:/system/sys_reset 1 , 0 {200 ns}

At the ModelSim prompt, type:

do run.do

The following is an example ISim script called run.tcl that you can write to perform the BFM simulation steps:

isim force add /system/sys_clk 1 -time 0 ns, -value 0 -time 10 ns
-repeat 20 ns
isim force add /system/sys_reset 1 -time 100 ns -value 0 -time 200 ns
do sample.tcl
do wave.do
run 2 us

At the ISim prompt, type:

source run.tcl

After you launch XPS, you can find the following Xilinx AXI BFM components in the IP Catalog list under verification category:

• AXI3 Master BFM(cdn_axi3_master_bfm_wrap) This is a master pcore on an AXI3 bus; it contains logic to initiate bus transactions on an AXI3 bus automatically.
• AXI3 Slave BFM(cdn_axi3_slave_bfm_wrap) This is a slave pcore on an AXI3 bus; it contains logic to respond to AXI3 bus transactions based on an address decode operation.
• AXI4-Lite Master BFM(cdn_axi4_lite_master_bfm_wrap) This is an AXI4-Lite Master pcore on an AXI4 bus; it contains logic to initiate Axi4-Lite bus transactions on an AXI4 bus automatically.

Note: An AXI4-Lite Master can initiate only a single read and a single write transaction, Axi4-Lite protocol does not allow burst transaction.

• AXI4-Lite Slave BFM(cdnaxi4_lite_slave_bfm_wrap) This is AXI4-Lite Slave pcore on AXI4 bus and it contains logic to respond to AXI4-Lite bus transaction based on an address decode operation. _Note: An AXI4-Lite Slave can respond only to a single read and write transaction, AXI4 lite protocol does not allow burst transaction.

• AXI4 Master BFM(cdn_axi4_master_bfm_wrap) This is an AXI4 Slave pcore on AXI4 bus and it contains logic to initiate AXI4 bus transactions on an AXI4 bus automatically. This master can initiate burst transaction.

• AXI4 Slave BFM(cdn_axi4_slave_bfm_wrap) This is an AXI4 Slave pcore on AXI4 bus and it contains logic to respond to AXI4 bus transaction based on an address decode operation. This slave can respond to burst transactions.

• AXI4-Stream Master BFM(cdn_axi4_streaming_master_bfm_wrap) This is an AXI4-Stream Master pcore on AXI4- Stream Point-to-Point (P2P) connection to initiate an AXI4-Stream transaction on a streaming connection.

• AXI4-Stream Slave BFM(cdn_axi4_streaming_slave_bfm_wrap) This is AXI4-Stream Slave pcore on AXI4 Streaming Point-to-Point (P2P) connection to respond to an AXI4-Stream transaction on a streaming connection.

These components can be instantiated in an MHS design file for the Platform Studio tools to create the simulation HDL files.

The following is an example MHS file that instantiates AXI4 BFM component

#
##############################################################################
# BFM simulation system
#
##############################################################################
 PARAMETER VERSION = 2.1.0
 PORT sys_reset = sys_reset, DIR = IN, SIGIS = RST
 PORT sys_clk = sys_clk, DIR = IN, SIGIS = CLK, CLK_FREQ = 100000000
#AXI4 Lite Master BFM
BEGIN cdn_axi4_lite_master_bfm_wrap
 PARAMETER INSTANCE = bfm_processor
 PARAMETER HW_VER = 2.00.a
 BUS_INTERFACE M_AXI_LITE = axi4lite_bus
 PORT M_AXI_LITE_ACLK = sys_clk
END
#AXI Interconnect
BEGIN axi_interconnect
 PARAMETER INSTANCE = axi4lite_bus
 PARAMETER HW_VER = 1.03.a
 PARAMETER C_INTERCONNECT_CONNECTIVITY_MODE = 0
 PORT INTERCONNECT_ARESETN = sys_reset
 PORT INTERCONNECT_ACLK = sys_clk
END
#DUT
BEGIN test_slave_lite
 PARAMETER INSTANCE = test_slave_lite_inst
 PARAMETER HW_VER = 1.00.a
 PARAMETER C_BASEADDR = 0x30000000
 PARAMETER C_HIGHADDR = 0x3000ffff
 BUS_INTERFACE S_AXI = axi4lite_bus
 PORT S_AXI_ACLK = sys_clk
END

Figure 6-5 shows an example for AXI BFM, and the MHS example above shows its instantiations for an AXI4-Lite Master BFM:

Figure 6-5: Master AXI BFM Bus Usage for DUT Verification

Figure 6-6 shows the usage of a Cadence AXI BFM.

Figure 6-6: Cadence AXI BFM

Cadence AXI BFMs consist of three main layers; the:

• Signal interface: A standard Verilog input/output ports and associated signal.
• Channel API: A set of defined Verilog tasks that operate at the basic transaction level inherent in the AXI protocol, namely:
  • Read Address Channel
  • Write Address Channel
  • Read Data Channel
  • Write Data Channel
  • Write Response Channel
• Function-level API: This level has complete transaction level control, for example a complete AXI read burst process is encapsulated in a single Verilog task.

The configuration is implemented using Verilog parameters and/or BFM internal variables and is used to set, for example, the address bus width and the data bus width.

The testbench can contain multiple instances of Cadence AXI BFMs but for simplicity only one has been shown in Figure 6-6. The basic principle is that the Design Under Test (DUT) and AXI BFMs are instantiated in a testbench that also contains a clock and reset generator. Then you instantiate the testbench into your test module and create a test program using the Cadence BFM API layers. Such a test program does calls to these API tasks either sequentially or concurrently using a fork and join method.

The following is a sample BFM test program for the Example MHS File, page 66, which instantiates the AXI4-Lite BFM component:

reg rst_n; reg sys_clk; integer number_of_bytes; integer i; integer j; reg[31 : 0] test_data; reg[31 : 0] mtestAddr; reg[2 : 0] mtestProtection; reg[31 : 0] rd_data; reg[1 : 0] response; //-------------------------------------------------------------- // Instantiate bfm_system //------------------------------------------------------------- bfm_system dut(.sys_reset(rst_n),.sys_clk(sys_clk)); initial begin //Wait for end of reset wait(rst_n == 0) @(posedge sys_clk); wait(rst_n == 1) @(posedge sys_clk); $display("----------------------------------------------------"); $display("Full Registers write"); $display("----------------------------------------------------"); number_of_bytes = 4; //writing the all register for( i = 0 ; i <4; i = i+1) begin for(j=0 ; j < number_of_bytes ; j = j+1) test_data[j8 +: 8] = j+(inumber_of_bytes); mtestAddr = SLAVE_BASE_ADDR + i*number_of_bytes; $display("Writing to Slave Register addr=0x%h",mtestAddr, " data=0x%h",test_data); fork dut.bfm_processor.bfm_processor.cdn_axi4_lite_master_bfm_inst.SEND_WRITE_ADDRESS(mtestAddr,mtestProtec tion); dut.bfm_processor.bfm_processor.cdn_axi4_lite_master_bfm_inst.SEND_WRITE_DATA(4'b1111,test_data); dut.bfm_processor.bfm_processor.cdn_axi4_lite_master_bfm_inst.RECEIVE_WRITE_RESPONSE(response); join CHECK_RESPONSE_OKAY(response); end //reading the all register for( i = 0 ; i <4; i = i+1) begin for(j=0 ; j < number_of_bytes ; j = j+1) test_data[j*8 +: 8] = j+(i*number_of_bytes); mtestAddr = SLAVE_BASE_ADDR + i*number_of_bytes; dut.bfm_processor.bfm_processor.cdn_axi4_lite_master_bfm_inst.SEND_READ_ADDRESS(mtestAddr,mtestProtect ion); dut.bfm_processor.bfm_processor.cdn_axi4_lite_master_bfm_inst.RECEIVE_READ_DATA(rd_data,response); CHECK_RESPONSE_OKAY(response); $display("Reading from Slave Register addr=0x%h",mtestAddr, " data=0x%h",rd_data); COMPARE_DATA(test_data,rd_data); if (rd_data !== test_data) begin $display("TESTBENCH FAILED! Data expected is not equal to actual.","\n expected = 0x%h",expected, "\n actual = 0x%h",actual); $stop; end $display("----------------------------------------------------"); $display("Peripheral Verification Completed Successfully"); $display("----------------------------------------------------"); End

The overall steps to run the an AXI BFM simulation are:

• 1. Compile the simulation HDL files.
• 2. Load the system into the simulator.
• 3. Initialize the Bus Functional Models.
• 4. (Optionally) create a waveform list or load a previously created waveform.
• 5. Provide the clock and reset stimulus to the system.
• 6. Run the simulation.

Specifically, in EDK, the steps are:

• 1. In XPS, open your test design.
• 2. Go to Project > Project options > design flow, and select the following:
  • a. Verilog for HDL language
  • b. Generate test bench template
  • c. Behavioral for simulation models
• 3. Select Edit > Preference > Simulation and select the simulator (ISim, ModelSim, QuestaSim)
• 4. Generate the simulation file (Simulation > Generate Simulation HDL Files). This also generates a <projectname>_tb.v file inside the ./simulation/behavioral/ directory.
• 5. Write you test program in the ./simulation/behavioral/<projectname>_tb.v file.
• 6. Launch Simulation: Go to Simulation > Launch HDL Simulator The simulator wizard opens.
• 7. Take the action according to simulator:
  • Select ISim > run timelength. For example: run 1ms
  • For ModelSim and Questa Sim:
    • - Compile the HDL files
    • - Simulate
    • - Specify run timelength. For example: run 1ms

This chapter introduces the basics of Hardware Description Language (HDL) simulation and describes the Simulation Model Generator tool, Simgen, and usage of the Compxlib utility tool.

Simgen creates and configures various VHDL and Verilog simulation models for a specified hardware. Simgen takes, as the input file, the Microprocessor Hardware Specification (MHS) file, which describes the instantiations and connections of hardware components.

Simgen is also capable of creating scripts for a specified vendor simulation tool. The scripts compile the generated simulation models.

The hardware component is defined by the MHS file. Refer to the "Microprocessor Hardware Specification (MHS)" chapter in the Platform Specification Format Reference Manual for more information. Appendix E, Additional Resources, contains a link to the document web site. For more information about simulation basics and for discussions of behavioral, structural, and timing simulation methods, refer to the Platform Studio Online Help.

EDK simulation netlists use low-level hardware primitives available in Xilinx® FPGAs. Xilinx provides simulation models for these primitives in the libraries listed in this section.

The libraries described in the following sections are available for the Xilinx simulation flow. The HDL code must refer to the appropriate compiled library. The HDL simulator must map the logical library to the physical location of the compiled library.

ISE provides the following libraries for simulation:

• UNISIM Library
• SIMPRIM Library
• XilinxCoreLib Library

The UNISIM Library is a library of functional models used for behavioral and structural simulation. It includes all of the Xilinx Unified Library components that are inferred by most popular synthesis tools. The UNISIM library also includes components that are commonly instantiated, such as I/Os and memory cells.

You can instantiate the UNISIM library components in your design (VHDL or Verilog) and simulate them during behavioral simulation. Structural simulation models generated by Simgen instantiate UNISIM library components.

Asynchronous components in the UNISIM library have zero delay. Synchronous components have a unit delay to avoid race conditions. The clock-to-out delay for these synchronous components is 100 ps.

The SIMPRIM Library is used for timing simulation. It includes all the Xilinx primitives library components used by Xilinx implementation tools. Timing simulation models generated by Simgen instantiate SIMPRIM library components.

The Xilinx CORE Generator™ software is a graphical Intellectual Property (IP) design tool for creating high-level modules like FIR Filters, FIFOs, CAMs, and other advanced IP. You can customize and pre-optimize modules to take advantage of the inherent architectural features of Xilinx FPGA devices, such as block multipliers, SRLs, fast carry logic and on-chip, single- or dual-port RAM.

The CORE Generator software HDL library models are used for behavioral simulation. You can select the appropriate HDL model to integrate into your HDL design. The models do not use library components for global signals.

The EDK library is used for behavioral simulation. It contains all the EDK IP components, precompiled for ModelSim SE and PE, or Cadence Incisive Enterprise Simulator (IES). This library eliminates the need to recompile EDK components on a per-project basis, minimizing overall compile time. The EDK IP components library is provided for VHDL only and can be encrypted.

The Xilinx Compxlib utility deploys compiled models for EDK IP components into a common location. Unencrypted EDK IP components can be compiled using Compxlib. Precompiled libraries are provided for encrypted components.

Xilinx provides the Compxlib utility to compile the HDL libraries for Xilinx-supported simulators. Compxlib compiles the UNISIM, SIMPRIM, and XilinxCoreLib libraries for supported device architectures using the tools provided by the simulator vendor. You must have an installation of the Xilinx implementation tools to compile your HDL libraries using Compxlib.

Run Compxlib with the -help option if you need to display a brief description for the available options:

compxlib -help

Each simulator uses certain environment variables that you must set before invoking Compxlib. Consult your simulator documentation to ensure that the environment is properly set up to run your simulator.

Note: Use the -p <simulator_path> option to point to the directory where the ModelSim executable is, if it is not in your path.

The following is an example of a command for compiling Xilinx libraries for MTI_SE:

Compxlib -s mti_se -arch all -l vhdl -w -dir .

This command compiles the necessary Xilinx libraries into the current working directory. Refer to the Command Line Tools User Guide for information Compxlib. Refer to the "Simulating Your Design" chapter of the Synthesis and Simulation Design Guide (UG626) to learn more about compiling and using Xilinx ISE simulation libraries. A link to the documentation website is provided in Appendix E, Additional Resources.

Figure X-Ref Target - Figure 7-1

This section describes how and when each of three FPGA simulation models are implemented, and provides instructions for creating simulation models using XPS batch mode. At specific points in the design process, Simgen creates an appropriate simulation model, as shown in the following figure.

Figure 7-1 illustrates the FPGA design simulation stages:

UG111_01_111903

Figure 7-1: FPGA Design Simulation Stages

X-Ref Target - Figure 7-2

To create a behavioral simulation model as displayed in Figure 7-2, Simgen requires an MHS file as input. Simgen creates a set of HDL files that model the functionality of the design. Optionally, Simgen can generate a compile script for a specified vendor simulator.

If specified, Simgen can generate HDL files with data to initialize block RAMs associated with any processor that exists in the design. This data is obtained from an existing Executable Linked Format (ELF) file. Figure 7-2 illustrates the behavioral simulation model generation.

Figure 7-2: Behavioral Simulation Model Generation

X-Ref Target - Figure 7-3

To create a structural simulation model as shown in the following figure, Simgen requires an MHS file as input and associated synthesized netlist files. From these netlist files, Simgen creates a set of HDL files that structurally model the functionality of the design.

Optionally, Simgen can generate a compile script for a specified vendor simulator.

If specified, Simgen can generate HDL files with data to initialize block RAMs associated with any processor that exists in the design. This data is obtained from an existing ELF file. Figure 7-3 illustrates the structural simulation model simulation generation.

Figure 7-3: Structural Simulation Model Generation

Note: The EDK design flow is modular. Platgen generates a set of netlist files that Simgen uses to generate structural simulation models.

UG111_04_101705

X-Ref Target - Figure 7-4

To create a timing simulation model, as shown in Figure 7-4, Simgen requires an MHS file as input and an associated implemented netlist file. From this netlist file, Simgen creates an HDL file that models the design and a Standard Data Format (SDF) file with the appropriate timing information. Optionally, Simgen can generate a compile script for a specified vendor simulator. If specified, Simgen can generate HDL files with data to initialize block RAMs associated with any processor that exists in the design. This data is obtained from an existing ELF file.

Figure 7-4: Timing Simulation Model Generation

Simgen allows the use of mixed language components in behavioral files for simulation. By default, Simgen takes the native language in which each component is written. Individual components cannot be mixed language. To use this feature, a mixed language simulator is required.

Xilinx IP components are written in VHDL. If a mixed language simulator is not available, Simgen can generate single language models by translating the HDL files that are not in the HDL language. The resulting translated HDL files are structural files.

Structural and Timing simulation models are always single language.

• 1. Open your project by loading your XMP file:

XPS% load xmp <filename>.xmp

• 2. Set the following simulation values at the XPS prompt.
  • a. Select the simulator of your choice using the following command:

XPS% xset simulator [ mgm | questa | ies | isim | vcs | none ]
Where:

mgm = Mentor Graphics ModelSim
questa = Mentor Graphics QuestaSim
ies = Cadence Incisive Enterprise Simulator (IES)
isim = ISE Simulator (ISIM)
vcs = Verilog Compiler code Simulator

• b. Specify the path to the Xilinx and EDK precompiled libraries using the following commands: XPS% xset sim_x_lib <path> XPS% xset sim_edk_lib <path>

• c. Select the Simulation Model using the following command:

  • XPS% xset sim_model [ behavioral | structural | timing ]

• d. Enable or disable external memory simulation using following command:

xset external_mem_sim [ 0 | 1 ]

Optionally, before setting external memory simulation flag you might need to check if a DDRx memory controller (for Virtex-6) is present in the system. Use the following command:

xget is_external_mem_present

Check for more detail in External Memory Simulation, page 83.

• 3. To generate the simulation model, type:

When the process finishes, HDL models are saved in the simulation directory.

• 4. To open the simulator, type: XPS% run sim

At the prompt, run Simgen with the MHS file and appropriate options as inputs.

simgen <system_name>.mhs [options]

Verify that your system is properly configured to run the Xilinx ISE tools. Consult the release notes and installation notes that came with your software package for more information.

Table 7-1 list the supported Simgen options:

Simgen produces all simulation files in the /simulation directory, which is located inside the /output_directory. In the /simulation directory, there is a subdirectory for each simulation model such as:

output_directory/simulation/<sim_model>
Where <sim_model> is one of: behavioral, structural, or timing

After a successful Simgen execution, the simulation directory contains the files listed in Table 7-2. The generated file extension reflects the simulator used.

Table 7-2: Simgen Output Files

Table 7-2: Simgen Output Files (Cont'd)

If a design contains banks of memory for a system, the corresponding memory simulation models can be initialized with data. You can specify a list of ELF files to associate to a given processor instance using the -pe switch.

The compiled executable files are generated with the appropriate GNU Compiler Collection (GCC) compiler or assembler, from corresponding C or assembly source code.

Note: Memory initialization of structural simulation models is only supported when the netlist file has hierarchy preserved.

For VHDL/Verilog simulation models, run Simgen with the -pe option to generate .mem files. These files contain a configuration for the system with all initialization values. For example:

simgen system.mhs -pe mblaze executable.elf -l vhdl ...
simgen system.mhs -pe mblaze executable.elf -l verilog ...

The .mem files are used along with your system to initialize memory. The BRAM blocks connected to the mblaze processor contain the data in executable.elf.

Simgen can create test bench templates. When you use the -tb switch, Simgen creates a test bench that:

• Instantiates the top-level design
• Creates default stimulus for clock and reset signals

Clock stimulus is inferred from any global port which is tagged SIGIS = CLK in the MHS file. The frequency of the clock is given by the CLK_FREQ tag. The phase of the clock is given by the CLK_PHASE tag, which takes values from 0 to 360.

Reset stimulus is inferred for all global ports tagged SIGIS = RST in the MHS file.

• The polarity of the reset signal is given by the RST_POLARITY tag.
• The length of the reset is given by the RST_LENGTH tag.

For more information about the clock and reset tags, refer to the Platform Studio Online Help.

library IEEE;
use IEEE.STD_LOGIC_1164.ALL;
library UNISIM;
use UNISIM.VCOMPONENTS.ALL;
entity system_tb is
end system_tb;
architecture STRUCTURE of system_tb is
 constant sys_clk_PERIOD : time := 10 ns;
 constant sys_reset_LENGTH : time := 160 ns;
 constant sys_clk_PHASE : time 2.5 ns;
 component system is
 port (
 sys_clk : in std_logic;
 sys_reset : in std_logic;
 rx : in std_logic;
 tx : out std_logic;
 leds : inout std_logic_vector(0 to 3)
 );
 end component;
 -- Internal signals
 signal leds : std_logic_vector(0 to 3);
 signal rx : std_logic;
 signal sys_clk : std_logic;
 signal sys_reset : std_logic;
 signal tx : std_logic;
begin

 dut : system
 port map (
 sys_clk => sys_clk,
 sys_reset => sys_reset,
 rx => rx,
 tx => tx,
 leds => leds
 );
 -- Clock generator for sys_clk
 process
 begin
 sys_clk <= '0';
   wait for (sys_clk_PHASE);
    loop
 wait for (sys_clk_PERIOD/2);
 sys_clk <= not sys_clk;
 end loop;
 end process;

 -- Reset Generator for sys_reset
 process
 begin
 sys_reset <= '0';
 wait for (sys_reset_LENGTH);
 sys_reset <= not sys_reset;
 wait;
 end process;
 -- START USER CODE (Do not remove this line)
 -- User: Put your stimulus here. Code in this
 -- section will not be overwritten.
 -- END USER CODE (Do not remove this line)
end architecture STRUCTURE;

You can add your own VHDL code between the lines tagged BEGIN USER CODE and END USER CODE. The code between these lines is maintained if simulation files are created again. Any code outside these lines will be lost if a new test bench is created.

`timescale 1 ns/10 ps
`uselib lib=unisims_ver
module system_tb
 (
 );
 real sys_clk_PERIOD = 10;
 real sys_clk_PHASE = 2.5;
 real sys_reset_LENGTH = 160;
 // Internal signals
 reg [0:3] leds;
 reg rx;
 reg sys_clk;
 reg sys_reset;
 reg tx;
 system
 dut (
 .sys_clk ( sys_clk ),
 .sys_reset ( sys_reset ),
 .rx ( rx ),
 .tx ( tx ),
 .leds ( leds )
 );

// Clock generator for sys_clk
 initial
 begin
 sys_clk = 1'b0;
    #(sys_clk_PHASE);forever
    #(sys_clk_PERIOD/2)
    sys_clk = ~sys_clk;
 end
 // Reset Generator for sys_reset
 initial
 begin
 sys_reset = 1'b0;
 #sys_clk_LENGTH sys_reset = ~sys_reset;
 end
 // START USER CODE (Do not remove this line)
 // User: Put your stimulus here. Code in this
 // section will be not be overwritten.
 // END USER CODE (Do not remove this line)
endmodule

You can add your own Verilog code between the lines tagged BEGIN USER CODE and END USER CODE. The code between these lines is maintained if simulation files are created again. Any code outside these lines is lost if you create a new test bench.

Simgen provides simulation models for external memory and has automated support to instantiate memory models in the simulation testbench and performs connection with the design under test.

To compile memory model into the user library, Simgen also generates simulator-specific compilation/elaboration commands into respective helper/setup scripts.

The restrictions on external memory simulation models are:

• 1. Supported for DDR2 and DDR3 (Virtex®-6, Kintex®-7 and Virtex-7 DDRx IPs ).
• 2. Supported for behavioral simulation only.
• 3. When you select external memory simulation, the memory model is instantiated only if an AXI DDRx memory controller is present. The IP nomenclature is axi_<device family>_ddrx. If the AXI memory controller is not present, Simgen continues to generate the testbench without the external memory model.
• 4. The following are not supported:
  • 72-bit wide memory interface (for example, with ECC)
  • RDIMM memory types

To enable external memory simulation, pass the following flag to Simgen: -external_mem_sim [yes|no]

By default, Simgen uses memory model files generated by MIG, as follows:

• <XPS project directory>/__xps/<DDRx_Inst>/[ddr3|ddr2]_model.v
• <XPS project directory>/__xps/<DDRx_Inst>/ [ddr3|ddr2]_model_parameters.vh

It is not necessary to copy any other memory model files. You can specify other memory model files by placing the file in the with the name [ddr2|ddr3].v/vhd.

Note: Simgen is tested with MIG-generated memory model files; to use any customized simulation model files you must download and specify those files from vendor websites, provided that it is renamed accordingly. You must also have a copy of the [ddr2|ddr3]_model_parameters.vh.

An additional Simgen command line option lets you specify the external simulation file: -externalmem_module <_external memory entity/module name>

Note: This option is not supported in the XPS GUI or XPS "no window" mode.

The following are optional, recommended steps when working in XPS:

• 1. For better tracking model initialization on the simulator waveforms, expose the phy_init_done or the init_calib_complete pin on the top-level. To make the port external:

• a. Go to XPS > System Assembly View.

• b. Select the Port tab and expand the DDRx_SDRAM IP instance.

• c. Select the pin. For:

  • - Virtex-6, the pin name is phy_init_done
  • - Kintex-7, the pin name is init_calib_complete

• d. In the net drop-down, select Make External.

• 2. To speed simulation, manually set the *_init_call to FAST in the MHS (this feature is not available in the GUI IP configuration).

Under the axi*ddrx IP instance Add PARAMETER *_ = FAST to the MHS, where the parameter name for:

• - Virtex-6 is C_BYPASS_INIT_CAL
• - Kintex-7 is C_SIM_BYPASS_INIT_CAL
• 3. For a Micron memory model higher than 1.62, the model files must have density defined before compilation. Add the `define <*density*> construct into the model file, where is: den1024Mb, den2048Mb, or den4096Mb.

Note: This step is not required for version 1.60 micron memory models.

• 4. Configure the Memory part, Memory datawidth, and other parameters using the DDRx IP Configuration MIG window.

• 1. The memory model is always instantiated with x8 configuration; consequently, if the DQ_WIDTH parameter is 64 then eight instances are generated in the testbench and other parameters are modified accordingly.
• 2. External memory simulation with multiple instances of DDRx memory controller in XPS is not supported.
• 3. External memory simulation is supported only for Micron Memory Models used with XPS MIG.
• 4. During simulation the following initialization errors can be observed in the simulator console, but can be ignored for behavioral simulation:

system_axi_tb.inst_ddr_00.dqs_neg_timing_check: at time 5485244.0 ps ERROR: tDQSH violation on DQS bit 0 by 1039.0 ps. system_axi_tb.inst_ddr_03.cmd_task: at time 3438850.0 ps ERROR: Load Mode 0 Illegal value. Reserved address bits must be programmed to zero.

• 5. There is no support from Simgen to allow an application to load an ELF into external memory.
• 6. Other, non-supported external memory models must be manually instantiated and connected in the simulation testbench and initialized according to the model specifications.

When simulating your design, there are some special considerations to keep in mind, such as the global reset and 3-state nets. Xilinx ISE tools provide detailed information on how to simulate your VHDL or Verilog design. Refer to the "Simulating Your Design" chapter in the ISE Synthesis and Simulation Design Guide (UG626), for more information. Appendix E, Additional Resources, contains a link to the document website.

Helper scripts generated at the test harness (or testbench) level are simulator setup scripts. When run, the setup script performs initialization functions and displays usage instructions for creating waveform and list (ModelSim only) windows using the waveform and list scripts. The top-level scripts invoke instance-specific scripts. You might need to edit hierarchical path names in the helper scripts for test harnesses not created by Simgen.

Commands in the scripts are commented or not commented to define the displayed set of signals. Editing the top-level waveform or list scripts lets you include or exclude signals for an instance; editing the instance-level scripts lets you include or exclude individual port signals. For timing simulations, only top-level ports are displayed.

This chapter describes the Library Generator utility, Libgen, which is required for the generation of libraries and drivers for embedded processors.

Libgen is the first Embedded Design Kit (EDK) tool that you run to configure libraries and device drivers. Libgen takes an XML hardware specification file and a Microprocessor Software Specification (MSS) file that you create. The hardware specification file defines the hardware system to Libgen and the MSS file describes the content and configuration of the software platform for a particular processor. Components are instantiated as blocks in the MSS file, and configuration is specified using parameters. Libgen reads the MSS file and generates the software components, configuring them as specified in the MSS.

For further description on generating the XML hardware specification file refer to the Software Development Kit (SDK) documentation in the SDK Online Help. For further description of the MSS file format, refer to the "Microprocessor Software Specification (MSS)" chapter in the Platform Specification Format Reference Manual. A link to the document is supplied in Appendix E, Additional Resources.

Note: EDK includes a Format Revision tool to convert older MSS file formats to a new MSS format. Refer to Chapter 15, "Version Management Tools (revup)," for more information.

To run Libgen, type the following:

libgen [options] <*filename>*.mss

Table 8-1 list the supported Libgen command options.

Figure 8-1 shows the directory structure of peripherals, drivers, libraries, and operating systems.

By default, Libgen scans the following repositories for software components:

• $XILINX_EDK/sw/lib/XilinxProcessorIPLib
• $XILINX_EDK/sw/lib
• $XILINX_EDK/sw/ThirdParty

It also treats the directory from which Libgen is invoked as a repository and therefore scans for cores under sub-directories with standard directory names, such as drivers, bsp, and sw_services. Figure 8-2 shows the repository directory structure.

Figure 8-2: Repository Directory Structure

Libgen uses a search priority mechanism to locate drivers and libraries, as follows:

• 1. Search the current working directory:
• 2. Search the repositories under the library path directory specified using the -lp option:
• 3. Search the default repositories as described in "Default Repositories."

Libgen generates directories and files in the <YOUR_PROJECT> directory. For every processor instance in the MSS file, Libgen generates a directory with the name of the processor instance. Within each processor instance directory, Libgen generates the following directories and files, which are described in the following subsections:

• The include Directory
• lib Directory
• libsrc Directory
• code Directory

The include directory contains C header files needed by drivers. The include file xparameters.h is also created through Libgen in this directory. This file defines base addresses of the peripherals in the system, #defines needed by drivers, OSs, libraries and user programs, as well as function prototypes.

• The Microprocessor Driver Definition (MDD) file for each driver specifies the definitions that must be customized for each peripheral that uses the driver. See the "Microprocessor Driver Definition (MDD)" chapter in the Platform Specification Format Reference Manual (UG642) for more information.
• The Microprocessor Library Definition (MLD) file for each OS and library specifies the definitions that you must customize. See the "Microprocessor Library Definition (MLD)" chapter in the Platform Specification Format Reference Manual (UG642) for more information.

A link to the Platform Specification Format Reference Manual, (UG642), is in Appendix E, Additional Resources.

The lib directory contains libc.a, libm.a, and libxil.a libraries. The libxil library contains driver functions that the particular processor can access. For more information about the libraries, refer to the introductory section of the OS and Libraries Document Collection (UG643). A link to the document is in Appendix E, Additional Resources.

The libsrc directory contains intermediate files and make files needed to compile the OSs, libraries, and drivers. The directory contains peripheral-specific driver files, BSP files for the OS, and library files that are copied from the EDK and your driver, OS, and library directories. Refer to the Drivers, page 92, OS Block, page 93, and Libraries, page 93 sections of this chapter for more information.

The code directory is a repository for EDK executables. Libgen creates an xmdstub.elf file (for MicroBlaze™ on-board debug) in this directory.

Note: Libgen removes these directories every time you run the tool. You must put your sources, executables, and any other files in an area that you create.

This section provides an overview of generating libraries and drivers.

The hardware specification file and the MSS files define a system. For each processor in the system, Libgen finds the list of addressable peripherals. For each processor, a unique list of drivers and libraries are built. Libgen does the following for each processor:

• Builds the directory structure as defined in the Output Files, page 89.
• Copies the necessary source files for the drivers, OSs, and libraries into the processor instance specific area: OUTPUT_DIR/processor_instance_name/libsrc.
• Calls the Design Rule Check (DRC) procedure, which is defined as an option in the MDD or MLD file, for each of the drivers, OSs, and libraries visible to the processor.
• Calls the generate Tcl procedure (if defined in the Tcl file associated with an MDD or MLD file) for each of the drivers, OSs, and libraries visible to the processor. This generates the necessary configuration files for each of the drivers, OSs, and libraries in the include directory of the processor.
• Calls the post_generate Tcl procedure (if defined in the Tcl file associated with an MDD or MLD file) for each of the drivers, OSs, and libraries visible to the processor.
• Runs make (with targets include and libs) for the OSs, drivers, and libraries specific to the processor. On the Linux platform, the gmake utility is used, while on NT platforms, make is used for compilation.
• Calls the execs_generate Tcl procedure (if defined in the Tcl file associated with an MDD or MLD file) for each of the drivers, OSs, and libraries visible to the processor.

A driver or library has two associated data files:

• Data Definition File (MDD or MLD file): This file defines the configurable parameters for the driver, OS, or library.
• Data Generation File (Tcl): This file uses the parameters configured in the MSS file for a driver, OS, or library to generate data. Data generated includes but is not limited to generation of header files, C files, running DRCs for the driver, OS, or library, and generating executables.

The Tcl file includes procedures that Libgen calls at various stages of its execution. Various procedures in a Tcl file include:

• DRC The name of DRC given in the MDD or MLD file

• generate A Libgen-defined procedure that is called after files are copied

• post_generate A Libgen-defined procedure that is called after generate has been called on all drivers, OSs, and libraries

• execs_generate A Libgen-defined procedure that is called after the BSPs, libraries, and drivers have been generated

• Note: The data generation (Tcl) file is not necessary for a driver, OS, or library.

For more information about the Tcl procedures and MDD/MLD related parameters, refer to the "Microprocessor Driver Definition (MDD)" and "Microprocessor Library Definition (MLD)" chapters in the Platform Specification Format Reference Manual (UG642). A link to the document is supplied in Appendix E, Additional Resources.

For a complete description of the MSS format and all the parameters that MSS supports, refer to the "Microprocessor Software Specification (MSS)" chapter in the Platform Specification Format Reference Manual. A link to the document is supplied in Appendix E, Additional Resources.

Most peripherals require software drivers. The EDK peripherals are shipped with associated drivers, libraries and BSPs. Refer to the Device Driver Programmer Guide for more information on driver functions. A link to the guide is supplied in Appendix E, Additional Resources.

The MSS file includes a driver block for each peripheral instance. The block contains a reference to the driver by name (DRIVER_NAME parameter) and the driver version (DRIVER_VER). There is no default value for these parameters.

A driver has an associated MDD file and a Tcl file.

• The driver MDD file is the data definition file and specifies all configurable parameters for the drivers.
• Each MDD file has a corresponding Tcl file which generates data that includes generation of header files, generation of C files, running DRCs for the driver, and generating executables.

You can write your own drivers. These drivers must be in a specific directory under <YOUR_PROJECT>/<driver_name> or <library_name>/drivers, as shown in Figure 8-1 on page 88.

• The DRIVER_NAME attribute allows you to specify any name for your drivers, which is also the name of the driver directory.
• The source files and make file for the driver must be in the /src subdirectory under the /<driver_name> directory.
• The make file must have the targets /include and /libs.
• Each driver must also contain an MDD file and a Tcl file in the /data subdirectory.

Open the existing EDK driver files to get an understanding of the required structure.

Refer to the "Microprocessor Driver Definition (MDD)" chapter in the Platform Specification Format Reference Manual for details on how to write an MDD and its corresponding Tcl file. A link to the document is supplied in Appendix E, Additional Resources.

The MSS file includes a library block for each library. The library block contains a reference to the library name (LIBRARY_NAME parameter) and the library version (LIBRARY_VER). There is no default value for these parameters. Each library is associated with a processor instance specified using the PROCESSOR_INSTANCE parameter. The library directory contains C source and header files and a make file for the library.

The MLD file for each library specifies all configurable options for the libraries and each MLD file has a corresponding Tcl file.

You can write your own libraries. These libraries must be in a specific directory under <YOUR_PROJECT>/swservices or <libraryname>/sw_services as shown in Figure 8-1 on page 88.

• The LIBRARY_NAME attribute lets you specify any name for your libraries, which is also the name of the library directory.
• The source files and make file for the library must be in the /src subdirectory under the /<library_name> directory.
• The make file must have the targets /include and /libs.
• Each library must also contain an MLD file and a Tcl file in the /data subdirectory.

Refer to the existing EDK libraries for more information about the structure of the libraries.

Refer to the "Microprocessor Library Definition (MLD)" chapter in the Platform Specification Format Reference Manual (UG642) for details on how to write an MLD and its corresponding Tcl file. A link to the document is in Appendix E, Additional Resources.

The MSS file includes an OS block for each processor instance. The OS block contains a reference to the OS name (OS_NAME parameter), and the OS version (OS_VER). There is no default value for these parameters. The bsp directory contains C source and header files and a make file for the OS.

The MLD file for each OS specifies all configurable options for the OS. Each MLD file has a corresponding Tcl file associated with it. Refer to the "Microprocessor Library Definition (MLD)" and "Microprocessor Software Specification (MSS)" chapters in the Platform Specification Format Reference Manual, (UG642). A link to the document is in Appendix E, Additional Resources.

You can write your own OSs. These OSs must be in a specific directory under <YOUR_PROJECT>/bsp or <library_name>/bsp as shown in Figure 8-1 on page 88.

• The OS_NAME attribute allows you to specify any name for your OS, which is also the name of the OS directory.
• The source files and make file for the OS must be in the src subdirectory under the /<os_name> directory.
• The make file should have the targets /include and /libs.
• Each OS must contain an MLD file and a Tcl file in the /data subdirectory.

Look at the existing EDK OSs to understand the structures. See the "Microprocessor Library Definition (MLD)" chapter in the Platform Specification Format Reference Manual (UG642) for details on how to write an MLD and its corresponding Tcl file. The Device Driver Programmer Guide is located in the /doc/usenglish folder of your EDK installation, file name: xilinx_drivers_guide.pdf.

This chapter describes the GNU compiler tools.

EDK includes the GNU compiler collection (GCC) for both the PowerPC® (405 and 440) processors and the MicroBlaze™ processor.

• The EDK GNU tools support both the C and C++ languages.
• The MicroBlaze GNU tools include mb-gcc and mb-g++ compilers, mb-as assembler and mb-ld linker*.*
• The PowerPC processor tools include powerpc-eabi-gcc and powerpc-eabi-g++ compilers, powerpc-eabi-as assembler and the powerpc-eabi-ld linker.
• The toolchains also include the C, Math, GCC, and C++ standard libraries.

The compiler also uses the common binary utilities (referred to as binutils), such as an assembler, a linker, and object dump. The PowerPC and MicroBlaze compiler tools use the GNU binutils based on GNU version 2.16 of the sources. The concepts, options, usage, and exceptions to language and library support are described Appendix A, "GNU Utilities."

This section discusses the common features of both the MicroBlaze and PowerPC processor compilers. Figure 9-1 displays the GNU tool flow.

UG111_05_101905

Figure 9-1: GNU Tool Flow

The GNU compiler is named mb-gcc for MicroBlaze and powerpc-eabi-gcc for PowerPC. The GNU compiler is a wrapper that calls the following executables:

• Pre-processor (cpp0) This is the first pass invoked by the compiler. The pre-processor replaces all macros with definitions as defined in the source and header files.
• Machine and language specific compiler This compiler works on the pre-processed code, which is the output of the first stage. The language-specific compiler is one of the following:
  • C Compiler (cc1) The compiler responsible for most of the optimizations done on the input C code and for generating assembly code.
  • C++ Compiler (cc1plus) The compiler responsible for most of the optimizations done on the input C++ code and for generating assembly code.
• Assembler (mb-as for MicroBlaze and powerpc-eabi-as for PowerPC processors*)* The assembly code has mnemonics in assembly language. The assembler converts these to machine language. The assembler also resolves some of the labels generated by the compiler. It creates an object file, which is passed on to the linker.
• Linker (mb-ld for MicroBlaze and powerpc-eabi-ld for PowerPC processors) Links all the object files generated by the assembler. If libraries are provided on the command line, the linker resolves some of the undefined references in the code by linking in some of the functions from the assembler.

Executable options are described in:

• Commonly Used Compiler Options: Quick Reference, page 101
• Linker Options, page 105
• MicroBlaze Compiler Options: Quick Reference, page 111
• MicroBlaze Linker Options, page 118
• PowerPC Compiler Options: Quick Reference, page 126.

Note: From this point forward the references to GCC in this chapter refer to both the MicroBlaze compiler, mb-gcc, and the PowerPC processor compiler, powerpc-eabi-gcc, and references to G++ refer to both the MicroBlaze C++ compiler, mb-g++, and the PowerPC processor C++ compiler, powerpc-eabi-g++.

To use the GNU compiler, type:

<Compiler_Name> options files...

where <Compiler_Name> is powerpc-eabi-gcc or mb-gcc. To compile C++ programs, you can use either the powerpc-eabi-g++ or the mb-g++ command.

The compilers take one or more of the following files as input:

• C source files
• C++ source files
• Assembly files
• Object files
• Linker scripts

Note: These files are optional. If they are not specified, the default linker script embedded in the linker (mb-ld or powerpc-eabi-ld) is used.

The default extensions for each of these types are listed in Table 9-1. In addition to the files mentioned above, the compiler implicitly refers to the libraries files libc.a, libgcc.a, libm.a, and libxil.a. The default location for these files is the EDK installation directory. When using the G++ compiler, the libsupc++.a and libstdc++.a files are also referenced. These are the C++ language support and C++ platform libraries, respectively.

The compiler generates the following files as output:

• An ELF file. The default output file name is a.exe on Windows.
• Assembly file, if -save-temps or -S option is used.
• Object file, if -save-temps or -c option is used.
• Preprocessor output, .i or .ii file, if -save-temps option is used.

The GNU compiler determines the type of your file from the file extension. Table 9-1 lists the valid extensions and the corresponding file types. The GCC wrapper calls the appropriate lower level tools by recognizing these file types.

Table 9-1: File Extensions

Table 9-2 lists the libraries necessary for the powerpc_eabi_gcc and mb_gcc compilers.

Table 9-2: Libraries Used by the Compilers

Libraries are linked in automatically by both compilers. If the standard libraries are overridden, the search path for these libraries must be given to the compiler. The libxil.a is modified by the Library Generator tool, Libgen, to add driver and library routines.

The GCC compiler recognizes both C and C++ dialects and generates code accordingly. By GCC convention, it is possible to use either the GCC or the G++ compilers equivalently on a source file. The compiler that you use and the extension of your source file determines the dialect used on the input and output files.

When using the GCC compiler, the dialect of a program is always determined by the file extension, as listed in Table 9-1, page 98. If a file extension shows that it is a C++ source file, the language is set to C++. This means that if you have compile C code contained in a CC file, even if you use the GCC compiler, it automatically mangles function names.

The primary difference between GCC and G++ is that G++ automatically sets the default language dialect to C++ (irrespective of the file extension), and if linking, automatically pulls in the C++ support libraries. This means that even if you compile C code in a .c file with the G++ compiler, it will mangle names.

Name mangling is a concept unique to C++ and other languages that support overloading of symbols. A function is said to be overloaded if the same function can perform different actions based on the arguments passed in, and can return different return values. To support this, C++ compilers encode the type of the function to be invoked in the function name, avoiding multiple definitions of a function with the same name.

Be careful about name mangling if you decide to follow a mixed compilation mode, with some source files containing C code and some others containing C++ code (or using GCC for compiling certain files and G++ for compiling others). To prevent name mangling of a C symbol, you can use the following construct in the symbol declaration.

#ifdef __cplusplus
extern "C" {
£endif
int foo();
int morefoo();
#ifdef __cplusplus
}
£endif

Make these declarations available in a header file and use them in all source files. This causes the compiler to use the C dialect when compiling definitions or references to these symbols.

Note: All EDK drivers and libraries follow these conventions in all the header files they provide. You must include the necessary headers, as documented in each driver and library, when you compile with G++. This ensures that the compiler recognizes library symbols as belonging to "C" type.

When compiling with either variant of the compiler, to force a file to a particular dialect, use the -x lang switch. Refer to the GCC manual on the GNU website for more information on this switch. A link to the document is provided in the Appendix E, "Additional Resources."

• When using the GCC compiler, libstdc++.a and libsupc++.a are not automatically linked in.
• When compiling C++ programs, use the G++ variant of the compiler to make sure all the required support libraries are linked in automatically.
• Adding -lstdc++ and -lsupc++ to the GCC command are also possible options.

For more information about how to invoke the compiler for different languages, refer to the GNU online documentation. A link to the documentation is provided in the Appendix E, "Additional Resources."

The summary below lists compiler options that are common to the compilers for MicroBlaze and PowerPC processors.

Note: The compiler options are case sensitive.

To jump to a detailed description for a given option, click its name.

-E

Preprocess only; do not compile, assemble and link. The preprocessed output displays on the standard out device.

Compile only; do not assemble and link. Generates a .s file.

Compile and Assemble only; do not link. Generates a .o file.

This option adds DWARF2-based debugging information to the output file. The debugging information is required by the GNU debugger, mb-gdb or powerpc-eabi-gdb. The debugger provides debugging at the source and the assembly level. This option adds debugging information only when the input is a C/C++ source file.

Use this option for adding STABS-based debugging information on assembly (.S) files and assembly file symbols at the source level. This is an assembler option that is provided directly to the GNU assembler, mb-as or powerpc-eabi-as. If an assembly file is compiled using the compiler mb-gcc or powerpc-eabi-gcc, prefix the option with -Wa.

The GNU compiler provides optimizations at different levels. The optimization levels in the following table apply only to the C and C++ source files.

Table 9-3: Optimizations for Values of n

Note: Optimization levels 1 and above cause code re-arrangement. While debugging your code, use of no optimization level is recommended. When an optimized program is debugged through gdb, the displayed results might seem inconsistent.

This option executes the compiler and all the tools underneath the compiler in verbose mode. This option gives complete description of the options passed to all the tools. This description is helpful in discovering the default options for each tool.

The GNU compiler provides a mechanism to save the intermediate files generated during the compilation process. The compiler stores the following files:

• Preprocessor output –input_file_name.i for C code and input_file_name.ii for C++ code
• Compiler (cc1) output in assembly format input_file_name.s
• Assembler output in ELF format input_file_name.s

The compiler saves the default output of the entire compilation as a.out.

The compiler stores the default output of the compilation process in an ELF file named a.out. You can change the default name using -o output_file_name. The output file is created in ELF format.

• **-Wp,***option*
• **-Wa,***option*

The compiler, mb-gcc or powerpc-eabi-gcc, is a wrapper around other executables such as the preprocessor, compiler (cc1), assembler, and the linker. You can run these components of the compiler individually or through the top level compiler.

There are certain options that are required by tools, but might not be necessary for the top-level compiler. To run these commands, use the options listed in the following table.

Table 9-4: Tool-Specific Options Passed to the Top-Level GCC Compiler

Use this option with any GNU compiler to get more information about the available options.

You can also consult the GCC manual. A link to the manual is in Appendix E, "Additional Resources."

Add directory to the C run time library search paths.

Add directory to library search path.

Add directory to header search path.

Search library for undefined symbols.

Note: The compiler prefixes "lib" to the library name indicated in this command line switch.

By default, the compiler searches only the standard libraries, such as libc, libm, and libxil. You can also create your own libraries. You can specify the name of the library and where the compiler can find the definition of these functions. The compiler prefixes lib to the library name that you provide.

The compiler is sensitive to the order in which you provide options, particularly the -l command line switch. Provide this switch only after all of the sources in the command line.

For example, if you create your own library called libproject.a. you can include functions from this library using the following command:

Compiler Source_Files -L${LIBDIR} -l project

Caution! If you supply the library flag -l library_name before the source files, the compiler does not find the functions called from any of the sources. This is because the compiler search is only done in one direction and it does not keep a list of available libraries.

This option indicates the directories in which to search for the libraries. The compiler has a default library search path, where it looks for the standard library. Using the -L option, you can include some additional directories in the compiler search path.

This option searches for header files in the /<dir_name> directory before searching the header files in the standard path.

The compilers, mb-gcc and powerpc-eabi-gcc, search certain paths for libraries and header files. The search paths on the various platforms are described below.

The compilers search libraries in the following order:

• 1. Directories are passed to the compiler with the -L <dir_name> option.
• 2. Directories are passed to the compiler with the -B <dir_name> option.
• 3. The compilers search the following libraries:
  • a. ${XILINX_EDK}/gnu/processor/platform/processor-lib/lib

b. ${XILINX_EDK}/lib/processor

Note: Processor indicates powerpc-eabi for the PowerPC processor and microblaze for MicroBlaze.

The compilers search header files in the following order:

• 1. Directories are passed to the compiler with the -I <dir_name> option.
• 2. The compilers search the following header files:
  • a. ${XILINX_EDK}/gnu/processor/platform/lib/gcc/processor/ {gcc version}/include
  • b. ${XILINX_EDK}/gnu/processor/platform/processor-lib/include

The compilers search initialization files in the following order:

• 1. Directories are passed to the compiler with the -B <dir_name> option.
• 2. The compilers search ${XILINX_EDK}/gnu/processor/platform/ processor-lib/lib.
• 3. The compilers search the following libraries:
  • a. $XILINXEDK/gnu//platform/_/lib
  • b. $XILINX_EDK/lib/processor

Where:

• is powerpc-eabi for PowerPC processors, and microblaze for MicroBlaze processors.
• is powerpc-eabi for PowerPC processors, and microblaze-xilinx-elf for MicroBlaze processors.

Note: platform indicates lin for Linux, lin64 for Linux 64-bit and nt for Windows Cygwin.

The total memory allocated for the stack can be modified using this linker option. The variable _STACK_SIZE is the total space allocated for the stack. The _STACK_SIZE variable is given the default value of 100 words, or 400 bytes. If your program is expected to need more than 400 bytes for stack and heap combined, it is recommended that you increase the value of _STACK_SIZE using this option. The value is in bytes.

In certain cases, a program might need a bigger stack. If the stack size required by the program is greater than the stack size available, the program tries to write in other, incorrect, sections of the program, leading to incorrect execution of the code.

Note: A minimum stack size of 16 bytes (0x0010) is required for programs linked with the Xilinx-provided C runtime (CRT) files.

The total memory allocated for the heap can be controlled by the value given to the variable _HEAP_SIZE. The default value of _HEAP_SIZE is zero.

Dynamic memory allocation routines use the heap. If your program uses the heap in this fashion, then you must provide a reasonable value for _HEAP_SIZE.

For advanced users: you can generate linker scripts directly from XPS.

The MicroBlaze and PowerPC processors use 32-bit logical addresses and can address any memory in the system in the range 0x0 to 0xFFFFFFFF. This address range can be categorized into reserved memory and I/O memory.

Reserved memory has been defined by the hardware and software programming environment for privileged use. This is typically true for memory containing interrupt vector locations and operating system level routines. Table 9-5 lists the reserved memory locations for MicroBlaze and PowerPC processors as defined by the processor hardware. For more information on these memory locations, refer to the corresponding processor reference manuals.

Note: In addition to these memories that are reserved for hardware use, your software environment can reserve other memories. Refer to the manual of the particular software platform that you are using to find out if any memory locations are deemed reserved.

Table 9-5: Hardware Reserved Memory Locations

I/O memory refers to addresses used by your program to communicate with memory-mapped peripherals on the processor buses. These addresses are defined as a part of your hardware platform specification.

User and Program memory refers to all the memory that is required for your compiled executable to run. By convention, this includes memories for storing instructions, read-only data, read-write data, program stack, and program heap. These sections can be stored in any addressable memory in your system. By default the compiler generates code and data starting from the address listed in Table 9-5 and occupying contiguous memory locations. This is the most common memory layout for programs. You can modify the starting location of your program by defining (in the linker) the symbol _TEXT_START_ADDR for MicroBlaze and _START_ADDR for PowerPC processors.

In special cases, you might want to partition the various sections of your ELF file across different memories. This is done using the linker command language (refer to the Linker Scripts, page 110 for details). The following are some situations in which you might want to change the memory map of your executable:

• When partitioning large code segments across multiple smaller memories
• Remapping frequently executed sections to fast memories
• Mapping read-only segments to non-volatile flash memories

No restrictions apply to how you can partition your executable. The partitioning can be done at the output section level, or even at the individual function and data level. The resulting ELF can be non-contiguous, that is, there can be "holes" in the memory map. Ensure that you do not use documented reserved locations.

Alternatively, if you are an advanced user and want to modify the default binary data provided by the tools for the reserved memory locations, you can do so. In this case, you must replace the default startup files and the memory mappings provided by the linker.

X-Ref Target - Figure 9-2

An executable file is created by concatenating input sections from the object files (.o files) being linked together. The compiler, by default, creates code across standard and well-defined sections. Each section is named based on its associated meaning and purpose. The various standard sections of the object file are displayed in the following figure.

In addition to these sections, you can also create your own custom sections and assign them to memories of your choice.

Sectional Layout of an object or an Executable File

X11005

The reserved sections that you would not typically modify include:.init, .fini, .ctors, .dtors, .got,.got2, and .eh_frame.

This section of the object file contains executable program instructions. This section has the x (executable), r (read-only) and i (initialized) flags. This means that this section can be assigned to an initialized read-only memory (ROM) that is addressable from the processor instruction bus.

This section contains read-only data. This section has the r (read-only) and the i (initialized) flags. Like the .text section, this section can also be assigned to an initialized, read-only memory that is addressable from the processor data bus.

This section is similar to the .rodata section. It contains small read-only data of size less than 8 bytes. All data in this section is accessed with reference to the read-only small data anchor. This ensures that all the contents of this section are accessed using a single instruction. You can change the size of the data going into this section with the -G option to the compiler. This section has the r (read-only) and the i (initialized) flags.

This section contains read-write data and has the w (read-write) and the i (initialized) flags. It must be mapped to initialized random access memory (RAM). It cannot be mapped to a ROM.

This section contains small read-write data of a size less than 8 bytes. You can change the size of the data going into this section with the -G option. All data in this section is accessed with reference to the read-write small data anchor. This ensures that all contents of the section can be accessed using a single instruction. This section has the w (read-write) and the i (initialized) flags and must be mapped to initialized RAM.

This section contains small, read-only un-initialized data of a size less than 8 bytes. You can change the size of the data going into this section with the -G option. This section has the r (read) flag and can be mapped to ROM.

This section contains small un-initialized data of a size less than 8 bytes. You can change the size of the data going into this section with the -G option. This section has the w (read-write) flag and must be mapped to RAM.

This section contains un-initialized data. This section has the w (read-write) flag and must be mapped to RAM.

This section contains uninitialized data that is used as the global program heap. Dynamic memory allocation routines allocate memory from this section. This section must be mapped to RAM.

This section contains uninitialized data that is used as the program stack. This section must be mapped to RAM. This section is typically laid out right after the .heap section. In some versions of the linker, the .stack and .heap sections might appear merged together into a section named .bss_stack.

This section contains language initialization code and has the same flags as .text. It must be mapped to initialized ROM.

This section contains language cleanup code and has the same flags as .text. It must be mapped to initialized ROM.

This section contains a list of functions that must be invoked at program startup and the same flags as .data and must be mapped to initialized RAM.

This section contains a list of functions that must be invoked at program end, the same flags as .data, and it must be mapped to initialized RAM.

This section contains pointers to program data, the same flags as .data, and it must be mapped to initialized RAM.

This section contains frame unwind information for exception handling. It contains the same flags as .rodata, and can be mapped to initialized ROM.

This section holds uninitialized thread-local data that contribute to the program memory image. This section has the same flags as .bss, and it must be mapped to RAM.

This section holds initialized thread-local data that contribute to the program memory image. This section must be mapped to initialized RAM.

This section holds language specific data. This section must be mapped to initialized RAM.

This section contains information necessary for registering compiled Java classes. The contents are compiler-specific and used by compiler initialization functions. This section must be mapped to initialized RAM.

This section contains information necessary for doing fixup, such as the fixup page table, and the fixup record table. This section must be mapped to initialized RAM.

The linker utility uses commands specified in linker scripts to divide your program on different blocks of memories. It describes the mapping between all of the sections in all of the input object files to output sections in the executable file. The output sections are mapped to memories in the system. You do not need a linker script if you do not want to change the default contiguous assignment of program contents to memory. There is a default linker script provided with the linker that places section contents contiguously.

You can selectively modify only the starting address of your program by defining the linker symbol _TEXT_START_ADDR on MicroBlaze processors, or _START_ADDR on PowerPC processors, as displayed in this example:

mb-gcc <input files and flags> -Wl,-defsym -Wl,_TEXT_START_ADDR=0x100

powerpc-eabi-gcc <input files and flags> -Wl,-defsym
-Wl,_TEXT_START_ADDR=0x2000

mb-ld <.o files> -defsym _TEXT_START_ADDR=0x100

The choices of the default script that will be used by the linker from the $XILINXEDK/ gnu/<_procname>/<platform>/<processor_name>/lib/ ldscripts area are described as follows:

• elf32**.x is used by default when none of the following cases apply.
• elf32**.xn is used when the linker is invoked with the -n option.
• elf32**.xbn is used when the linker is invoked with the -N option.
• elf32**.xr is used when the linker is invoked with the -r option.
• elf32**.xu is used when the linker is invoked with the -Ur option.

where = ppc or microblaze, <processor_name> = powerpc-eabi or microblaze, and = lin or nt.

To use a linker script, provide it on the GCC command line. Use the command line option -T <script> for the compiler, as described below:

compiler -T <linker_script>

If the linker is executed on its own, include the linker script as follows:

linker -T <linker_script>

This tells GCC to use your linker script in the place of the default built-in linker script. Linker scripts can be generated for your program from within XPS and SDK.

In XPS or SDK, select Tools > Generate Linker Script.

This opens up the linker script generator utility. Mapping sections to memory is done here. Stack and Heap size can be set, as well as the memory mapping for Stack and Heap. When the linker script is generated, it is given as input to GCC automatically when the corresponding application is compiled within XPS or SDK.

Linker scripts can be used to assign specific variables or functions to specific memories. This is done through "section attributes" in the C code. Linker scripts can also be used to assign specific object files to sections in memory. These and other features of GNU linker scripts are explained in the GNU linker documentation, which is a part of the online binutils manual. A link to the GNU manuals is supplied in the Appendix E, "Additional Resources." For a specific list of input sections that are assigned by MicroBlaze and PowerPC processor linker scripts, see "MicroBlaze Linker Script Sections" on page 119, and "PowerPC Processor Linker Script Sections" on page 128.

The MicroBlaze GNU compiler is derived from the standard GNU sources as the Xilinx port of the compiler. The features and options that are unique to the MicroBlaze compiler are described in the sections that follow. When compiling with the MicroBlaze compiler, the pre-processor provides the definition MICROBLAZE automatically. You can use this definition in any conditional code.

The mb-gcc compiler for the Xilinx™ MicroBlaze soft processor introduces new options as well as modifications to certain options supported by the GNU compiler tools. The new and modified options are summarized in this chapter.

Click an option name below to view its description.

This option directs the compiler to generate code suited to MicroBlaze hardware version v.X.YY.Z. To get the most optimized and correct code for a given processor, use this switch with the hardware version of the processor.

The -mcpu switch behaves differently for different versions, as described below:

• Pr-v3.00.a: Uses 3-stage processor pipeline mode. Does not inhibit exception causing instructions being moved into delay slots.
• v3.00.a and v4.00.a: Uses 3-stage processor pipeline model. Inhibits exception causing instructions from being moved into delay slots.
• v5.00.a and later: Uses 5-stage processor pipeline model. Does not inhibit exception causing instructions from being moved into delay slots.

Use these options to select the endianness of the target machine for which code is being compiled. The endianness of the binary object file produced is also set appropriately based on this switch. The GCC driver passes switches to the sub tools (as, cc1, cc1plus, ld) to set the corresponding endianness in the sub tool.

The default is -mbig-endian.

Note: You cannot link together object files of mixed endianness.

This option permits use of hardware multiply instructions for 32-bit multiplications.

The MicroBlaze processor has an option to turn the use of hardware multiplier resources on or off. This option should be used when the hardware multiplier option is enabled on the MicroBlaze processor. Using the hardware multiplier can improve the performance of your application. The compiler automatically defines the C pre-processor definition HAVEHW_MUL when this switch is used. This allows you to write C or assembly code tailored to the hardware, based on whether this feature is specified as available or not. See the _MicroBlaze Processor Reference Guide, (UG081), for more details about the usage of the multiplier option in MicroBlaze. A link to the document is in Appendix E, "Additional Resources."

The MicroBlaze processor has an option to enable instructions that can compute the higher 32-bits of a 32x32-bit multiplication. This option tells the compiler to use these multiply high instructions. The compiler automatically defines the C pre-processor definition HAVE_HW_MUL_HIGH when this switch is used. This allows you to write C or assembly code tailored to the hardware, based on whether this feature is available or not. See the *MicroBlaze Processor Reference Guide, (UG081),*for more details about the usage of the multiply high instructions in MicroBlaze. A link to the document is in Appendix E, "Additional Resources."

Do not use multiply high instructions. This option is the default.

This option tells the compiler that there is no hardware multiplier unit on MicroBlaze, so every 32-bit multiply operation is replaced by a call to the software emulation routine__mulsi3. This option is the default.

You can instantiate a hardware divide unit in MicroBlaze. When the divide unit is present, this option tells the compiler that hardware divide instructions can be used in the program being compiled.

This option can improve the performance of your program if it has a significant amount of division operations. The compiler automatically defines the C pre-processor definition HAVEHW_DIV when this switch is used. This allows you to write C or assembly code tailored to the hardware, based on whether this feature is specified as available or not. See the _MicroBlaze Processor Reference Guide, (UG081), for more details about the usage of the hardware divide option in MicroBlaze. A link to the document is in Appendix E, "Additional Resources."

This option tells the compiler that there is no hardware divide unit on the target MicroBlaze hardware.

This option is the default. The compiler replaces all 32-bit divisions with a call to the corresponding software emulation routines (**divsi3, **udivsi3).

The MicroBlaze processor can be configured to be built with a barrel shifter. In order to use the barrel shift feature of the processor, use the option -mxl-barrel-shift.

The default option assumes that no barrel shifter is present, and the compiler uses add and multiply operations to shift the operands. Enabling barrel shifts can speed up your application significantly, especially while using a floating point library. The compiler automatically defines the C pre-processor definition HAVEHW_BSHIFT when this switch is used. This allows you to write C or assembly code tailored to the hardware, based on whether or not this feature is specified as available. See the _MicroBlaze Processor Reference Guide, (UG081), for more details about the use of the barrel shifter option in MicroBlaze. A link to the document is in Appendix E, "Additional Resources."

This option tells the compiler not to use hardware barrel shift instructions. This option is the default.

This option activates the use of pattern compare instructions in the compiler.

Using pattern compare instructions can speed up boolean operations in your program. Pattern compare operations also permit operating on word-length data as opposed to byte-length data on string manipulation routines such as strcpy, strlen, and strcmp. On a program heavily dependent on string manipulation routines, the speed increase obtained will be significant. The compiler automatically defines the C pre-processor definition HAVEHW_PCMP when this switch is used. This allows you to write C or assembly code tailored to the hardware, based on whether this feature is specified as available or not. Refer to the _MicroBlaze Processor Reference Guide, (UG081), for more details about the use of the pattern compare option in MicroBlaze. A link to the document is in Appendix E, "Additional Resources."

This option tells the compiler not to use pattern compare instructions. This is the default.

This option turns on the usage of single precision floating point instructions (fadd, frsub, fmul, and fdiv) in the compiler.

It also uses fcmp.p instructions, where p is a predicate condition such as le, ge, lt, gt, eq, ne. These instructions are natively decoded and executed by MicroBlaze, when the FPU is enabled in hardware. The compiler automatically defines the C pre-processor definition HAVEHW_FPU when this switch is used. This allows you to write C or assembly code tailored to the hardware, based on whether this feature is specified as available or not. Refer to the _MicroBlaze Processor Reference Guide, (UG081), for more details about the use of the hardware floating point unit option in MicroBlaze. A link to the document is in Appendix E, "Additional Resources."

This option tells the compiler to use software emulation for floating point arithmetic. This option is the default.

This option turns on the usage of single precision floating point conversion instructions (fint and flt) in the compiler. These instructions are natively decoded and executed by MicroBlaze, when the FPU is enabled in hardware and these optional instructions are enabled.

Refer to the MicroBlaze Processor Reference Guide, (UG081), for more details about the use of the hardware floating point unit option in MicroBlaze. A link to the document is in Appendix E, "Additional Resources."

This option turns on the usage of single precision floating point square root instructions (fsqrt) in the compiler. These instructions are natively decoded and executed by MicroBlaze, when the FPU is enabled in hardware and these optional instructions are enabled.

Refer to the MicroBlaze Processor Reference Guide, (UG081), for more details about the use of the hardware floating point unit option in the MicroBlaze processor. A link to the document is in Appendix E, "Additional Resources."

This option generates code optimized for small divides when no hardware divider exists. For signed integer divisions where the numerator and denominator are between 0 and 15 inclusive, this switch provides very fast table-lookup-based divisions. This switch has no effect when the hardware divider is enabled.

If your program contains addresses that have non-zero bits in the most significant half (top 16 bits), then load or store operations to that address require two instructions.

The MicroBlaze processor ABI offers two global small data areas that can each contain up to 64 Kbytes of data. Any memory location within these areas can be accessed using the small data area anchors and a 16-bit immediate value, needing only one instruction for a load or store to the small data area. This optimization can be turned on with the -mxl-gp-opt command line parameter. Variables of size less than a certain threshold value are stored in these areas and can be addressed with fewer instructions. The addresses are calculated during the linking stage.

Caution! If this option is being used, it must be provided to both the compile and the link commands of the build process for your program. Using the switch inconsistently can lead to compile, link, or run-time errors.

This option is useful for compiling programs used in simulation.

According to the C language standard, uninitialized global variables are allocated in the .bss section and are guaranteed to have the value 0 when the program starts execution. Typically, this is achieved by the C startup files running a loop to fill the .bss section with zero when the program starts execution. Optimizing compilers also allocates global variables that are assigned zero in C code to the .bss section.

In a simulation environment, the above two language features can be unwanted overhead. Some simulators automatically zero the entire memory. Even in a normal environment, you can write C code that does not rely on global variables being zero initially. This switch is useful for these scenarios. It causes the C startup files to not initialize the .bss section with zeroes. It also internally forces the compiler to not allocate zero-initialized global variables in the .bss and instead move them to the .data section. This option might improve startup times for your application. Use this option with care and ensure either that you do not use code that relies on global variables being initialized to zero, or that your simulation platform performs the zeroing of memory.

With this option, you can check whether the stack overflows when the program runs.

The compiler inserts code in the prologue of the every function, comparing the stack pointer value with the available memory. If the stack pointer exceeds the available free memory, the program jumps to a the subroutine _stack_overflow_exit. This subroutine sets the value of the variable _stack_overflow_error to 1.

You can override the standard stack overflow handler by providing the function _stack_overflow_exit in the source code, which acts as the stack overflow handler.

This is the default mode used for compiling programs with mb-gcc. This option need not be provided on the command line for mb-gcc. This uses the startup file crt0.o.

The Xilinx Microprocessor Debugger (XMD) allows debugging of applications in a software-intrusive manner, known as XMDSTUB mode. Compile programs being debugged in such a manner with this switch. In such programs, the address locations 0x0 to 0x800 are reserved for use by XMDSTUB. Using -xl-mode-xmdstub has two effects:

• The start address of your program is set to 0x800. You can change this address by overriding the _TEXT_START_ADDR in the linker script or through linker options. For more details about linker options, refer to Linker Options, page 105. If the start address is defined to be less than 0x800, XMD issues an address overlap error.
• crt1.o is used as the initialization file. The crt1.o file returns the control back to the XMDStub when your program execution is complete.

Note: Use -xl-mode-xmdstub for designs when XMDStub is part of the bitstream. Do not use this mode when the system is complied for No Debug or when "Hardware Debugging" is turned ON. For more details on debugging with XMD, refer to Chapter 11, GNU Debugger.

This option is used for applications that are loaded using a bootloader. Typically, the bootloader resides in non-volatile memory mapped to the processor reset vector. If a normal executable is loaded by this bootloader, the application reset vector overwrites the reset vector of the bootloader. In such a scenario, on a processor reset, the bootloader does not execute first (it is typically required to do so) to reload this application and do other initialization as necessary.

To prevent this, you must compile the bootloaded application with this compiler flag. On a processor reset, control then reaches the bootloader instead of the application.

Using this switch on an application that is deployed in a scenario different from the one described above will not work. This mode uses crt2.o as a startup file.

This option is used for applications that do not require any of the MicroBlaze vectors. This is typically used in standalone applications that do not use any of the processor's reset, interrupt, or exception features. Using this switch leads to smaller code size due to the elimination of the instructions for the vectors. This mode uses crt3.o as a startup file.

Caution! Do not use more than one mode of execution on the command line. You will receive link errors due to multiple definition of symbols if you do so.

The GNU compiler for MicroBlaze supports the -fPIC and -fpic switches. These switches enable Position Independent Code (PIC) generation in the compiler. This feature is used by the Linux operating system only for MicroBlaze to implement shared libraries and relocatable executables. The scheme uses a Global Offset Table (GOT) to relocate all data accesses in the generated code and a Procedure Linkage Table (PLT) for making function calls into shared libraries. This is the standard convention in GNU-based platforms for generating relocatable code and for dynamically linking against shared libraries.

The GNU compiler for MicroBlaze uses the Application Binary Interface (ABI) defined in the MicroBlaze Processor Reference Guide (UG081). Refer to the ABI documentation for register and stack usage conventions as well as a description of the standard memory model used by the compiler. A link to the document is provided in Appendix E, "Additional Resources.".

The mb-as assembler for the Xilinx MicroBlaze soft processor supports the same set of options supported by the standard GNU compiler tools. It also supports the same set of assembler directives supported by the standard GNU assembler.

The mb-as assembler supports all the opcodes in the MicroBlaze machine instruction set, with the exception of the imm instruction. The mb-as assembler generates imm instructions when large immediate values are used. The assembly language programmer is never required to write code with imm instructions. For more information on the MicroBlaze instruction set, refer to the MicroBlaze Processor Reference Guide (UG081). A link to the document is in Additional Resources, page 281.

The mb-as assembler requires all MicroBlaze instructions with an immediate operand to be specified as a constant or a label. If the instruction requires a PC-relative operand, then the mb-as assembler computes it and includes an imm instruction if necessary.

For example, the Branch Immediate if Equal (beqi) instruction requires a PC-relative operand.

The assembly programmer should use this instruction as follows:

beqi r3, mytargetlabel

where mytargetlabel is the label of the target instruction. The mb-as assembler computes the immediate value of the instruction as mytargetlabel - PC.

If this immediate value is greater than 16 bits, the mb-as assembler automatically inserts an imm instruction. If the value of mytargetlabel is not known at the time of compilation, the mb-as assembler always inserts an imm instruction. Use the relax option of the linker remove any unnecessary imm instructions.

Similarly, if an instruction needs a large constant as an operand, the assembly language programmer should use the operand as is, without using an imm instruction. For example, the following code adds the constant 200,000 to the contents of register r3, and stores the results in register r4:

addi r4, r3, 200000

The mb-as assembler recognizes that this operand needs an imm instruction, and inserts one automatically.

In addition to the standard MicroBlaze instruction set, the mb-as assembler also supports some pseudo-op codes to ease the task of assembly programming. Table 9-6 lists the supported pseudo-opcodes.

Table 9-6: Pseudo-Opcodes Supported by the GNU Assembler

The mb-ld linker for the MicroBlaze soft processor provides additional options to those supported by the GNU compiler tools. The options are summarized in this section.

By default, the text section of the output code starts with the base address 0x28 (0x800 in XMDStub mode). This can be overridden by using the -defsym _TEXT_START_ADDR option. If this is supplied to mb-gcc compiler, the text section of the output code starts from the given value.

You do not have to use -defsym _TEXT_START_ADDR if you want to use the default start address set by the compiler.

This is a linker option and should be used when you invoke the linker separately. If the linker is being invoked as a part of the mb-gcc flow, you must use the following option:

**-Wl,-defsym -Wl,_TEXT_START_ADDR=***value*

This is a linker option that removes all unwanted imm instructions generated by the assembler. The assembler generates an imm instruction for every instruction where the value of the immediate cannot be calculated during the assembler phase.

Most of these instructions do not need an imm instruction. These are removed by the linker when the -relax command line option is provided.

This option is required only when linker is invoked on its own. When linker is invoked through the mb-gcc compiler, this option is automatically provided to the linker.

This option sets the text and data section as readable and writable. It also does not page-align the data segment. This option is required only for MicroBlaze programs. The top-level GCC compiler automatically includes this option, while invoking the linker, but if you intend to invoke the linker without using GCC, use this option.

For more details on this option, refer to the GNU manuals online. A link to the manuals is in Appendix E, "Additional Resources."

The MicroBlaze linker uses linker scripts to assign sections to memory. These are listed in the following section.

Table 9-7 lists the input sections that are assigned by MicroBlaze linker scripts.

Table 9-7: Section Names and Descriptions

The following points must be kept in mind when writing or customizing your own linker script:

• Ensure that the different vector sections are assigned to the appropriate memories as defined by the MicroBlaze hardware.
• Allocate space in the .bss section for stack and heap. Set the _stack variable to the location after _STACK_SIZE locations of this area, and the _heap_start variable to the next location after the _STACK_SIZE location. Because the stack and heap need not be initialized for hardware as well as simulation, define the _bss_end variable after the .bss and COMMON definitions.

Note: The .bss section boundary does not include either stack or heap.

• Ensure that the variables _SDATA_START** , _SDATA_END**, SDATA2_START, _SDATA2_END**, _SBSS2_START** , _SBSS2_END__, _bss_start, _bss_end, _sbss_start, and _sbss_end are defined to the beginning and end of the sections sdata, sdata2, sbss2, bss, and sbss respectively.
• ANSI C requires that all uninitialized memory be initialized to startup (not required for stack and heap). The standard CRT that is provided assumes a single .bss section that is initialized to zero. If there are multiple .bss sections, this CRT will not work. You should write your own CRT that initializes all the .bss sections.

The compiler includes pre-compiled startup and end files in the final link command when forming an executable. Startup files set up the language and the platform environment before your application code executes. Start up files typically do the following:

• Set up any reset, interrupt, and exception vectors as required.
• Set up stack pointer, small-data anchors, and other registers. Refer to Table 9-8, page 120 for details.
• Clear the BSS memory regions to zero.
• Invoke language initialization functions, such as C++ constructors.
• Initialize the hardware sub-system. For example, if the program is to be profiled, initialize the profiling timers.
• Set up arguments for the main procedure and invoke it.

Similarly, end files are used to include code that must execute after your program ends. The following actions are typically performed by end files:

• Invoke language cleanup functions, such as C++ destructors.
• De-initialize the hardware sub-system. For example, if the program is being profiled, clean up the profiling sub-system.

Table 9-8 lists the register names, values, and descriptions in the C-Runtime files.

Table 9-8: Register Initialization in C-Runtime Files

The following subsections describe the initialization files used for various application modes. This information is for advanced users who want to change or understand the startup code of their application.

For MicroBlaze, there are two distinct stages of C runtime initialization. The first stage is primarily responsible for setting up vectors, after which it invokes the second stage initialization. It also provides exit stubs based on the different application modes.

This initialization file is used for programs which are to be executed in standalone mode, without the use of any bootloader or debugging stub such as xmdstub. This CRT populates the reset, interrupt, exception, and hardware exception vectors and invokes the second stage startup routine _crtinit. On returning from _crtinit, it ends the program by infinitely looping in the _exit label.

This initialization file is used when the application is debugged in a software-intrusive manner. It populates all the vectors except the breakpoint and reset vectors and transfers control to the second-stage _crtinit startup routine. Upon return from _crtinit, program control returns back to the XMDStub, which signals to the debugger that the program has finished.

This initialization file is used when the executable is loaded using a bootloader. It populates all the vectors except the reset vector and transfers control to the second-stage _crtinit startup routine. On returning from _crtinit, it ends the program by infinitely looping at the _exit label. Because the reset vector is not populated, on a processor reset, control is transferred to the bootloader, which can reload and restart the program.

This initialization file is employed when the executable does not use any vectors and wishes to reduce code size. It populates only the reset vector and transfers control to the second stage _crtinit startup routine. On returning from _crtinit, it ends the program by infinitely looping at the _exit label. Because the other vectors are not populated, the GNU linking mechanism does not pull in any of the interrupt and exception handling related routines, thus saving code space.

According to the C standard specification, all global and static variables must be initialized to 0. This is a common functionality required by all the CRTs above. Another routine, _crtinit, is invoked. The _crtinit routine initializes memory in the .bss section of the program. The _crtinit routine is also the wrapper that invokes the main procedure. Before invoking the main procedure, it may invoke other initialization functions. The _crtinit routine is supplied by the startup files described below.

This default, second stage, C startup file performs the following steps:

• 1. Clears the .bss section to zero.
• 2. Invokes _program_init.
• 3. Invokes "constructor" functions (_init).
• 4. Sets up the arguments for main and invokes main.
• 5. Invokes "destructor" functions (_fini).
• 6. Invokes _program_clean and returns.

This second stage startup file is used during profiling, and performs the following steps:

• 1. Clears the .bss section to zero.
• 2. Invokes _program_init.
• 3. Invokes _profile_init to initialize the profiling library.
• 4. Invokes "constructor" functions (_init).
• 5. Sets up the arguments for main and invokes main.
• 6. Invokes "destructor" functions (_fini).
• 7. Invokes _profile_clean to cleanup the profiling library.
• 8. Invokes _program_clean**,** and then returns.

This second-stage startup file is used when the -mno-clearbss switch is used in the compiler, and performs the following steps:

• 1. Invokes _program_init.
• 2. Invokes "constructor" functions (_init).
• 3. Sets up the arguments for main and invokes main.
• 4. Invokes "destructor" functions (_fini).
• 5. Invokes _program_clean, and then returns.

This second stage startup file is used during profiling in conjunction with the -mno-clearbss switch, and performs the following steps in order:

• 1. Invokes _program_init.
• 2. Invokes _profile_init to initialize the profiling library.
• 3. Invokes "constructor" functions (_init).
• 4. Sets up the arguments for and invokes main.
• 5. Invokes "destructor" functions (_fini).
• 6. Invokes _profile_clean to cleanup the profiling library.
• 7. Invokes _program_clean**,** and then returns.

The compiler also uses certain standard start and end files for C++ language support. These are crti.o, crtbegin.o, crtend.o, and crtn.o. These files are standard compiler files that provide the content for the .init, .fini, **.**ctors, and .dtors sections.

The initialization files are distributed in both pre-compiled and source form with EDK. The pre-compiled object files are found in the compiler library directory. Sources for the initialization files for the MicroBlaze GNU compiler can be found in the <XILINX_EDK>/ sw/lib/microblaze/src directory, where <XILINX_EDK> is the EDK installation area.

To fulfill a custom startup file requirement, you can take the files from the source area and include them as a part of your application sources. Alternatively, you can assemble the files into .o files and place them in a common area. To refer to the newly created object files instead of the standard files, use the -B directory -name command-line option while invoking mb-gcc.

To prevent the default startup files from being used, use the -nostartfiles on the final compile line.

Note: The miscellaneous compiler standard CRT files, such as crti.o, and crtbegin.o, are not provided with source code. They are available in the installation to be used as is. You might need to bring them in on your final link command.

If your application has stringent requirements on code size for C programs, you might want to eliminate all sources of overhead. This section describes how to reduce the overhead of invoking the C++ constructor or destructor code in a C program that does not require that code. You might be able to save approximately 220 bytes of code space by making the following modifications:

• 1. Follow the instructions for creating a custom copy of the startup files from the installation area, as described in the preceding sections. Specifically, copy over the particular versions of crtn.s and xcrtinit.s that suit your application. For example, if your application is being bootstrapped and profiled, copy crt2.s and pg-crtinit.s from the installation area.
• 2. Modify pg-crtinit.s to remove the following lines:

brlid r15, __init
/* Invoke language initialization functions */
nop

and

brlid r15, __fini
/* Invoke language cleanup functions */
nop

This avoids referencing the extra code usually pulled in for constructor and destructor handling, reducing code size.

• 3. Compile these files into .o files and place them in a directory of your choice, or include them as a part of your application sources.
• 4. Add the -nostartfiles switch to the compiler. Add the -B directory switch if you have chosen to assemble the files in a particular folder.
• 5. Compile your application.

If your application is executing in a different mode, then you must pick the appropriate CRT files based on the description in Startup Files, page 120.