EDK Processor - wlan_agc_axiw 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 "wlan_agc_axiw.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 "wlan_agc_axiw.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.

Basic Data Types

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:

Shared Memory Settings

Shared Memory NameMemory typeAccess Data TypeNative Precision*
TIMING_RESETTo Registerxc_to_reg_tUFix_32_0
RSSI_PWR_CALIBTo Registerxc_to_reg_tUFix_32_0
IIR_COEF_B0To Registerxc_to_reg_tUFix_18_17
IIR_COEF_A1To Registerxc_to_reg_tFix_18_17
RESETTo Registerxc_to_reg_tUFix_32_0
TIMING_AGCTo Registerxc_to_reg_tUFix_32_0
TARGETTo Registerxc_to_reg_tUFix_32_0
CONFIGTo Registerxc_to_reg_tUFix_32_0
TIMING_DCOTo Registerxc_to_reg_tUFix_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.

Software Driver Functions

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)
xc_status_t XC_Read_Float(xc_iface_t *iface, xc_r_addr_t r_addr, float *data)
xc_status_t XC_Write_Float(xc_iface_t *iface, xc_w_addr_t w_addr, const float data)

Create

xc_status_t XC_CfgInitialize(
    xc_ifact_t *iface,
    void *config_table);

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 WLAN_AGC_AXIW_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, &WLAN_AGC_AXIW_ConfigTable[XPAR_<PCORE_INSTANCE_NAME>_DEVICE_ID]);

Get Shared Memory

xc_status_t XC_GetShmem(
    xc_iface_t *iface,
    const char *name,
    void **shmem);

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.

Read

xc_status_t XC_Read(
    xc_iface_t *iface,
    xc_r_addr_t r_addr,
    const u32 *data);

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

xc_status_t XC_Write(
    xc_iface_t *iface,
    xc_w_addr_t w_addr,
    const u32 data);

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.

Read Floating-Point Data

xc_status_t XC_Read_Float(
    xc_iface_t *iface,
    xc_r_addr_t r_addr,
    const float *data);

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

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

Write Floating-Point Data

xc_status_t XC_Write_Float(
    xc_iface_t *iface,
    xc_w_addr_t w_addr,
    const float data);

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

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

Helper Functions

xc_raw_addr_t XC_GetAddr(
    xc_raw_addr_t addr,
    const u32 offset);

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.

Driver Performance Optimization

The System Generator software driver improves user code portability. On the other hand, it introduces overhead for shared memory access. In cases that the software driver performance is a concern, users may want to perform read/write operations of the shared memories directly through pointer arithmetics. The addresses of the shared memories can be found at "xparameters.h".

In the following code snippet, users can read data from a "From Register" shared memory named "FROMREG1" and write it to a "To Register" shared memory named "TOREG1":
volatile unsigned value;
unsigned *fromreg_plb_data;
unsigned *toreg_plb_data;

// get the absolute shared memory addresses from "xparameters.h"
fromreg_plb_data = XPAR_SG_PLBIFACE_0_MEMMAP_FROMREG1;
toreg_plb_data = XPAR_SG_PLBIFACE_0_MEMMAP_TOREG1;

// read data from shared memory "FROMREG1"
value = *fromreg_plb_data;
// write data to shared memory "TOREG1"
*toreg_plb_data = value;
Even though the software driver does not support array operations, the following code snippet shows how to use pointer arithmetics to write a array of data to the "Shared Memory" shared memories. Array read can be realized similarly.
int i;
int *plb_addr;
u32 value;
xc_iface_t *iface;
xc_shram_t *shram;

// initialize the software driver, assuming the Pcore device ID is 0
XC_CfgInitialize(&iface, &WLAN_AGC_AXIW_ConfigTable[0]);
// obtain the memory location for storing the settings of shared memory "shram1"
XC_GetShmem(iface, "shram1", (void **) &shram);
// obtain the base address of shared memory "shram1"
plb_addr = (int *) shram->addr;
// write the data stored at array to the shared memory "shram1"
for (i = 0; i < ARRAY_SIZE; i++) {
    *(plb_addr++) = array[i];
}

