Common API

COMMON GENERIC 

group Generic

Generic utilities and helper functions for the Common API.

This group includes base types, macros, and helper functions that are shared across modules. Useful for general operations needed by multiple parts of the library.

Defines

ADDI_DATA_DISABLE: Disable flag (0).

ADDI_DATA_ENABLE: Enable flag (1).

Enums

enum ADDI_DATA_TCW_OPTIONS

Timer/Counter/Watchdog option flags.

This bitmask controls behaviour for timers, counters, and watchdogs. Multiple flags may be combined using bitwise OR.

Available flags:

COUNT_DIRECTION_UP / COUNT_DIRECTION_DOWN (APCIx-1564 only)
COUNTER_FALLING_EDGE_COUNT / COUNTER_RISING_EDGE_COUNT / COUNTER_BOTH_EDGE_COUNT (APCIx-1564 only)
SINGLE_CYCLE (APCIx-1500 only)
EXTERNAL_TRIGGER (APCIx-1500 only)
HARDWARE_GATE (APCIx-1500 only)

Values:

enumerator COUNT_DIRECTION_DOWN

enumerator COUNT_DIRECTION_UP

enumerator SINGLE_CYCLE

enumerator EXTERNAL_TRIGGER

enumerator HARDWARE_GATE

enumerator COUNTER_FALLING_EDGE_COUNT

enumerator COUNTER_RISING_EDGE_COUNT

enumerator COUNTER_BOTH_EDGE_COUNT

enum ADDI_DATA_DEVICE_TYPE

Indicates the hardware type of the device.

Values:

enumerator PCI: Legacy PCI device

enumerator PCIE: PCI Express device

enumerator MSXE: MSX-series device

enum DIGIO_COUNTER_TIMER_SOURCE

Digital I/O source for counter/timer operations.

Values:

enumerator SIGNAL_INPUT

enumerator TRIGGER_INPUT

enumerator GATE_INPUT

enum PORT_DIRECTION

Digital I/O Port Direction (Input or Output).

Values:

enumerator PORT_INPUT

enumerator PORT_OUTPUT

enum TIMEBASE_UNITS

Timebase units for timers and watchdogs.

Values:

enumerator MICROSECOND: µs

enumerator MILLISECOND: ms

enumerator SECOND: s

enumerator CUSTOM: Custom frequency set by user

COMMON INFORMATIONS STRUCTURE 

group Info Structure

Structure objects which contain information about devices and modules.

This group includes information structures that are shared across modules.

Enums

enum DIGITAL_EVENT_TYPE

Supported event types for digital input interrupts.

These values represent the trigger condition used when configuring digital input interrupts.

Some values are device-specific:

ON_ZERO and ON_ONE are only supported by APCIx-1500 devices.

Values:

enumerator UNUSED: No event configured

enumerator ON_ZERO: Input should be 0 when the trigger input comes (only relevant in 1500 “AND” Logic)

enumerator ON_ONE: Input should be 1 when the trigger input comes (only relevant in 1500 “AND” Logic)

enumerator FALLING_EDGE: Trigger on falling edge

enumerator RISING_EDGE: Trigger on rising edge

enumerator ANY_EDGE: Trigger on both edges

enum DIGITAL_EVENT_LOGIC

Logic mode used when combining multiple digital input events.

Defines how multiple input lines within the same port contribute to generating an interrupt.

Values:

enumerator OR: Interrupt triggers if at least one bit in the event mask produces the configured event

enumerator AND: Interrupt triggers only if all bits in the event mask produce the configured event simultaneously.

struct TimerInformations

#include <addidata_types.h>

Defines timer capabilities for a given device.

Public Members

uint8_t number_timers: Number of available timers

uint16_t max_reload_value[NUMBER_OF_TIMEBASES]: Maximum reload values for each timebase

uint32_t valid_options: Bitmask representing valid timer options

uint16_t min_reload_value[NUMBER_OF_TIMEBASES]: Minimum reload values for each timebase

struct WatchdogInformations

#include <addidata_types.h>

Defines watchdog capabilities for a given device.

Public Members

uint8_t number_watchdogs: Number of available watchdogs

uint16_t max_reload_value[NUMBER_OF_TIMEBASES]: Maximum reload values for each timebase

uint32_t valid_options: Bitmask representing valid watchdog options

