EDK Processor - user_io_board_controller_plbw API

This software API is provided to allow easy access of the shared memories added to the System Generator EDK Processor block via an automatically generated memory-mapped interface. Only single-word read and write operations are supported at this time.

In order to utilize these functions, the following two header files need to be included in the user C code.

#include "xparameters.h"
#include "user_io_board_controller_plbw.h"

The hardware settings of the shared memories inside the System Generator Pcore can be found in the header file "xparameters.h". For example, absolute memory-mapped addresses, data bit widths (n_bits) and binary point positions (bin_pt), depths of the "To FIFO" shared memories on the processor memory map can be found in this header file. The header file "user_io_board_controller_plbw.h" defines the basic data types and software driver functions for accessing the shared memories.

Refer to the Basic Data Types section for information on the System Generator basic data types. Refer to the Software Driver Functions section for information on the software driver functions. The section Driver Performance Optimization contains information on how to improve the shared memory access time using pointer arithmatics. Code snippets showing how to use the different software driver functions can be found in the Examples section of this document.

The basic data types of the software driver is defined at "xcope.h". All the System Generator Pcore specific data types and function names are prefixed with "xc_".

Three types of shared memory addresses are defined according to the read-write accessibility of the shared memory ports: xc_r_addr_t for read-only addresses, xc_w_addr_t for write-only addresses, and xc_addr_t for read-write addresses. For example, the address of the din port of a "To Register" shared memory is a write-only xc_w_addr_t data type. The address of the dout port of a "From Register" shared memory is a read-only xc_r_addr_t data type. The address of the addr port of a "Shared Memory" shared memory is a xc_addr_t, meaning that you can both read from and write to this shared memory. While these three address data types are essentially the same xc_raw_addr_t data type, and are interchangeable. They help users to easily find out the read and write accessibility of a specific port on a shared memory by just looking at its data structure.

Each type of shared memories has its own hardware implementation and interface. Accordingly, the following software driver has corresponding data structures for storing the shared memory information:

• "From Register":
  
  typedef struct {
    xc_r_addr_t dout;
    uint32_t n_bits;
    uint32_t bin_pt;
} xc_from_reg_t;

  
• "To Register":
  
  typedef struct {
    xc_w_addr_t din;
    uint32_t n_bits;
    uint32_t bin_pt;
} xc_to_reg_t;

  
• "From FIFO":
  
  typedef struct {
    xc_r_addr_t dout;
    xc_r_addr_t percentfull;
    xc_r_addr_t empty;
    uint32_t n_bits;
    uint32_t bin_pt;
} xc_from_fifo_t;

  
• "To FIFO":
  
  typedef struct {
    xc_w_addr_t din;
    xc_r_addr_t percentfull;
    xc_r_addr_t full;
    uint32_t n_bits;
    uint32_t bin_pt;
} xc_to_fifo_t;

  
• "Shared Memory":
  
  typedef struct {
    xc_addr_t addr;
    uint32_t n_bits;
    uint32_t bin_pt;
} xc_shram_t;

  

* Native precision here refers to the bit widths and binary point positions of the shared memories in the original System Generator model. Data reading from or writing to the shared memories are always treated as a C uint32_t data type by the processor. When reading from a shared memory, a data is first converted to UFix_32_0 data type following the System Generator fix-point data conversion rules, and then interpreted as a C uint32_t value by the processor. Vise verse, when writing to a shared memory, a C uint32_t data is first interpreted as UFix_32_0 data type, and then converted to the native precision of the target shared memory following the System Generator fix-point data conversion rules.

Create

Parameters:
iface - interface parameters.
config_table - pointer pointing an entry of the Pcore configurable table.

Returns:
Returns XC_SUCCESS if created succeeded. Returns XC_FAILURE upon error.

Notes:
xc_create is used to initialize the software driver, and should be called before any other software driver function is called.

xc_create accepts a pointer pointing to an entry of the configuration table USER_IO_BOARD_CONTROLLER_PLBW_ConfigTable. A configurable table is a specific C struct array, which contains the hardware and software settings of the System Generator Pcore instances. The configurable table is automatically created by EDK during library generation. Each System Generator Pcore instance has an entry on the configuration table that stores its specific settings. The position of a Pcore on the configurable table is its device ID, which is defined in "xparameters.h" as XPAR_<PCORE_INSTANCE_NAME>_DEVICE_ID.

xc_create uses the information stored in the configurable table to initialize iface. iface stores the settings of the automatically generated bus interface connecting the System Generator shared memories to the processor. The settings includes the software driver version number, low-level implementations of the read/write operations, etc. iface also stores the shared memory settings, such as absolute memory-mapped addresses, data bit width (n_bit), binary position (bin_pt), etc. Once initialized by xc_create, users can provide iface to other software driver functions to perform various operations.

Note that the memory space for iface needs to be allocated before calling xc_create. One way of allocating the memory space is shown in below:

xc_iface_t *iface;
xc_create(&iface, &USER_IO_BOARD_CONTROLLER_PLBW_ConfigTable[XPAR_<PCORE_INSTANCE_NAME>_DEVICE_ID]);


Get Shared Memory

Parameters:
iface - interface parameters.
name - name of the shared memory.
shmem - the pointer pointing to the corresponding shared memory data structure.

Returns:
Returns XC_SUCCESS if created succeeded. Returns XC_FAILURE upon error.

Notes:
xc_get_shmem accepts the iface of a System Generator Pcore, and the name of a shared memory name. It returns a pointer shmem pointing to the memory locations for storing the corresponding shared memory settings. shmeme can then be passed to xc_read and xc_write for read/write operations on the specific shared memory.

This function is provided for better code portability. The shared memory names and the corresponding data structures are listed in the Shared Memory Settings table. Note that while "xparameters.h" converts all shared memory names into caps, xc_get_shmem preserves the cases of shared memory names and is case-sensitive during search.

For performance consideraion, it is recommended to cache the shmem returned by xc_get_shmem to avoid unnecessary searching.

Read

Parameters:
iface - interface parameters.
r_addr - the address to read from.
data - the place to store the read-back data.

Returns:
Returns XC_SUCCESS if created succeeded. Returns XC_FAILURE upon error.

Write

Parameters:
iface - interface parameters.
w_addr - the address to write to.
data - the data to write.

Returns:
Returns XC_SUCCESS if created succeeded. Returns XC_FAILURE upon error.

Helper Functions

Parameters:
addr - base address (e.g., the base address of a "Shared Memory" shared memory.
offset - offset to the base address.

Returns:
Returns the absolute address with the specified offset relative to addr.

Notes:
xc_get_addr is a helper function that is useful in accessing a random location of the "Shared Memory" shared memories. See Accessing "Shared Memory" shared memories for example usage of this helper function.

Accessing "From Register" and "To Register" shared memories

Accessing "From FIFO" and "To FIFO" shared memories

Accessing "Shared Memory" shared memories