Macros
#define	PDSERV_VERSION(major, minor, patchlevel) (((major) << 16) + ((minor) << 8) + (patchlevel))
	Generate version code from major, minor and patchlevel.

#define	PDSERV_VERSION_CODE PDSERV_VERSION(3,3,1)
	Current library version code.

#define	PDSERV_VERSION_MAJOR 3
	Current library major version code.

#define	PDSERV_VERSION_MINOR 3
	Current library minor version code.

#define	PDSERV_VERSION_PATCH 1
	Current library patch version code. Note: this may be a string!

#define	HAS_VERSION_CODE
	Macro to indicate that there is a pdserv_version_str.

#define	pd_double_T 1
	double precision floating point data type

#define	pd_single_T 2
	single precision floating point data type

#define	pd_uint8_T 3
	8 bit unsigned integer data type

#define	pd_sint8_T 4
	8 bit signed integer data type

#define	pd_uint16_T 5
	16 bit unsigned integer data type

#define	pd_sint16_T 6
	16 bit signed integer data type

#define	pd_uint32_T 7
	32 bit unsigned integer data type

#define	pd_sint32_T 8
	32 bit signed integer data type

#define	pd_uint64_T 9
	64 bit unsigned integer data type

#define	pd_sint64_T 10
	64 bit signed integer data type

#define	pd_boolean_T 11
	boolean data type

#define	pd_schar_T 12
	signed char data type

#define	pd_char_T 13
	char data type

#define	pd_uchar_T 14
	unsigned char data type

#define	pd_short_T 15
	short data type

#define	pd_ushort_T 16
	unsigned short data type

#define	pd_int_T 17
	int data type

#define	pd_uint_T 18
	unsigned int data type

#define	pd_long_T 19
	long data type

#define	pd_ulong_T 20
	unsigned long data type

#define	pd_longlong_T 21
	long long data type

#define	pd_ulonglong_T 22
	unsigned long long data type

#define	pd_ssize_T 23
	signed size_t data type

#define	pd_size_T 24
	size_t data type

#define	RESET_EVENT 0
	Reset the event.

#define	EMERG_EVENT 1
	Emergency event.

#define	ALERT_EVENT 2
	Alert event.

#define	CRIT_EVENT 3
	Critical event.

#define	ERROR_EVENT 4
	Error event.

#define	WARN_EVENT 5
	Warning event.

#define	NOTICE_EVENT 6
	Notice event.

#define	INFO_EVENT 7
	Information event.

#define	DEBUG_EVENT 8
	Debug event.

Typedefs
typedef int(*	gettime_t) (struct timespec *)

typedef int(*	write_parameter_t) (const struct pdvariable param, void dst, const void src, size_t len, struct timespec time, void *priv_data)

Functions
PDSERV_EXPORT struct pdserv *	pdserv_create (const char name, const char version, gettime_t gettime_cb)

PDSERV_EXPORT void	pdserv_config_file (struct pdserv pdserv, const char file)

PDSERV_EXPORT void	pdserv_set_parameter_writelock_cb (struct pdserv pdserv, void(fn)(int lock, void priv_data), void priv_data)

PDSERV_EXPORT struct pdtask *	pdserv_create_task (struct pdserv pdserv, double tsample, const char name)

PDSERV_EXPORT void	pdserv_set_signal_readlock_cb (struct pdtask pdtask, void(fn)(int lock, void priv_data), void priv_data)

PDSERV_EXPORT int	pdserv_create_compound (const char *name, size_t size)

PDSERV_EXPORT void	pdserv_compound_add_field (int compound, const char name, int data_type, size_t offset, size_t ndim, const size_t dim)

PDSERV_EXPORT struct pdvariable *	pdserv_signal (struct pdtask pdtask, unsigned int decimation, const char path, int datatype, const void addr, size_t n, const size_t dim)

PDSERV_EXPORT struct pdevent *	pdserv_event (struct pdserv pdserv, const char path, size_t n)

PDSERV_EXPORT void	pdserv_event_set_text (struct pdevent event, const char const *text)

PDSERV_EXPORT void	pdserv_event_set (const struct pdevent event, size_t element, int priority, const struct timespec t)

PDSERV_EXPORT void	pdserv_event_reset (const struct pdevent event, size_t element, const struct timespec t)

PDSERV_EXPORT void	pdserv_event_set_all (const struct pdevent event, const unsigned int level, const struct timespec *t)

PDSERV_EXPORT struct pdvariable *	pdserv_parameter (struct pdserv pdserv, const char path, unsigned int mode, int datatype, void addr, size_t n, const size_t dim, write_parameter_t write_cb, void *priv_data)

PDSERV_EXPORT void	pdserv_set_alias (struct pdvariable variable, const char alias)

PDSERV_EXPORT void	pdserv_set_unit (struct pdvariable variable, const char unit)

