Library API#

Library to access telemetry sections.

For further information, the source code is available here.

Here are the objects and functions provided.

Enumerations#

enum tlm_var_type#

Type of variables

Values:

enumerator TLM_TYPE_INVALID#

enumerator TLM_TYPE_BOOL#: Boolean value 8-bit

enumerator TLM_TYPE_UINT8#: 8-bit unsigned value

enumerator TLM_TYPE_INT8#: 8-bit signed value

enumerator TLM_TYPE_UINT16#: 16-bit unsigned value

enumerator TLM_TYPE_INT16#: 16-bit signed value

enumerator TLM_TYPE_UINT32#: 32-bit unsigned value

enumerator TLM_TYPE_INT32#: 32-bit signed value

enumerator TLM_TYPE_UINT64#: 64-bit unsigned value

enumerator TLM_TYPE_INT64#: 64-bit signed value

enumerator TLM_TYPE_FLOAT32#: 32-bit float value

enumerator TLM_TYPE_FLOAT64#: 64-bit float (double) value

enumerator TLM_TYPE_STRING#: Character string (fixed-size array of char)

enumerator TLM_TYPE_BINARY#: Binary data (fixed-size array of u8)

enumerator TLM_TYPE_STRUCT#: Complexe structure

enumerator TLM_TYPE_COUNT#: Last entry corresponds to number of entries

enum tlm_method#

Query method

Values:

enumerator TLM_LATEST#: Get last sample (timestamp of query unused)

enumerator TLM_CLOSEST#: Get closest sample to a given timestamp

enumerator TLM_FIRST_AFTER#: Get closest sample AFTER given timestamp

enumerator TLM_FIRST_BEFORE#: Get closest sample BEFORE given timestamp

enumerator TLM_OLDEST#: Get oldest sample (query timestamp unused)

enumerator TLM_STRICTLY_AFTER#: Get closest sample STRICTLY AFTER ts

enumerator TLM_STRICTLY_BEFORE#: Get closest sample STRICTLY BEFORE ts

Structures#

struct tlm_producer_reg_entry#

Producer registration entry

Public Members

void *ptr#: Pointer to data, shall be valid during the lifetime of the producer

const char *name#: Name of the variable (excluding the section name)

enum tlm_var_type type#: Type of data produced

size_t size#: Size of a single data element

size_t count#: Number of elements (> 1 in the case of arrays)

uint32_t flags#: Flags for registration

struct tlm_consumer_reg_entry#

Consumer registration entry

Public Members

void *ptr#: Pointer to data, shall be valid during the lifetime of the consumer

const char *name#: Name of the variable (including the section name)

enum tlm_var_type type#: Type of data

size_t size#: Size of one element of data

size_t count#: Number of elements (> 1 for arrays)

struct timespec *timestamp#: Optional pointer to a timestamp to be filled during ‘get’ methods

struct tlm_reg_field#

Field registration structure

Public Members

size_t off#: Offset of the field in the parent structure

const char *name#: Name of the field

enum tlm_var_type type#: Type of the field

size_t size#: Size of a single element

size_t count#: Number of elements (> 1 in the case of arrays)

uint32_t flags#: Additional flags

const struct tlm_reg_struct *desc#: Sub-structure description if type is TLM_TYPE_STRUCT

struct tlm_reg_struct#

Structure registration structure

Public Members

const char *name#: Name of the structure (informative, not used in telemetry section)

size_t count#: Number of fields in the structure

const struct tlm_reg_field *fields#: Array of field description

Functions#

struct tlm_producer *tlm_producer_new(const char *section, uint32_t maxsamples, uint32_t rate)#

Create a new producer.

Remark

a YAML alias map file can be set in environment variable ‘TLM_ALIAS_MAP_FILE’

Parameters:

section – name of the producer (section).
maxsamples – Maximum number of samples.
rate – Approximative rate of samples (in us).

Returns:

created producer or NULL in case of error.

int tlm_producer_destroy(struct tlm_producer *producer)#

Destroy a producer.

Parameters:: producer – producer to destroy.
Returns:: 0 in case of success, negative errno value in case of error.

int tlm_producer_reg(struct tlm_producer *producer, void *ptr, const char *name, enum tlm_var_type type, size_t size, size_t count, uint32_t flags)#

Parameters:

producer – producer object.
ptr – pointer to variable.
name – name of variable.
type – type of variable.
size – size of variable.
count – number of variables for arrays.
flags – flags for the variable.

