sdx_pack Utility

The SDSoC™ tools include the sdx_pack command line utility for creating C-Callable IP libraries for linking RTL IP into SDSoC applications using the sds++ system compiler.

Usage

sdx_pack -header <header.h/pp> -ip <component.xml> [-param <name>="value"] [other options]

Configuration Options

Table 1. Configuration Options
Option Valid Values Description
-header <header.h/.hpp> Header file with function declarations, Only one top header file allowed Required. Header file with function prototype.
-ip <component.xml> N/A Required. IP packed by the Vivado® IP integrator.
-control <protocol>[=<port>[:offset]] N/A Required. IP control protocol options:
  • AP_CTRL
  • AXI
  • none
-func <function_name> -map N/A Specify a list of C-Callable functions associated with the IP instance. For each function, use the [-func ... -map ... -func-end] option.

To map each software function argument to an IP port, use -map.

-map <sw_name>=<hw_name>:direction[:<offset>[<aximm_name>:<direction>]] N/A Required for using -func <function_name>. A software function argument to IP port mapping:<SW_Name>=<HW_Name>:direction[:offset[<aximm_name>:direction]

For example,

-primary-clk <clk_interface>=min_clk_period N/A Specify the primary clock interface and its minimum clock period in nanoseconds.
-derived-clk <clk_interface>=multiplier:divisor N/A Specify the phase-aligned derived clock interface, and its multiplier and divisor in integer.
-primary-clk <clk_interface>=min_clk_period N/A Specify the primary clock interface and its minimum clock period in nanoseconds.
-derived-clk <clk_interface>=multiplier:divisor N/A Specify the phase-aligned derived clock interface, and its multiplier and divisor in integer.
-target-cpu <cpu_type> N/A Specifies target CPU:
  • cortex-a9
  • cortex-a53
  • cortex-r5
  • microblaze
-target-family <board_family> N/A Specifies target board family; for example, zynq or zynquplus.
-target-os <name> N/A Specifies target Operating System:
  • linux (default)
  • standalone (bare-metal)
-verbose N/A Prints verbose output to STDOUT.
-version N/A Prints the sdx_pack version information to STDOUT.
--help N/A Displays information about this command: sdx_pack --help
-query-target <type>
  • family
  • cpu
  • os
Query supported board_family, cpu_type, and os_type of the IP.
-query-interface <interface type>
  • all
  • aximm
  • axilite
  • axis
  • clock
  • control
  • param
  • misc
Query interfaces and parameters of the IP, support multiple queries.
-primary-clk <clk_interface>=min_clk_period N/A Specify the primary clock interface and its minimum clock period in nanoseconds.

Only one top primary clock is allowed, min_clk_period should be between 0.5 and 1000.0 (i.e., 1 MHz to 2 GHz)

-derived-clk <clk_interface>=multiplier:divisor N/A Specify the phase-aligned derived clock interface, and its multiplier and divisor in integer.

sdx_pack Example

sdx_pack -header count.hpp -ip ../ip/component.xml -func count \
-control AXI=S_AXI:0  -map start_value=S_AXI:in:0x8 -map return=S_AXI:out:4 -func-end \
-target-cpu cortex-a9 -target-os standalone -target-family zynq

Where the flags that are used above are defined in the table.

The sdx_pack utility automatically generates:
  • <function_name>.o: Compiled object code for the specified function. This file is generated under the .Xil/sdx folder.
  • <function_name>.fcnmap.xml: Mapping IP ports to function arguments. This file is generated under the .Xil/rtl folder.
  • <function_name>.params.xml: IP parameters. This file is generated under the .Xil/rtl folder.
  • <function_name>.cpp: C++ file with entry point. This file is generated under the .Xil/rtl folder.

-query Option usage

sdx_pack -query-target <type> -ip component.xml [-target-family <board_family>] [-target-cpu <cpu_type>]

This query only supports meaningful queries instead of all possible combinations. Only one -query-target <type> option supported at each query. Specifically, below is what -query-target <type> returns. This is consistent with the SDx™ GUI for the application project.

-query-target family

It ignores all other options and returns all supported board families of the IP. This family set must be a subset of {artix7, kintex7, kintexu, kintexuplus, spartan7, virtex7, virtexu, virtexuplus, virtexuplusHBM, zynq, zynquplus}.

Note: For a family with an "a" (automotive), "q" (space) prefix, or "l" (low power) suffix, then specify the family without the prefix or suffix. For example, target azynq, select zynq.
-query-target cpu
It ignores all other options except -target-family <board_family>.
  • If -target-family <board_family> is specified, it returns all CPU types supported under this specific family. This must be a subset of {cortex-a9, cortex-a53, cortex-r5, microblaze}.
  • If -target-family <board_family> is not selected, then it returns all CPU types supported under all supported families. This must be a subset of {cortex-a9, cortex-a53, cortex-r5, microblaze} {cortex-a9, cortex-a53, cortex-r5, microblaze}.
-query-target os
  • If -target-cpu <cpu_type> is specified, it returns all OS types supported under this specific CPU. This must be a subset of {linux, standalone}.

    If -target-family <board_family> is also specified, cpu_type must be a valid CPU in this specific board_family.

  • Else, if -target-family <board_family> is specified, it returns all OS types supported under this specific family. This must be a subset of {linux, standalone}.
  • Else, it returns all OS types supported under all supported families. This must be a subset of {linux, standalone}

-map Option Usage

In this example, the hardware name for the AXI4-Lite interface is s_axi_AXILiteS.

Scalars are always mapped onto AXI4-Lite interfaces:

  • To map an input scalar (e.g., int a), use -map a=s_axi_AXILiteS:in:offset.
  • To map an output scalar (e.g., int *a, or int &a), use -map a=s_axi_AXILiteS:out:offset.
  • To map a return scalar (the return type can only be scalar), use -map return=s_axi_AXILiteS:out:offset.

Arrays (e.g., int a[N]) can be mapped onto any type of interface. The exact interface and direction is specified by the IP.

  • To map an array onto AXI4, use -map a=s_axi_AXILiteS:in:offset,<a_hwName>:direction. Do not map onto AXI4 (m_axi) when control none is used.

  • To map an array onto AXI4-Stream, use -map a=<a_hwName>:direction.

  • To map an array (a small, constant-size array) onto AXI4-Lite, use -map a=s_axi_AXILiteS:in:offset.
    Note: The array must be a one-dimensional array with a constant size. For example, int a[N], where N must be a constant (which can be either #define N 16 or constant int N = 16).