uint16_t min_reload_value[NUMBER_OF_TIMEBASES]: Minimum reload values for each timebase

struct CounterInformations

#include <addidata_types.h>

Counter subsystem capabilities.

Public Members

uint8_t number_counters: Number of available counters

uint32_t max_reload_value: Maximum reload value supported by each counter

uint32_t valid_options: Bitmask representing valid counter options

struct AddiDataFunctionInformations

#include <addidata_types.h>

Functional capability overview of a device.

Aggregates all functional capability information of a device. This structure groups the available features for:

digital input/output,
timers,
watchdogs,
counters.

Each sub-structure provides detailed information such as number of units, valid configuration options, and value ranges.

Public Members

DigitalInformations digital: Digital I/O capabilities of the device

TimerInformations timer: Timer subsystem information

WatchdogInformations watchdog: Watchdog subsystem information

CounterInformations counter: Counter subsystem information

struct AddiDataPCIBusInformations

#include <addidata_types.h>

Low-level PCI/PCIe bus information.

Provides low-level PCI/PCIe bus information for the device. This includes identifiers, bus location, BAR mappings, and interrupt routing information.

The structure is populated during device discovery and allows applications or diagnostic tools to inspect how the card is mapped in the system.

Public Members

uint16_t vendor_id: PCI vendor ID (e.g. 0x15B8 for ADDI-DATA)

uint16_t device_id: PCI device ID identifying the board model

uint32_t number: Internal device index within Addi-Pack

uint32_t device_number: Device number on the PCI bus

uint32_t bus_number: PCI bus number where the board is located

BAR_TYPE base_address_register[ADDI_MAX_BAR]: BAR (Base Address Register) mappings

uint8_t interrupt_number: Interrupt line or vector used by the device

uint8_t is_pcie: 1 if the device is PCIe, 0 if legacy PCI

struct AddiDataGeneralInformations

#include <addidata_types.h>

User-visible high-level information about a device.

Contains high-level identification data returned during device discovery. This structure provides static information (model, serial number), software information (driver/library versions), and runtime identifiers such as the device path or custom user-defined ID.

Public Members

char serial_number[ADDI_STRING_SIZE]: Hardware serial number of the device

char product_name[ADDI_STRING_SIZE]: Product model name (e.g. “apcie1500”)

char firmware_version[ADDI_STRING_SIZE]: On-board firmware revision

char library_version[ADDI_STRING_SIZE]: Addi-Pack API library version

char driver_version[ADDI_STRING_SIZE]: Installed driver version

char device_path[ADDI_STRING_SIZE]: System path used to access the device (OS-dependent)

wchar_t custom_id[ADDI_STRING_SIZE]: Optional user-defined identifier (Windows only, filled by the windows device manager layer)

ADDI_DATA_DEVICE_TYPE device_type: Device type enumeration (PCI, PCIe, CPCI, etc.)

struct AddiDataDeviceStruct

#include <addidata_types.h>

Main structure returned by device discovery.

This structure aggregates all relevant information about an ADDI-DATA board. It is filled by the device discovery process and used throughout the API to identify and interact with a specific hardware device.

The structure groups:

A unique device identifier (id)
General identification and versioning information (general)
Functional capabilities (digital I/O, timers, counters, watchdogs) (functions)
PCI/PCIe bus details (bus)

Every API function that targets a device expects an instance of AddiDataDeviceStruct. Applications should typically retrieve it using AddiDataGetDeviceList() or the device-selection utilities provided in the samples.

Public Members

char id[ADDI_STRING_SIZE]: Unique identifier assigned to the device instance

AddiDataGeneralInformations general: High-level information: model, versions, serial, etc.

AddiDataFunctionInformations functions: Functional capabilities and limits

AddiDataPCIBusInformations bus: PCI/PCIe configuration and hardware bus details

struct DigitalInformations

#include <digital_io.h>

Digital I/O capability information for a device.

This structure provides the capabilities of the digital I/O subsystem for a device, including:

number of available inputs and outputs,
number of ports,
which input lines support interrupt events.

Public Members

uint8_t number_inputs: Number of digital input channels

uint8_t number_outputs: Number of digital output channels

uint8_t number_of_ports: Number of digital I/O ports

