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:
- A generic pointer (
void*
). This is always the value that was passed in as themsg_handle
argument to the create function. - An integer (
int
) indicating whether the message is an error (1) or a note or warning (0). - 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.
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.
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:
-
data
: A pointer to thexip_array_real
type containing the data to be processed. The array registered by thexip_fir_v7_2_set_data_sink
function. - handle: A void pointer used to point to the next model instance in the filter chain.
-
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.
data_out
or cmplx_data_out
can be
set; the other should be set to NULL (or 0).