Examples

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

Single-word writes

The following code snippet write value to the "To Register" shared memory named "toreg". See also: Write
u32 value;
xc_iface_t *iface;
xc_to_reg_t *toreg;

// initialize the software driver, assuming the Pcore device ID is 0
XC_CfgInitialize(&iface, &WLAN_AGC_AXIW_ConfigTable[0]);

// obtain the memory location for storing the settings of shared memory "t"
XC_GetShmem(iface, "toreg", &toreg);
// write value to the "din" port of shared memory "toreg"
XC_Write(iface, toreg->din, (const unsigned) value);

Single-word reads

The following code snippet reads data stored in the "From Register" shared memory named "fromreg" into value. See also: Read
u32 value;
xc_iface_t *iface;
xc_from_reg_t *fromreg;

// initialize the software driver, assuming the Pcore device ID is 0
XC_CfgInitialize(&iface, &WLAN_AGC_AXIW_ConfigTable[0]);

// obtain the memory location for storing the settings of shared memory "fromreg"
XC_GetShmem(iface, "fromreg", (void **) &fromreg);
// read data from the "dout" port of shared memory "fromreg" and store at value
XC_Read(iface, fromreg->dout, &value);

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

Single-word writes

The following code snippet write value to the "To FIFO" shared memory named "tofifo". See also: Write
u32 full;
u32 value;
xc_iface_t *iface;
xc_to_fifo_t *tofifo;

// initialize the software driver, assuming the Pcore device ID is 0
XC_CfgInitialize(&iface, &WLAN_AGC_AXIW_ConfigTable[0]);

// obtain the memory location for storing the settings of shared memory "t"
XC_GetShmem(iface, "tofifo", (void **) &tofifo);
// check the "full" port of shared memory "tofifo"
do {
    XC_Read(iface, tofifo->full, &full);
} while (full == 1);
// write value to the "din" port of shared memory "tofifo"
value = 100;
XC_Write(iface, tofifo->din, value);

Single-word reads

The following code snippet reads data stored in the "From Register" shared memory named "fromreg" into value. See also: Read
u32 empty;
u32 value;
xc_iface_t *iface;
xc_from_fifo_t *fromfifo;

// initialize the software driver, assuming the Pcore device ID is 0
XC_CfgInitialize(&iface, &WLAN_AGC_AXIW_ConfigTable[0]);

// obtain the memory location for storing the settings of shared memory "fromfifo"
XC_GetShmem(iface, "fromreg", (void **) &fromfifo);
// check the "empty" port of shared memory "fromfifo"
do {
    XC_Read(iface, fromfifo->empty, &empty);
} while (empty == 1);
// read data from the "dout" port of shared memory "fromfifo" and store at value
XC_Read(iface, fromfifo->dout, &value);

Accessing "Shared Memory" shared memories

Single-word writes

The following code snippet write value to the "Shared Memory" shared memory named "shram1". See also: Write
u32 value;
xc_iface_t *iface;
xc_shram_t *shram;

// initialize the software driver, assuming the Pcore device ID is 0
XC_CfgInitialize(&iface, &WLAN_AGC_AXIW_ConfigTable[0]);

// obtain the memory location for storing the settings of shared memory "shram1"
XC_GetShmem(iface, "shram1", (void **) &shram);
// write value to the shared memory "shram1"
XC_Write(iface, XC_GetAddr(shram->addr, 2), (const unsigned) value);

Single-word reads

The following code snippet reads data stored in the "Shared Memory" shared memory named "shram2" into value. See also: Read
u32 value;
xc_iface_t *iface;
xc_shram_t *shram;

// initialize the software driver, assuming the Pcore device ID is 0
XC_CfgInitialize(&iface, &WLAN_AGC_AXIW_ConfigTable[0]);

// obtain the memory location for storing the settings of shared memory "fromfifo"
XC_GetShmem(iface, "shram2", (void **) &shram);
// read data from the shared memory "shram2" and store at value
XC_Read(iface, XC_GetAddr(shram->addr, 2), &value);
Generated by Xilinx System Generator