uint32_t interrupt_mask: Mask of input lines supporting interrupt events

struct InterruptData

#include <interrupt.h>

Information provided by the driver when an interrupt occurs.

Public Members

uint32_t interrupt_source: Bitfield indicating the interrupt source

uint32_t interrupt_mask: Mask of channels/bits involved in the interrupt

uint32_t arg_count: Number of extra arguments available

uint32_t args[ADDI_INTERRUPT_MAX_ARG_SIZE]: Array of device-specific additional data

COMMON ERROR CODES 

group Error Codes

Error codes and definitions for the Common API.

This group includes error codes and definitions that are shared across modules.

Defines

ADDIDATA_FUNCTION_SHIFT

32-bit status/error mask.

The bit layout is structured as follows:

Bits	Field	Size	Description
31	API/DRV	1 bit	0 = Driver, 1 = API
30-24	Domain	7 bits	Functional domain ID
23-16	Reserved	8 bits	Reserved for future use
15-8	Function	8 bits	Function identifier
7-0	Reason	8 bits	Error/reason code

ADDIDATA_CODE(source, domain, func, reason)

Create a complete AddiPack error code from its fields.

Parameters:

source – 0 = Driver, 1 = API
domain – Domain ID
func – Function ID
reason – Reason code

Returns:

Encoded 32-bit error code.

Enums

enum AddiDataSource

Source of the error.

Identifies whether the error originated from the driver or the API.

Table of values

Name	Value	Description
ADDIDATA_DRIVER	0	Error from driver
ADDIDATA_API	1	Error from API

Values:

enumerator ADDIDATA_DRIVER

enumerator ADDIDATA_API

enum AddiDataDomain

Domains for error classification.

Each domain represents a subsystem or functional module within Addi-Pack.

Table of values

Name	Value	Description
ADDIDATA_DOMAIN_GENERIC	0	General / unspecified
ADDIDATA_DOMAIN_COUNTER	1	Counter subsystem
ADDIDATA_DOMAIN_DIGIO	2	Digital I/O subsystem
ADDIDATA_DOMAIN_TIMER	3	Timer subsystem
ADDIDATA_DOMAIN_WATCHDOG	4	Watchdog subsystem
ADDIDATA_DOMAIN_INTERRUPTS	5	Interrupt handling
ADDIDATA_DOMAIN_LINUX_IOCTL	6	Linux IOCTL layer
ADDIDATA_DOMAIN_WIN_IOCTL	7	Windows IOCTL layer
ADDIDATA_DOMAIN_DIG_EVENT	8	Digital event
ADDIDATA_DOMAIN_PLUGIN	9	Plugin domain

Values:

enumerator ADDIDATA_DOMAIN_GENERIC

enumerator ADDIDATA_DOMAIN_COUNTER

enumerator ADDIDATA_DOMAIN_DIGIO

enumerator ADDIDATA_DOMAIN_TIMER

enumerator ADDIDATA_DOMAIN_WATCHDOG

enumerator ADDIDATA_DOMAIN_INTERRUPTS

enumerator ADDIDATA_DOMAIN_LINUX_IOCTL

enumerator ADDIDATA_DOMAIN_WIN_IOCTL

enumerator ADDIDATA_DOMAIN_DIG_EVENT

enumerator ADDIDATA_DOMAIN_PLUGIN

enum AddiDataFunction

Functions for error classification.

Identifies which operation or API function generated the error.

Table of values

