Model Configuration Functions - 7.2 English - PG149

FIR Compiler LogiCORE IP Product Guide ( PG149)

Document ID
PG149
Release Date
2025-06-11
Version
7.2 English

Get Version

const char* xip_fir_v7_2_get_version(void);

The function returns a string describing the version of the model.

Get Default Configuration

xip_status
xip_fir_v7_2_get_default_config(
  xip_fir_v7_2_config* config
)

This function populates the xip_fir_v7_2_config configuration structure pointed to by config with the default configuration of the FIR Compiler v7.2 core.

Create Model Object

xip_fir_v7_2
xip_fir_v7_2_create(
    const xip_fir_v7_2_config* config,
    xip_msg_handler msg_handler,
    void* msg_handle
)

This function creates a new model instance, based on the configuration data pointed to by config.

The msg_handler argument is a pointer to a function taking three arguments as previously defined in Type Definitions. This function pointer is retained by the model object and is called whenever the model wishes to issue a note, warning or error message. Its arguments are:

  1. A generic pointer (void*). This is always the value that was passed in as the msg_handle argument to the create function.
  2. An integer (int) indicating whether the message is an error (1) or a note or warning (0).
  3. The message string itself.

If the handler argument is a null pointer, then the C model outputs no messages at all. Using this mechanism, you can choose whether to output messages to the console, log them to a file or ignore them completely.

The create function returns a pointer to the newly created object. If the object cannot be created, then a diagnostic error message is emitted using the supplied handler function (if any) and a null pointer is returned.

If the data and coefficient widths, number of coefficients and output precision result in an output precision greater than supported by the double (xip_real) data type then the model uses the mpz_t data type [Ref 14] (xip_mpz) and issues a warning indicating this requirement when this function is executed.

Get Model Configuration

xip_status
xip_fir_v7_2_get_config (
    xip_fir_v7_2* model,
    xip_fir_v7_2_config* config
)

This function returns the full configuration of the model. The function is intended to be primarily used to determine the output width and output fractional width of the model.

Note: The coeff pointer of the returned xip_fir_v7_2_config structure is set to NULL.

Reset Model Object

xip_status
xip_fir_v7_2_reset(
    xip_fir_v7_2* model
);

This function resets in the internal state of the FIR Compiler model object pointed to by model. A reset causes all data and pending configuration packets to be cleared from the model. As per the core, any pending reload packets are retained.

Destroy Model Object

xip_status
xip_fir_v7_2_destroy(
    xip_fir_v7_2* model
);

This function deallocates the model object pointed to by model. Any system resources or memory belonging to the model object are released on return from this function. The model object becomes undefined, and any further attempt to use it is an error

Set Output Data Array

xip_status
xip_fir_v7_2_set_data_sink(
    xip_fir_v7_2* model,
    xip_array_real* data,
    xip_array_complex* cmplx_data
);
xip_status
xip_fir_v7_2_set_data_sink_mpz(
    xip_fir_v7_2* model,
    xip_array_mpz* data,
    xip_array_mpz_complex* cmplx_data
);

This function registers an array (the data sink), pointed to by data or cmplx_data, to push the generated filter output when the xip_fir_v7_2_data_send function is called. Only data or cmplx_data can be set, the other should be set to NULL (or 0).

If the data sink is undefined the filter output must be explicitly pulled using the xip_fir_v7_2_data_get function.

The array is automatically sized by the model given the size of the input request. The owner field of xip_array_<type> is ignored and forced to 0.

Note: The complex data sink is intended for the Hilbert filter type but is populated for other filter types with im set to 0.

Set Data Handler

xip_status
xip_fir_v7_2_set_data_handler(
    xip_fir_v7_2* model,
    xip_array_real_handler data_handler,
    void* handle,
    void* opt_arg
);

This function registers a data handler call back function that is called when the output data array is filled following a call to xip_fir_v7_2_data_send. The FIR Compiler C model API contains a function, xip_fir_v7_2_data_send_handler (see Send DATA Packet ), to send data to an instance of the model whose signature matches that of a data handler

The intention of this facility is to enable multiple instances of the model to be chained together such that only the first and last instance of the chain need to be directly controlled using the xip_fir_v7_2_data_send and xip_fir_v7_2_data_get functions.

The model only supports data handlers for output data arrays of type xip_array_real and the value passed to the (*xip_array_real_handler) function for the data argument is the value set by the xip_fir_v7_2_set_data_sink function. See Type Definitions for details of the data handler function signature. Its arguments are:

  1. data: A pointer to the xip_array_real type containing the data to be processed. The array registered by the xip_fir_v7_2_set_data_sink function.
  2. handle: A void pointer used to point to the next model instance in the filter chain.
  3. opt_arg: An extra generic argument not currently used by the FIR Compiler C model.

Calculate Output Size

xip_status
xip_fir_v7_2_data_calc_size(
    xip_fir_v7_2* model,
    const xip_array_real* data_in,
    xip_array_real* data_out,
    xip_array_complex* cmplx_data_out
)
xip_status
xip_fir_v7_2_data_calc_size_mpz(
    xip_fir_v7_2* model,
    const xip_array_real* data_in,
    xip_array_mpz* data_out,
    xip_array_mpz_complex cmplx_data_out
)

This function calculates the size of an output packet/array given the size of the supplied input packet/array.

The data_out or cmplx_data_out array dimensions are modified to reflect the size of output the model produces, given the data_in array. The array dimensions, dim and data_size element are updated but the function does not allocate more space. Ensure that the correct amount of space is allocated for the data element of the array.

Note: Only one of data_out or cmplx_data_out can be set; the other should be set to NULL (or 0).