PDSERV_EXPORT void	pdserv_set_comment (struct pdvariable variable, const char comment)

PDSERV_EXPORT const char *	pdserv_get_variable_path (const struct pdvariable *variable)

PDSERV_EXPORT int	pdserv_prepare (struct pdserv *pdserv)

PDSERV_EXPORT void	pdserv_update_statistics (struct pdtask *pdtask, double exec_time, double cycle_time, unsigned int overrun)

PDSERV_EXPORT void	pdserv_update (struct pdtask pdtask, const struct timespec t)

PDSERV_EXPORT void	pdserv_exit (struct pdserv *)

Variables
PDSERV_EXPORT const char *const	pdserv_version_str
	String of pdserv version code "major.minor.patch".

PDSERV_EXPORT const char *const	pdserv_full_version
	Full String of pdserv version, generated by `git describe`.

Typedef Documentation

◆ gettime_t

typedef int(* gettime_t) (struct timespec *)

Generic handle to an event Callback function type to get current world time

◆ write_parameter_t

typedef int(* write_parameter_t) (const struct pdvariable *param, void *dst, const void *src, size_t len, struct timespec *time, void *priv_data)

Callback on a parameter update event

This function is responsible for copying the data from src to dst.

The function allows the user to synchronize his application to the external events of setting a parameter.

Essentially the function should execute the following:

lock(priv_data);
memcpy(dst, src, len);
clock_gettime(CLOCK_REALTIME, time);
unlock(priv_data);

Parameters

param	Handle to parameter
dst	Copy destination address
src	Copy source address
len	Bytes to copy
time	Copy current time into this struct. It is preset to the current process time.
priv_data	Private data pointer passed when calling pdserv_parameter()

Returns: 0 on success

Function Documentation

◆ pdserv_compound_add_field()

PDSERV_EXPORT void pdserv_compound_add_field	(	int	compound,
		const char *	name,
		int	data_type,
		size_t	offset,
		size_t	ndim,
		const size_t *	dim
	)

Add a field to a compound data type

Parameters

compound	Compound data type identifier
name	Data type name
data_type	Field data type identifier: pd_*_T compound identifier from pdserv_create_compound()
offset	Offset of field; use offsetof()
ndim	Number of dimensions in `dim`
dim	Dimensions

◆ pdserv_config_file()

PDSERV_EXPORT void pdserv_config_file	(	struct pdserv *	pdserv,
		const char *	file
	)

Set the path to a configuration file

This file will loaded during pdserv_prepare() in non-real-time context.

Failure to load will be reported in syslog.

If a configuration file is not specified, it will attempt to load

PDSERV_CONFIG environment variable
/usr/local/etc/pdserv.conf

Parameters

pdserv	Handle to pdserv
file	Path to configuration file

Examples:: example-st.c.

◆ pdserv_create()

PDSERV_EXPORT struct pdserv* pdserv_create	(	const char *	name,
		const char *	version,
		gettime_t	gettime_cb
	)

Initialise pdserv library.

This is the first call to initialize an instance of the library. It must be called before any other library calls.

Returns

handle to an opaque instance of pdserv
NULL on error

Parameters

name	Name of the process
version	Version string
gettime_cb	Function used by the library when the system time is required. Essentially, this function should call clock_gettime(). If NULL, gettimeofday() is used.

Examples:: example-st.c.

◆ pdserv_create_compound()

PDSERV_EXPORT int pdserv_create_compound	(	const char *	name,
		size_t	size
	)

Create compound data type

Use this to create an application specific data type. Use pdserv_compound_add_field() to insert fields

Returns: compound data type identifier

Parameters

name	Data type name
size	Size of compound

◆ pdserv_create_task()

PDSERV_EXPORT struct pdtask* pdserv_create_task	(	struct pdserv *	pdserv,
		double	tsample,
		const char *	name
	)

Create a cyclic task

An application consists of one or more tasks that are called cyclically by caller. Tasks are used to organize signals.

Returns

handle to an opaque task instance
NULL on error

Parameters

pdserv	Handle to pdserv
tsample	Base sample time of task
name	Optional name; can be NULL

Examples:: example-st.c.

◆ pdserv_event()

PDSERV_EXPORT struct pdevent* pdserv_event	(	struct pdserv *	pdserv,
		const char *	path,
		size_t	n
	)

Register an event channel

Event channels are used to implement a messaging system. A clear text message corresponding to the event element is printed when the event is set using pdserv_event_set().

Parameters

pdserv	Handle to pdserv
path	Event path
n	Vector size

Examples:: example-st.c.

◆ pdserv_event_reset()

PDSERV_EXPORT void pdserv_event_reset	(	const struct pdevent *	event,
		size_t	element,
		const struct timespec *	t
	)

Reset an event.