Name	Value	Description
ADDIDATA_FUNCTION_NONE	0	No function defined
ADDIDATA_FUNCTION_READ	1	Read operation
ADDIDATA_FUNCTION_INTERRUPT_CALLBACK	2	Interrupt callback function
ADDIDATA_FUNCTION_IOCTL_CALL	3	IOCTL call
ADDIDATA_FUNCTION_IOCTL_INIT	4	IOCTL initialization
ADDIDATA_FUNCTION_ENABLE_INTERRUPT	5	Enable interrupt
ADDIDATA_FUNCTION_CREATE_INTERRUPT	6	Create interrupt
ADDIDATA_FUNCTION_KILL_INTERRUPT	7	Kill interrupt
ADDIDATA_FUNCTION_EVENT_FD	8	Event file descriptor
ADDIDATA_FUNCTION_WAIT_INTERRUPT	9	Wait for interrupt
ADDIDATA_FUNCTION_SELECT_EVENT	10	Select event
ADDIDATA_FUNCTION_CHECK_RELOAD_VALUE	11	Check reload value
ADDIDATA_FUNCTION_CHECK_TIMEBASE	12	Check timebase
ADDIDATA_FUNCTION_SET_DEVICE_HANDLE	13	Set device handle
ADDIDATA_FUNCTION_CALL	14	Generic function call
ADDIDATA_FUNCTION_HANDLE_RETURN	15	Handle return value
ADDIDATA_FUNCTION_CHANNEL_RANGE	16	Channel range selection
ADDIDATA_FUNCTION_INFO	17	Information retrieval
ADDIDATA_FUNCTION_INIT	18	Initialization function
ADDIDATA_FUNCTION_START	19	Start operation
ADDIDATA_FUNCTION_TRIGGER	20	Trigger function
ADDIDATA_FUNCTION_CONVERT_FREQ	21	Convert frequency
ADDIDATA_FUNCTION_STOP	22	Stop operation
ADDIDATA_FUNCTION_READ_VALUE	23	Read value
ADDIDATA_FUNCTION_READ_STATUS	24	Read status
ADDIDATA_FUNCTION_WRITE_DIGOUT	25	Write to digital output
ADDIDATA_FUNCTION_INTERRUPT_EVENT	26	Interrupt event
ADDIDATA_FUNCTION_INTERRUPT_LOGIC	27	Interrupt logic
ADDIDATA_FUNCTION_UPDATE_DIGITAL_INTERRUPT	28	Update digital interrupt
ADDIDATA_FUNCTION_GET_DIGOUT_STATUS	29	Get digital output status
ADDIDATA_FUNCTION_ENSURE_ID	30	Ensure device ID
ADDIDATA_FUNCTION_TEST	31	Test function
ADDIDATA_FUNCTION_ZILOG_INIT_EVENT	32	Zilog initialization event
ADDIDATA_FUNCTION_INIT_DIGIT_INTERRUPT	33	Initialize digital interrupt
ADDIDATA_FUNCTION_START_STOP_TCW	34	Start/stop TCW
ADDIDATA_FUNCTION_SET_OUTPUT_MEMORY	35	Set output memory
ADDIDATA_FUNCTION_INIT_EVENT_LOGIC	36	Initialize event logic
ADDIDATA_FUNCTION_INIT_TCW_COMPATIBILITY	37	Initialize TCW compatibility
ADDIDATA_FUNCTION_API_GET_LAST_ERRROR	38	Retrieve last API error
ADDIDATA_FUNCTION_DISABLE_INTERRUPT	39	Disable interrupt
ADDIDATA_FUNCTION_GET_DEVICES	40	Get devices
ADDIDATA_FUNCTION_GET_STRING	41	Get string
ADDIDATA_FUNCTION_GET_INSTANCE	42	Get instance
ADDIDATA_FUNCTION_DIRECT_ACCESS	43	Direct access
ADDIDATA_FUNCTION_OUTPUT_INTERRUPT	44	Set Output interrupt
ADDIDATA_FUNCTION_SET_PORT_DIRECTION	45	Set digital port direction
ADDIDATA_FUNCTION_GET_PORT_DIRECTION	46	Get port direction
ADDIDATA_FUNCTION_PORT_RANGE	47	Port range selection

Values:

enumerator ADDIDATA_FUNCTION_NONE

enumerator ADDIDATA_FUNCTION_READ

enumerator ADDIDATA_FUNCTION_INTERRUPT_CALLBACK

enumerator ADDIDATA_FUNCTION_IOCTL_CALL

enumerator ADDIDATA_FUNCTION_IOCTL_INIT

enumerator ADDIDATA_FUNCTION_ENABLE_INTERRUPT

enumerator ADDIDATA_FUNCTION_CREATE_INTERRUPT

enumerator ADDIDATA_FUNCTION_KILL_INTERRUPT

enumerator ADDIDATA_FUNCTION_EVENT_FD

enumerator ADDIDATA_FUNCTION_WAIT_INTERRUPT

enumerator ADDIDATA_FUNCTION_SELECT_EVENT

enumerator ADDIDATA_FUNCTION_CHECK_RELOAD_VALUE

