Code annotation

The code annotation API is the main interface to use in the code. More...

Enumerations
enum	PDI_inout_t {   integer,   PDI_NONE,   PDI_IN,   PDI_OUT,   PDI_NONE = 0,   PDI_IN = 1,   PDI_OUT = 2,   PDI_INOUT = 3 }
	Access directions. More...

Functions
PDI_status_t	PDI_share (const char *name, void *data, PDI_inout_t access)
	Shares some data with PDI. More...
PDI_status_t	PDI_access (const char *name, void **buffer, PDI_inout_t inout)
	Requests for PDI to access a data buffer. More...
PDI_status_t	PDI_release (const char *name)
	Releases ownership of a data shared with PDI. More...
PDI_status_t	PDI_reclaim (const char *name)
	Reclaims ownership of a data buffer shared with PDI. More...
PDI_status_t	PDI_event (const char *event)
	Triggers a PDI "event". More...
PDI_status_t	PDI_expose (const char *name, void *data, PDI_inout_t access)
	Shortly exposes some data to PDI. More...
PDI_status_t	PDI_multi_expose (const char *event_name, const char *name, void *data, PDI_inout_t access,...)
	Performs multiple exposes at once. More...

Detailed Description

The code annotation API is the main interface to use in the code.

It offers functions that can be called from code with no side effect by default and that can therefore be considered as annotations.

Enumeration Type Documentation

PDI_inout_t

enum PDI_inout_t

Access directions.

Enumerator
integer
PDI_NONE
PDI_IN
PDI_OUT
PDI_NONE	No data transfert.
PDI_IN	data tranfer from PDI to the main code
PDI_OUT	data transfer from the main code to PDI
PDI_INOUT	data transfer in both direction

Function Documentation

PDI_share()

PDI_status_t PDI_share	(	const char *	name,
		void *	data,
		PDI_inout_t	access
	)

Shares some data with PDI.

The user code should not modify it before a call to either PDI_release or PDI_reclaim.

Parameters

[in]	name	the data name
[in,out]	data	the accessed data
[in]	access	whether the data can be accessed for read or write by PDI

Returns

an error status

Precondition

the user code owns the data buffer

Postcondition

ownership of the data buffer is shared between PDI and the user code

the access parameter is a binary OR of PDI_IN & PDI_OUT.

• PDI_IN means PDI can set the buffer content
• PDI_OUT means the buffer contains data that can be accessed by PDI

PDI_access()

PDI_status_t PDI_access	(	const char *	name,
		void **	buffer,
		PDI_inout_t	inout
	)

Requests for PDI to access a data buffer.

Parameters

[in]	name	the data name
[in,out]	buffer	a pointer to the accessed data buffer
[in]	inout	the access properties (PDI_IN, PDI_OUT, PDI_INOUT)

Returns

an error status

Precondition

PDI owns the data buffer

Postcondition

ownership of the data buffer is shared between PDI and the user code

PDI_release()

PDI_status_t PDI_release

(

const char *

name

)

Releases ownership of a data shared with PDI.

PDI is then responsible to free the associated memory whenever necessary.

Parameters

[in]

name

name of the data to release

Returns

an error status

Precondition

ownership of the data buffer is shared between PDI and the user code

PDI owns the data buffer

PDI_reclaim()

PDI_status_t PDI_reclaim

(

const char *

name

)

Reclaims ownership of a data buffer shared with PDI.

PDI does not manage the buffer memory anymore.

Parameters

[in]

name

name of the data to reclaim

Returns

an error status

Precondition

ownership of the data buffer is shared between PDI and the user code

Postcondition

the user code owns the data buffer

PDI_event()

PDI_status_t PDI_event

(

const char *

event

)

Triggers a PDI "event".

Parameters

[in]

event

the event name

Returns

an error status

PDI_expose()

PDI_status_t PDI_expose	(	const char *	name,
		void *	data,
		PDI_inout_t	access
	)

Shortly exposes some data to PDI.

Equivalent to PDI_share + PDI_reclaim.

Parameters

[in]	name	the data name
[in]	data	the exposed data
[in]	access	whether the data can be accessed for read or write by PDI

Returns

an error status

PDI_multi_expose()

PDI_status_t PDI_multi_expose	(	const char *	event_name,
		const char *	name,
		void *	data,
		PDI_inout_t	access,
			...
	)

Performs multiple exposes at once.

All the data is shared in order they were specified and reclaimed in reversed order after an event is triggered.

NULL argument indicates an end of the list.

Parameters

[in]	event_name	the name of the event that will be triggered when all data become available
[in]	name	the data name
[in]	data	the exposed data
[in]	access	whether the data can be accessed for read or write by PDI
[in]	...	(additional arguments) additional list of data to expose, each should contain name, data and access, NULL argument inidactes an end of the list.

Returns

an error status