Returns:

0 in case of success, negative errno value in case of error.

int tlm_producer_reg_array(struct tlm_producer *producer, const struct tlm_producer_reg_entry *entries, size_t count)#

Parameters:

producer – producer object.
entries – array of entries.
count – number of entries.

Returns:

0 in case of success, negative errno value in case of error.

int tlm_producer_reg_struct_ptr(struct tlm_producer *producer, const void *ptr, const char *name, const struct tlm_reg_struct *desc)#

Parameters:

producer – producer object.
ptr – pointer to the base of the structure. Its scope should be valid until the producer is destroyed because ‘tlm_put_sample’ will implicitly dereference it.
name – optional name to prefix to all fields. Useful when registering multiple descriptions. The same behaviour can be achieved by creating a top level structure description and calling this function just once.
desc – description of the structure.

Returns:

0 in case of success, negative errno value in case of error.

int tlm_producer_reg_complete(struct tlm_producer *producer)#

Complete registration of variables. Must be called after all variables have been registered.

Parameters:: producer – producer object.
Returns:: 0 in case of success, negative errno value in case of error.

int tlm_producer_put_sample(struct tlm_producer *producer, const struct timespec *timestamp)#

Put a new sample.

Parameters:

producer – producer object.
timestamp – timestamp of new sample or NULL to use current time.

Returns:

0 in case of success, negative errno value in case of error.

struct tlm_consumer *tlm_consumer_new(void)#

Create a new consumer.

Remark

a YAML alias map file can be set in environment variable ‘TLM_ALIAS_MAP_FILE’

Returns:: created consumer or NULL in case of error.

int tlm_consumer_destroy(struct tlm_consumer *consumer)#

Destroy a consumer.

Parameters:: consumer – consumer to destroy.
Returns:: 0 in case of success, negative errno value in case of error.

int tlm_consumer_reg(struct tlm_consumer *consumer, void *ptr, const char *name, enum tlm_var_type type, size_t size, size_t count, struct timespec *timestamp)#

Parameters:

consumer – consumer object.
ptr – pointer to variable.
name – name of variable.
type – type of variable.
size – size of variable.
count – number of variables for arrays.
timestamp – structure where to store timestamp of samples.

Returns:

0 in case of success, negative errno value in case of error.

int tlm_consumer_reg_array(struct tlm_consumer *consumer, const struct tlm_consumer_reg_entry *entries, size_t count)#

Parameters:

consumer – consumer object.
entries – array of entries.
count – number of entries.

Returns:

0 in case of success, negative errno value in case of error.

int tlm_consumer_reg_struct_ptr(struct tlm_consumer *consumer, const void *ptr, const char *name, const struct tlm_reg_struct *desc)#

Register variables using a recursive structure description and a pointer to the base of the structure. Internally, the description will be analyzed and variables automatically registered with the given pointer as base. Fields can contain the flag ‘TLM_FLAG_POINTER’ to construct complex opaque structures. Note this takes a struct tlm_reg_struct, without timestamp. If you need the timestamps, you should register only variables from the same section and use tlm_consumer_get_sample_with_timestamp

Parameters:

consumer – consumer object.
ptr – pointer to the base of the structure. Its scope should be valid until the consumer is destroyed because ‘tlm_get_sample’ will implicitly dereference it.
name – optional name to prefix to all fields. Useful when registering multiple descriptions. The same behaviour can be achieved by creating a top level structure description and calling this function just once.
desc – description of the structure.

Returns:

0 in case of success, negative errno value in case of error.

int tlm_consumer_reg_complete(struct tlm_consumer *consumer)#

Complete the registration of variables.

Parameters:: consumer – consumer object.
Returns:: 0 in case of success, negative errno value in case of error.

int tlm_consumer_get_sample(struct tlm_consumer *consumer, const struct timespec *timestamp, enum tlm_method method)#

Get a sample.

Remark

-ENOENT is returned if no samples where retrieved.

Parameters:

consumer – consumer object.
timestamp – timestamp of query (can be NULL for LATEST method).
method – method of query.

Returns:

0 if at least one sample has been read in one of the shared memory where variables are, negative errno value in case of error.

int tlm_consumer_timestamp_is_valid(struct timespec *timestamp)#

Check the validity of the timestamp.

Parameters:: timestamp – timestamp.
Returns:: 0 if the timestamp is not valid.