enumerator ADDIDATA_FUNCTION_CHECK_TIMEBASE

enumerator ADDIDATA_FUNCTION_SET_DEVICE_HANDLE

enumerator ADDIDATA_FUNCTION_CALL

enumerator ADDIDATA_FUNCTION_HANDLE_RETURN

enumerator ADDIDATA_FUNCTION_CHANNEL_RANGE

enumerator ADDIDATA_FUNCTION_INFO

enumerator ADDIDATA_FUNCTION_INIT

enumerator ADDIDATA_FUNCTION_START

enumerator ADDIDATA_FUNCTION_TRIGGER

enumerator ADDIDATA_FUNCTION_CONVERT_FREQ

enumerator ADDIDATA_FUNCTION_STOP

enumerator ADDIDATA_FUNCTION_READ_VALUE

enumerator ADDIDATA_FUNCTION_READ_STATUS

enumerator ADDIDATA_FUNCTION_WRITE_DIGOUT

enumerator ADDIDATA_FUNCTION_INTERRUPT_EVENT

enumerator ADDIDATA_FUNCTION_INTERRUPT_LOGIC

enumerator ADDIDATA_FUNCTION_UPDATE_DIGITAL_INTERRUPT

enumerator ADDIDATA_FUNCTION_GET_DIGOUT_STATUS

enumerator ADDIDATA_FUNCTION_ENSURE_ID

enumerator ADDIDATA_FUNCTION_TEST

enumerator ADDIDATA_FUNCTION_ZILOG_INIT_EVENT

enumerator ADDIDATA_FUNCTION_INIT_DIGIT_INTERRUPT

enumerator ADDIDATA_FUNCTION_START_STOP_TCW

enumerator ADDIDATA_FUNCTION_SET_OUTPUT_MEMORY

enumerator ADDIDATA_FUNCTION_INIT_EVENT_LOGIC

enumerator ADDIDATA_FUNCTION_INIT_TCW_COMPATIBILITY

enumerator ADDIDATA_FUNCTION_API_GET_LAST_ERROR

enumerator ADDIDATA_FUNCTION_DISABLE_INTERRUPT

enumerator ADDIDATA_FUNCTION_GET_DEVICES

enumerator ADDIDATA_FUNCTION_GET_STRING

enumerator ADDIDATA_FUNCTION_GET_INSTANCE

enumerator ADDIDATA_FUNCTION_DIRECT_ACCESS

enumerator ADDIDATA_FUNCTION_OUTPUT_INTERRUPT

enumerator ADDIDATA_FUNCTION_GET_PORT_DIRECTION

enumerator ADDIDATA_FUNCTION_PORT_RANGE

enum AddiDataReason

Reasons for error classification.

Provides the specific reason associated with an error code.

Table of values

Name	Value	Description
ADDIDATA_REASON_NONE	0	No error reason defined
ADDIDATA_REASON_NOT_INITIALIZED	1	The module or device was not initialized
ADDIDATA_REASON_ALREADY_INITIALIZED	2	The module or device was already initialized
ADDIDATA_REASON_INVALID_PARAMETER	3	One or more input parameters were invalid
ADDIDATA_REASON_OUT_OF_BOUNDS	4	A value or index was out of valid range
ADDIDATA_REASON_NOT_SUPPORTED	5	The requested feature is not supported
ADDIDATA_REASON_OVERFLOW	6	A buffer or counter overflow occurred
ADDIDATA_REASON_UNDERFLOW	7	A buffer or counter underflow occurred
ADDIDATA_REASON_HARDWARE_FAILURE	8	A hardware failure was detected
ADDIDATA_REASON_INVALID_STATE	9	The operation was not valid in the current state
ADDIDATA_REASON_CONFIG_ERROR	10	Configuration error detected
ADDIDATA_REASON_INTERNAL_ERROR	11	Internal or unexpected error
ADDIDATA_REASON_UNKNOWN	12	Unknown or unspecified error
ADDIDATA_REASON_INFO_UNAVAILABLE	13	Requested information is unavailable
ADDIDATA_REASON_INIT_FAILURE	14	Initialization failed
ADDIDATA_REASON_INVALID_RETURN_VAL	15	Invalid return value encountered
ADDIDATA_REASON_INVALID_ID	16	Invalid identifier or handle
ADDIDATA_REASON_INVALID_OPTION	17	Invalid or unsupported option specified
ADDIDATA_REASON_INVALID_TIMEBASE	18	Invalid timebase specified
ADDIDATA_REASON_HANDLE_ERROR	19	Invalid handle

