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 "prng_useriosrc_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 "prng_useriosrc_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:
typedef struct {
xc_r_addr_t dout;
u32 n_bits;
u32 bin_pt;
} xc_from_reg_t;
typedef struct {
xc_w_addr_t din;
u32 n_bits;
u32 bin_pt;
} xc_to_reg_t;
typedef struct {
xc_r_addr_t dout;
xc_r_addr_t percentfull;
xc_r_addr_t empty;
u32 n_bits;
u32 bin_pt;
u32 depth;
} xc_from_fifo_t;
typedef struct {
xc_w_addr_t din;
xc_r_addr_t percentfull;
xc_r_addr_t full;
u32 n_bits;
u32 bin_pt;
u32 depth;
} xc_to_fifo_t;
typedef struct {
xc_addr_t addr;
u32 n_bits;
u32 bin_pt;
u32 depth;
} xc_shram_t;
| Shared Memory Name | Memory type | Access Data Type | Native Precision* |
|---|---|---|---|
| capturedOutput | From Register | xc_from_reg_t | UFix_16_0 |
| capturePeriod | To Register | xc_to_reg_t | UFix_32_0 |
* 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
u32 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 u32 value by the processor. Vise verse, when writing to a
shared memory, a C u32 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.
| xc_status_t | XC_CfgInitialize(xc_iface_t **iface, void *config_table) |
| xc_status_t | XC_GetShMem(xc_iface_t *iface, const char *name, void **shmem) |
| xc_status_t | XC_Read(xc_iface_t *iface, xc_r_addr_t r_addr, u32 *data) |
| xc_status_t | XC_Write(xc_iface_t *iface, xc_w_addr_t w_addr, const u32 data) |
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_CfgInitialize is used to initialize the software driver, and should be
called before any other software driver function is called.
XC_CfgInitialize accepts a pointer pointing to an entry of the
configuration table PRNG_USERIOSRC_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_CfgInitialize 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_CfgInitialize, 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_CfgInitialize. One way of allocating the memory space is shown
in below:
xc_iface_t *iface;
XC_CfgInitialize(&iface, &PRNG_USERIOSRC_PLBW_ConfigTable[XPAR_<PCORE_INSTANCE_NAME>_DEVICE_ID]);
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_GetShMem 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_GetShMem 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_GetShMem to avoid unnecessary
searching.
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.
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.
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_GetAddr 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.