This function is used to reset an event. This causes the corresponding message to be printed to log and all clients.

Parameters

event	Opage event structure
element	Event element
t	Current time

◆ pdserv_event_set()

PDSERV_EXPORT void pdserv_event_set	(	const struct pdevent *	event,
		size_t	element,
		int	priority,
		const struct timespec *	t
	)

Set the state of a single event.

This function is used to set an event to the given state. Setting the event causes the corresponding message to be printed to log and all clients.

Parameters

event	Opage event structure
element	Event element
priority	One of: EMERG_EVENT ALERT_EVENT CRIT_EVENT ERROR_EVENT WARN_EVENT NOTICE_EVENT INFO_EVENT DEBUG_EVENT
t	Current time

◆ pdserv_event_set_all()

PDSERV_EXPORT void pdserv_event_set_all	(	const struct pdevent *	event,
		const unsigned int *	level,
		const struct timespec *	t
	)

Set the state of event vector.

This function is used to set an event to the given state. Setting the event causes the corresponding message to be printed to log and all clients.

This call is similar to pdserv_event_set(), except that its state state is stored internally. Only when level changes will the event be generated or reset. Thus this function can be called continuously from the cyclic task.

Do not mix the calls to pdserv_event_set_state() and pdserv_event_set() pdserv_event_reset() pair

Parameters

event	Opage event structure
level	One of: EMERG_EVENT ALERT_EVENT CRIT_EVENT ERROR_EVENT WARN_EVENT NOTICE_EVENT INFO_EVENT DEBUG_EVENT RESET_EVENT

The vector length must be the same as that specified when calling pdserv_event()

Parameters

t	Current time

Examples:: example-st.c.

◆ pdserv_event_set_text()

PDSERV_EXPORT void pdserv_event_set_text	(	struct pdevent *	event,
		const char const	text
	)

Set a text message for events

Parameters

event	Handle to event
text	Event text list, same size as event

PdServ does not make a copy of these messages. They must be available permanently.

Examples:: example-st.c.

◆ pdserv_exit()

PDSERV_EXPORT void pdserv_exit ( struct pdserv * )

Cleanup pdserv

Examples:: example-st.c.

◆ pdserv_get_variable_path()

PDSERV_EXPORT const char* pdserv_get_variable_path ( const struct pdvariable * variable )

Get the path of a registered Parameter or Signal.

Useful for example in Parameter Update Event Callback.

See also: write_parameter_t

Returns: Path of given variable.

Parameters

variable Parameter or Signal address

◆ pdserv_parameter()

PDSERV_EXPORT struct pdvariable* pdserv_parameter	(	struct pdserv *	pdserv,
		const char *	path,
		unsigned int	mode,
		int	datatype,
		void *	addr,
		size_t	n,
		const size_t *	dim,
		write_parameter_t	write_cb,
		void *	priv_data
	)

Register a parameter

This call registers a parameter. See pdserv_signal() for the description of similar function arguments.

During the registration of a parameter, the caller can supply a callback function write_cb of type write_parameter_t that is called with data source and destination addresses when a parameter is changed. write_cb is responsible to copy the data, usually using memcpy(). If custom locking is used (see pdserv_set_parameter_writelock_cb()), that function will be called before and after write_cb.

By default memcpy() will be used automatically when write_cb is NULL.

Parameters

pdserv	Handle to pdserv
path	Parameter path
mode	Access mode, same as Unix file mode
datatype	Parameter data type identifier: pd_*_T compound identifier from pdserv_create_compound()
addr	Parameter address
n	Parameter element count. If `dim` != NULL, this is the number elements in `dim`
dim	Dimensions. If NULL, the parameter is a vector of length `n`
write_cb	Callback for updating the parameter inside real time context
priv_data	Arbitrary pointer passed to `write_cb` when it is called

Examples:: example-st.c.

◆ pdserv_prepare()

PDSERV_EXPORT int pdserv_prepare ( struct pdserv * pdserv )

Finish initialisation

This function is called after registering all variables and parameters, just before going into cyclic real time. This will fork off the process that communicates with the rest of the world.

Since the new process lives in a separate memory space, all parameters must have been initialised beforehand. After calling pdserv_prepare(), parameters should not be changed any more. They can only be updated though a call by the library.

Returns: 0 on Success, nonzero on Error (usually the value of errno ).

Parameters

pdserv Handle to pdserv

Examples:: example-st.c.

◆ pdserv_set_alias()

PDSERV_EXPORT void pdserv_set_alias	(	struct pdvariable *	variable,
		const char *	alias
	)

Set an optional alias for a variable

Sometimes it it easier to find a variable by its alias. Use this function after calling either pdserv_signal() or pdserv_parameter() to set the alias name for a variable.

Parameters

variable	Parameter or Signal address
alias	Variable's alias

◆ pdserv_set_comment()