Values:

enumerator ADDIDATA_REASON_NONE

enumerator ADDIDATA_REASON_NOT_INITIALIZED

enumerator ADDIDATA_REASON_ALREADY_INITIALIZED

enumerator ADDIDATA_REASON_INVALID_PARAMETER

enumerator ADDIDATA_REASON_OUT_OF_BOUNDS

enumerator ADDIDATA_REASON_NOT_SUPPORTED

enumerator ADDIDATA_REASON_OVERFLOW

enumerator ADDIDATA_REASON_UNDERFLOW

enumerator ADDIDATA_REASON_HARDWARE_FAILURE

enumerator ADDIDATA_REASON_INVALID_STATE

enumerator ADDIDATA_REASON_CONFIG_ERROR

enumerator ADDIDATA_REASON_INTERNAL_ERROR

enumerator ADDIDATA_REASON_UNKNOWN

enumerator ADDIDATA_REASON_INFO_UNAVAILABLE

enumerator ADDIDATA_REASON_INIT_FAILURE

enumerator ADDIDATA_REASON_INVALID_RETURN_VAL

enumerator ADDIDATA_REASON_INVALID_ID

enumerator ADDIDATA_REASON_INVALID_OPTION

enumerator ADDIDATA_REASON_INVALID_TIMEBASE

enumerator ADDIDATA_REASON_HANDLE_ERROR

Functions

size_t AddiDataGetLastError(char *error_message, size_t max_len)

Function which returns the pretty messsage from AddiPackException.

This function extracts the internally stored error message generated by the most recent AddiPackException.

Parameters:

error_message – [out] Pointer to a buffer where the error message will be stored.
max_len – [in] Maximum length of the buffer in bytes.

Returns:

Number of characters copied (same as strlen(error_message)).

addi_data_code AddiDataPrintLastError(void)

Prints the last error message with the AddiDataGetLastError function. This function is a helper function. Can be used for quick checking.

Returns:: addi_data_code ADDIDATA_SUCCESS_CODE

addi_data_code AddiDataTestError(const char *device_id)

Test function that generates a predefined error for testing purposes . Will always “fail”.

Parameters:: device_id – [in] The ID of the device to test (can be any valid device ID).
Returns:: addi_data_code An error code that can be used to test error handling.

COMMON UTILITIES 

group Common Utilities

Utilities and helper functions for the Common API.

This group includes utility functions and helper methods that are shared across modules. Useful for samples for instance.

Arg Parser

group Arg Parser

Argument parser utilities for the Common API.

This group includes argument parsing functions.

Functions

void AddiDataArgParserAddOption(const char *name, char short_option, const char *description, int has_value)

Add a new command-line option.

An option may require a value (e.g. --config file.txt) or be value-less depending on has_value.

Parameters:

name – [in] Long name (e.g., “config”)
short_option – [in] Short option (e.g., ‘c’)
description – [in] Description for help output
has_value – [in] Does the option requires a value (1: yes, 0: no)

void AddiDataArgParserAddFlag(const char *name, char short_option, const char *description)

Add a new boolean flag.

Example:

--verbose or -v
Does not take a value (true if present).

Parameters:

name – [in] Long name (e.g., “verbose”)
short_option – [in] Short option (e.g., ‘v’)
description – [in] Description for help output

void AddiDataArgParserParse(int argc, char *argv[])

Parse command-line arguments.

Must be called after registering all flags and options.

Parameters:

argc – [in] Argument count
argv – [in] Argument vector

int AddiDataArgParserIsFlagSet(const char *name)

Check if a flag was set;.

Parameters:: name – [in] Long name of the flag
Returns:: 1 is set, 0 otherwise

int AddiDataArgParserIsOptionSet(const char *name)

Check if an option was set.

Parameters:: name – [in] Long name of the option
Returns:: 1 if set, 0 otherwise

int AddiDataArgParserGetOptionValue(const char *name, char *value, size_t max_size)

Retrieve the value of an option (dynamically allocated).

Parameters:

name – [in] Longname of the option (e.g., “config”)
value – [out] Buffer to write the value into (must be allocated by caller)
max_size – [in] Maximum number of bytes to write (including null terminator ‘\0’)

Returns:

1 if a value was found and copied, 0 otherwise

void AddiDataArgParserClear()

Clear the internal parser state.

Removes all options, flags and stored values. Useful when running multiple independent parses.

User I/O

group User I/O

Interactive utilities for AddiPack sample applications.

This module provides helper functions used by the interactive C samples (timer, counter, watchdog, digital I/O).

Functions

void AddiDataUtilsPrintAvailableTcwOptions(unsigned int valid_mask)

Print the list of available TCW (Timer-Counter-Watchdog) options for a given device.

This function filters all TCW options against the provided and displays only the options supported by the device. Each option is numbered sequentially starting at 1 for user selection.

Parameters:: valid_mask – [in] Bitmask of valid TCW options supported by the device

unsigned int AddiDataUtilsGetTcwOptionsFromUser(unsigned int valid_mask)

Prompt the user to select TCW (Timer-Counter-Watchdog) options interactively.

This function repeatedly prompts the user to select options from the list of valid TCW options (as previously displayed by AddiDataUtilsPrintAvailableOptions). The function updates the provided mask by applying the selected options. The loop ends when the user enters 0.

Parameters:: valid_mask – [in] Bitmask of valid TCW options for the current device
Returns:: Updated mask containing all options selected by the user

int AddiDataUtilsPromptString(const char *message, const char **accepted, int accepted_count, char *output, size_t output_size)

Prompt the user to input a string with optional accepted values and default.

Parameters:

message – [in] Prompt message to display
accepted – [in] List of accepted values (NULL if none)
accepted_count – [in] Number of accepted values
output – [out] Output buffer
output_size – [in] Size of output buffer

Returns:

1 if value was entered or default used, 0 if failed

int AddiDataUtilsPromptInt(const char *message, int min, int max)

Prompt the user to input an integer between [min, max] with optional default.

Parameters:

message – [in] Prompt message to display
min – [in] Minimum allowed value
max – [in] Maximum allowed value

Returns:

the selected integer value

unsigned int AddiDataUtilsPromptHex(const char *message, unsigned int min, unsigned int max)

Prompt the user to input a hexadecimal value between [min, max].

Parameters:

message – [in] Prompt message to display
min – [in] Minimum allowed value
max – [in] Maximum allowed value

Returns:

the selected hexadecimal value

int AddiDataUtilsGetValidString(const char *name, const char *message, const char **accepted, int accepted_count, char *output, size_t output_size)

Get a validate string from CLI args or fallback to prompt if invalid.

If the CLI --name option is present and valid, its value is returned. Otherwise the user is prompted until a valid value is entered.

Parameters:

name – [in] Name of the CLI argument (e.g. “mode”)
message – [in] Prompt message
accepted – [in] List of accepted values (NULL if none)
accepted_count – [in] Number of accepted values
output – [out] Output buffer
output_size – [in] Size of output buffer

Returns:

1 if value is valid and copied to output, 0 otherwise

int AddiDataUtilsGetValidInt(const char *name, const char *message, int min, int max)

Get a validated integer from CLI args or prompt fallback.

Parameters:

name – [in] Name of the CLI argument (e.g. “timer”)
message – [in] Prompt message
min – [in] Minimum allowed value
max – [in] Maximum allowed value

Returns:

Validated integer

unsigned int AddiDataUtilsGetValidHex(const char *name, const char *message, unsigned int min, unsigned int max)

Get a validated hexadecimal value from CLI args or prompt fallback.

Parameters:

name – [in] Name of the CLI argument (e.g. “mask”)
message – [in] Prompt message
min – [in] Minimum allowed value
max – [in] Maximum allowed value

Returns:

Validated hexadecimal value

void AddiDataUtilsExitOnUserInput(int exit_code)

Waits for the user to press ENTER, then exits the program.

Parameters:: exit_code – [in] the code to return. ‘EXIT_FAILURE’ or ‘EXIT_SUCCESS’.

void AddiDataUtilsDisplayAllPortsConfigurations(uint16_t port_mask, uint8_t *input_values, uint8_t *output_value, uint8_t max_port)

Get the configuration (input/output) of all digital ports on the device.