PDSERV_EXPORT void pdserv_set_comment	(	struct pdvariable *	variable,
		const char *	comment
	)

Set the optional comment of a variable

Parameters

variable	Parameter or Signal address
comment	Variable's comment

Examples:: example-st.c.

◆ pdserv_set_parameter_writelock_cb()

PDSERV_EXPORT void pdserv_set_parameter_writelock_cb	(	struct pdserv *	pdserv,
		void()(int lock, void priv_data)	fn,
		void *	priv_data
	)

Register a function to be called when setting a parameter's value.

Since parameter writes from a client application are asynchronous as far as the real-time threads are concerned, access to them must be protected using a lock or inconsistent data is risked.

This function registers a callback which is called before (with lock = 1) and after (with lock = 0) setting the parameter value. Inside the callback a lock can be aquired and realeased as required, for instance.

Parameters

pdserv	Handle to pdserv
fn	function to call
priv_data	private data passed to callback

Examples:: example-st.c.

◆ pdserv_set_signal_readlock_cb()

PDSERV_EXPORT void pdserv_set_signal_readlock_cb	(	struct pdtask *	pdtask,
		void()(int lock, void priv_data)	fn,
		void *	priv_data
	)

Register a function to be called when polling a signal's value.

Since polling a signal value from a client application is asynchronous as far as the real-time thread is concerned, access to it must be protected using a lock or inconsistent data is risked.

This function registers a callback which is called before (with lock = 1) and after (with lock = 0) copying the signal value. Inside the callback a lock can be aquired and realeased as required, for instance.

Parameters

pdtask	Handle to pdtask
fn	function to call
priv_data	private data passed to callback

Examples:: example-st.c.

◆ pdserv_set_unit()

PDSERV_EXPORT void pdserv_set_unit	(	struct pdvariable *	variable,
		const char *	unit
	)

Set the optional unit of a variable

Parameters

variable	Parameter or Signal address
unit	Variable's unit

◆ pdserv_signal()

PDSERV_EXPORT struct pdvariable* pdserv_signal	(	struct pdtask *	pdtask,
		unsigned int	decimation,
		const char *	path,
		int	datatype,
		const void *	addr,
		size_t	n,
		const size_t *	dim
	)

Register a signal

This call registers a signal, i.e. Variables that are calculated during a task's execution.

Arguments n and dim are used to specify the shape:

For scalars:
- n: 1
- dim: NULL
For vectors length x
- n: x
- dim: NULL
For arrays:
int array[2][3][4]
size_t array_dim[] = {2,3,4};
- n: 3
- dim: array_dim

Argument decimation specifies calculation decimation of the signal within the task if it is not calculated every time.

Parameters

pdtask	Handle to pdtask
decimation	Decimation with which the signal is calculated
path	Signal path
datatype	Signal data type identifier pd_*_T compound identifier from pdserv_create_compound()
addr	Signal address
n	Element count. If `dim` != NULL, this is the number elements in `dim`
dim	Dimensions. If NULL, consider the parameter to be a vector of length `n`

Examples:: example-st.c.

◆ pdserv_update()

PDSERV_EXPORT void pdserv_update	(	struct pdtask *	pdtask,
		const struct timespec *	t
	)

Update variables

Call this function once at the end of the calculation cycle to update variables

Parameters

pdtask	Handle to pdtask
t	Current model time. If NULL, zero is assumed

Examples:: example-st.c.

◆ pdserv_update_statistics()

PDSERV_EXPORT void pdserv_update_statistics	(	struct pdtask *	pdtask,
		double	exec_time,
		double	cycle_time,
		unsigned int	overrun
	)

Update task statistics variables

Call this function at the end of the calculation cycle just before pdserv_update() to update statistics

Parameters

pdtask	Handle to pdtask
exec_time	Execution time in [s]
cycle_time	Time since last call
overrun	total overrun count

Examples:: example-st.c.

Macros

Typedefs

Functions

Variables

Typedef Documentation

◆ gettime_t

◆ write_parameter_t

Function Documentation

◆ pdserv_compound_add_field()

◆ pdserv_config_file()

◆ pdserv_create()

◆ pdserv_create_compound()

◆ pdserv_create_task()

◆ pdserv_event()

◆ pdserv_event_reset()

◆ pdserv_event_set()

◆ pdserv_event_set_all()

◆ pdserv_event_set_text()

◆ pdserv_exit()

◆ pdserv_get_variable_path()

◆ pdserv_parameter()

◆ pdserv_prepare()

◆ pdserv_set_alias()

◆ pdserv_set_comment()

◆ pdserv_set_parameter_writelock_cb()

◆ pdserv_set_signal_readlock_cb()

◆ pdserv_set_unit()

◆ pdserv_signal()

◆ pdserv_update()

◆ pdserv_update_statistics()