This function fills the provided output arrays with the configuration of each port specified in the port_mask.

Parameters:

port_mask – [in] Bitmask related to the current port configuration.
input_values – [in] Current Input value of the ports (from 0x00 to 0xFF for each port).
output_value – [in] Current Output value of the ports (from 0x00 to 0xFF for each port).
max_port – [in] Maximum number of ports to check (size of input_values and output_value arrays)

Device

group Device Utils

Device utilities for the CPP API.

Device related utilities and helper functions.

Functions

int AddiDataUtilsMatchesCardFilter(const AddiDataDeviceStruct *device, const char *card_filter)

Check whether a device matches a card filter string.

Parameters:

device – [in] Pointer to device struct
card_filter – [in] Filter string (nullable or empty to match all)

Returns:

1 if matches, 0 otherwise

const AddiDataDeviceStruct *AddiDataUtilsSelectDeviceByCapability(const AddiDataDeviceStruct *devices, int number_of_devices, const char *name, int (*predicate)(const AddiDataDeviceStruct*), const char *label)

Select a device matching a predicate from a list of devices.

If CLI --name is provided and matches exactly, that device is returned. Otherwise, the user is prompted to pick from all devices satisfying predicate.

Parameters:

devices – [in] Array of devices
number_of_devices – [in] Number of devices in devices
name – [in] CLI argument name (e.g. “card”)
predicate – [in] Predicate used to filter eligible devices
label – [in] Label to display (e.g. “timer”)

Returns:

Pointer to the selected device, or NULL on failure

int AddiDataUtilsSelectMode(const char *name, const char *modes[], const char *descriptions[], int count, char *output, size_t output_size)

Select a string mode from a list, using CLI --<name> or prompt.

Parameters:

name – [in] CLI option name (e.g. “mode”)
modes – [in] List of available mode strings
descriptions – [in] Optional descriptions for each mode (NULL if none)
count – [in] Number of modes
output – [out] Output buffer
output_size – [in] Size of output buffer

Returns:

1 if a valid selection was made and copied to output, 0 on failure

Timer Interruptions

group Timer Interruptions Utils

Timer interruption utilities for the CPP API.

Timer interruption related utilities and helper functions.

Functions

TIMEBASE_UNITS AddiDataUtilsParseTimebase(const char *timebase)

Parse a timebase string (“us”, “ms”, “s”) into a TIMEBASE_UNITS enum value.

Parameters:: timebase – [in] String value (“us”, “ms” or “s”)
Returns:: Parsed TIMEBASE_UNITS enum value

void AddiDataUtilsInterruptCallback(AddiDataDeviceStruct device, InterruptData data)

Default interrupt callback function. Logs the source, mask and elapsed time.

Logs:
- interrupt source
- interrupt mask
- instantaneous latency since last interrupt

Parameters:

device – [in] Device that triggered the interrupt
data – [in] Interrupt data structure

void AddiDataUtilsResetInterruptFlag(): Reset the interrupt flag and internal timer.

int AddiDataUtilsHasInterruptHappened()

Check whether an interrupt has occurred since the last reset.

Returns:: 1 if interrupt happened, 0 otherwise

int AddiDataUtilsGetValidTimebaseList(const AddiDataDeviceStruct *device, const char **timebases)

Get a list of valid timebases supported by the device.

This function returns only the timebases for which a max reload value exists.

Parameters:

device – [in] Pointer to the selected device
timebases – [out] Output array of timebase strings (“us”,”ms,””s”,”c”)

Returns:

Number of valid timebases written to timebases

Windows-Linux Compatibility

group Windows-Linux compatility Utils

Compatibility utilities.

Windows and Linux compatibility related utilities and helper functions.

Functions

static inline int _kbhit()

This is not strictly an equivalent, as most linux terminal need “enter” to be pressed to relay input buffer to an application.

Returns:: 0 if no input is available 1 if one is available.

Common API

COMMON GENERIC

COMMON INFORMATIONS STRUCTURE

COMMON ERROR CODES

COMMON UTILITIES

Arg Parser

User I/O

Device

Timer Interruptions

Windows-Linux Compatibility

COMMON GENERIC 

COMMON INFORMATIONS STRUCTURE 

COMMON ERROR CODES 

COMMON UTILITIES 