429 lines
14 KiB
C
429 lines
14 KiB
C
|
#ifndef GS_PARAM_TABLE_H
|
||
|
|
#define GS_PARAM_TABLE_H
|
||
|
|
/* Copyright (c) 2013-2018 GomSpace A/S. All rights reserved. */
|
||
|
|
/**
|
||
|
|
@file
|
||
|
|
|
||
|
|
Client table API.
|
||
|
|
*/
|
||
|
|
|
||
|
|
#include <gs/param/types.h>
|
||
|
|
#include <gs/util/stdio.h>
|
||
|
|
|
||
|
|
#ifdef __cplusplus
|
||
|
|
extern "C" {
|
||
|
|
#endif
|
||
|
|
|
||
|
|
/**
|
||
|
|
Allocate table memory when creating a table.
|
||
|
|
|
||
|
|
Flags must be in range: bit 16 - 23, to avoid clash with other parts of the parameter system.
|
||
|
|
*/
|
||
|
|
#define GS_PARAM_TABLE_F_ALLOC_MEMORY 0x0100
|
||
|
|
/**
|
||
|
|
Allocate table rows.
|
||
|
|
|
||
|
|
Flags must be in range: bit 16 - 23, to avoid clash with other parts of the parameter system.
|
||
|
|
*/
|
||
|
|
#define GS_PARAM_TABLE_F_ALLOC_ROWS 0x0200
|
||
|
|
/**
|
||
|
|
Disable table locking.
|
||
|
|
|
||
|
|
Flags must be in range: bit 16 - 23, to avoid clash with other parts of the parameter system.
|
||
|
|
*/
|
||
|
|
#define GS_PARAM_TABLE_F_NO_LOCK 0x0400
|
||
|
|
|
||
|
|
/**
|
||
|
|
Calculate memory size based on table rows.
|
||
|
|
|
||
|
|
@param[in] rows rows
|
||
|
|
@param[in] row_count row count.
|
||
|
|
@return size of table or 0 in case of invalid arguments.
|
||
|
|
*/
|
||
|
|
size_t gs_param_calc_table_size(const gs_param_table_row_t * rows, size_t row_count);
|
||
|
|
|
||
|
|
/**
|
||
|
|
Return size of table instance.
|
||
|
|
*/
|
||
|
|
size_t gs_param_table_instance_size(void);
|
||
|
|
|
||
|
|
/**
|
||
|
|
Clear (and check size) of memory for table instance.
|
||
|
|
|
||
|
|
@param[in] var user allocated space of at least gs_param_table_instance_size() bytes.
|
||
|
|
@param[in] var_size of \a var.
|
||
|
|
@return table instance
|
||
|
|
@see gs_param_table_instance_size()
|
||
|
|
@see #GS_PARAM_TINST_VAR
|
||
|
|
*/
|
||
|
|
gs_param_table_instance_t * gs_param_table_instance_clear(void * var, size_t var_size);
|
||
|
|
|
||
|
|
/**
|
||
|
|
Allocates aligned space on the stack for a table instance structure.
|
||
|
|
@param[in] var name of table instsance variable.
|
||
|
|
*/
|
||
|
|
#define GS_PARAM_TINST_VAR(var) uint8_t var##__data [gs_param_table_instance_size()] __attribute__ ((aligned(4))); gs_param_table_instance_t * var = gs_param_table_instance_clear(var##__data, sizeof(var##__data))
|
||
|
|
|
||
|
|
/**
|
||
|
|
Allocate memory for table instance.
|
||
|
|
|
||
|
|
Use gs_param_table_free() to free any internal resources.
|
||
|
|
|
||
|
|
Use standard free() to free allocated memory.
|
||
|
|
|
||
|
|
@return table instance on success, otherwise NULL.
|
||
|
|
*/
|
||
|
|
gs_param_table_instance_t * gs_param_table_instance_alloc(void);
|
||
|
|
|
||
|
|
/**
|
||
|
|
Find row by name.
|
||
|
|
|
||
|
|
@param[in] name parameter name.
|
||
|
|
@param[in] rows rows
|
||
|
|
@param[in] row_count row count.
|
||
|
|
@return row or NULL if not found.
|
||
|
|
*/
|
||
|
|
const gs_param_table_row_t * gs_param_row_by_name(const char * name, const gs_param_table_row_t * rows, size_t row_count);
|
||
|
|
|
||
|
|
/**
|
||
|
|
Find row by address.
|
||
|
|
|
||
|
|
@param[in] addr parameter address.
|
||
|
|
@param[in] rows rows
|
||
|
|
@param[in] row_count row count.
|
||
|
|
@return row or NULL if not found.
|
||
|
|
*/
|
||
|
|
const gs_param_table_row_t * gs_param_row_by_address(uint16_t addr, const gs_param_table_row_t * rows, size_t row_count);
|
||
|
|
|
||
|
|
/**
|
||
|
|
Return table memory.
|
||
|
|
|
||
|
|
@note handle with care - any read/write should be atomic to prevent inconsistent data.
|
||
|
|
|
||
|
|
@param[in] tinst table instance
|
||
|
|
@param[out] return_size if not NULL, the memory size is returned.
|
||
|
|
@return pointer to the table's data memory.
|
||
|
|
*/
|
||
|
|
void * gs_param_table_get_memory(gs_param_table_instance_t * tinst, size_t * return_size);
|
||
|
|
|
||
|
|
/**
|
||
|
|
Return table rows.
|
||
|
|
|
||
|
|
@param[in] tinst table instance
|
||
|
|
@param[out] return_count if not NULL, the row count is returned.
|
||
|
|
@return pointer to the table rows.
|
||
|
|
*/
|
||
|
|
const gs_param_table_row_t * gs_param_table_get_rows(gs_param_table_instance_t * tinst, size_t * return_count);
|
||
|
|
|
||
|
|
/**
|
||
|
|
Lock table (recursive).
|
||
|
|
|
||
|
|
@param[in] tinst table instance
|
||
|
|
@return_gs_error_t
|
||
|
|
*/
|
||
|
|
gs_error_t gs_param_table_lock(gs_param_table_instance_t * tinst);
|
||
|
|
|
||
|
|
/**
|
||
|
|
Unlock table.
|
||
|
|
|
||
|
|
Unlock must be called once for every time gs_param_table_lock() has been called.
|
||
|
|
|
||
|
|
@param[in] tinst table instance
|
||
|
|
@return_gs_error_t
|
||
|
|
*/
|
||
|
|
gs_error_t gs_param_table_unlock(gs_param_table_instance_t * tinst);
|
||
|
|
|
||
|
|
/**
|
||
|
|
Free internal resources and clears instance.
|
||
|
|
|
||
|
|
@param[in] tinst table instance
|
||
|
|
@return_gs_error_t
|
||
|
|
*/
|
||
|
|
gs_error_t gs_param_table_free(gs_param_table_instance_t * tinst);
|
||
|
|
|
||
|
|
/**
|
||
|
|
Print a single parameter on stream.
|
||
|
|
|
||
|
|
@param[in] tinst table instanc.
|
||
|
|
@param[in] row row to print.
|
||
|
|
@param[in] list_data \a true includes parameter value.
|
||
|
|
@param[in] flags flags to control output format: #GS_PARAM_F_SHOW_SCIENTIFIC, #GS_PARAM_F_SHOW_HEX.
|
||
|
|
@param[in] out output stream.
|
||
|
|
@return_gs_error_t
|
||
|
|
*/
|
||
|
|
gs_error_t gs_param_list_single_to_stream(gs_param_table_instance_t * tinst, const gs_param_table_row_t * row, bool list_data, uint32_t flags, FILE * out);
|
||
|
|
|
||
|
|
/**
|
||
|
|
Print a single parameter on stdout.
|
||
|
|
|
||
|
|
@param[in] tinst table instanc.
|
||
|
|
@param[in] row row to print.
|
||
|
|
@param[in] list_data \a true includes parameter value.
|
||
|
|
@return_gs_error_t
|
||
|
|
*/
|
||
|
|
static inline gs_error_t gs_param_list_single(gs_param_table_instance_t * tinst, const gs_param_table_row_t * row, bool list_data)
|
||
|
|
{
|
||
|
|
return gs_param_list_single_to_stream(tinst, row, list_data, 0, stdout);
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
Print entire table on stream.
|
||
|
|
|
||
|
|
@param[in] tinst table instanc.
|
||
|
|
@param[in] list_data \a true includes parameter value.
|
||
|
|
@param[in] flags flags to control output format: #GS_PARAM_F_SHOW_SCIENTIFIC, #GS_PARAM_F_SHOW_HEX.
|
||
|
|
@param[in] out output stream.
|
||
|
|
@return_gs_error_t
|
||
|
|
*/
|
||
|
|
gs_error_t gs_param_list_to_stream(gs_param_table_instance_t * tinst, bool list_data, uint32_t flags, FILE * out);
|
||
|
|
|
||
|
|
/**
|
||
|
|
Print entire table on stdout.
|
||
|
|
|
||
|
|
@param[in] tinst table instanc.
|
||
|
|
@param[in] list_data \a true includes parameter value.
|
||
|
|
@return_gs_error_t
|
||
|
|
*/
|
||
|
|
static inline gs_error_t gs_param_list(gs_param_table_instance_t * tinst, bool list_data)
|
||
|
|
{
|
||
|
|
return gs_param_list_to_stream(tinst, list_data, 0, stdout);
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
Convert string to parameter.
|
||
|
|
|
||
|
|
@param[in] row row defining the parameter to convert.
|
||
|
|
@param[in] string string to convert.
|
||
|
|
@param[out] return_value user supplied buffer for returning the value - must be at least the size specified in \a row
|
||
|
|
@return_gs_error_t
|
||
|
|
*/
|
||
|
|
gs_error_t gs_param_from_string(const gs_param_table_row_t * row, const char * string, void * return_value);
|
||
|
|
|
||
|
|
/**
|
||
|
|
Convert parameter to string.
|
||
|
|
|
||
|
|
@param[in] row row defining the parameter to convert.
|
||
|
|
@param[in] value parameter value to convert.
|
||
|
|
@param[in] with_type \a true includes data type.
|
||
|
|
@param[in] flags flags to control output format: #GS_PARAM_F_SHOW_SCIENTIFIC, #GS_PARAM_F_SHOW_HEX.
|
||
|
|
@param[out] buf user supplied buffer of \a buf_size bytes.
|
||
|
|
@param[in] buf_size size of \a buf in bytes.
|
||
|
|
@param[in] buf_pos buffer position to insert string.
|
||
|
|
@param[out] return_buf_written number of bytes written to \a buf.
|
||
|
|
@return_gs_error_t
|
||
|
|
*/
|
||
|
|
gs_error_t gs_param_to_string2(const gs_param_table_row_t * row, const void * value, bool with_type, uint32_t flags, char * buf, unsigned int buf_size, unsigned int buf_pos, unsigned int * return_buf_written);
|
||
|
|
|
||
|
|
/**
|
||
|
|
Convert parameter to string.
|
||
|
|
|
||
|
|
@param[in] row row defining the parameter to convert.
|
||
|
|
@param[in] value parameter value to convert.
|
||
|
|
@param[in] with_type \a true includes data type.
|
||
|
|
@param[out] buf user supplied buffer of \a buf_size bytes.
|
||
|
|
@param[in] buf_size size of \a buf in bytes.
|
||
|
|
@param[in] buf_pos buffer position to insert string.
|
||
|
|
@param[out] return_buf_written number of bytes written to \a buf.
|
||
|
|
@return_gs_error_t
|
||
|
|
*/
|
||
|
|
static inline gs_error_t gs_param_to_string(const gs_param_table_row_t * row, const void * value, bool with_type, char * buf, unsigned int buf_size, unsigned int buf_pos, unsigned int * return_buf_written)
|
||
|
|
{
|
||
|
|
return gs_param_to_string2(row, value, with_type, 0, buf, buf_size, buf_pos, return_buf_written);
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
Convert parameter type to string.
|
||
|
|
|
||
|
|
@param[in] type parameter type.
|
||
|
|
@return pointer to a static string.
|
||
|
|
*/
|
||
|
|
const char * gs_param_type_to_string(gs_param_type_t type);
|
||
|
|
|
||
|
|
/**
|
||
|
|
Return size of parameter type.
|
||
|
|
|
||
|
|
@param[in] type parameter type.
|
||
|
|
@return size of parameter type in bytes.
|
||
|
|
*/
|
||
|
|
uint8_t gs_param_type_size(gs_param_type_t type);
|
||
|
|
|
||
|
|
/**
|
||
|
|
Get table checksum - little-endian.
|
||
|
|
@note Use/exchange gs_param_table_checksum_be(), as this is calculated the same on all platforms.
|
||
|
|
@param[in] tinst table instance.
|
||
|
|
@returns 16-bit fletcher checksum
|
||
|
|
*/
|
||
|
|
uint16_t gs_param_table_checksum_le(gs_param_table_instance_t * tinst);
|
||
|
|
|
||
|
|
/**
|
||
|
|
Get table checksum - big-endian/network-order (prefered).
|
||
|
|
@param[in] tinst table instance.
|
||
|
|
@returns 16-bit fletcher checksum
|
||
|
|
*/
|
||
|
|
uint16_t gs_param_table_checksum_be(gs_param_table_instance_t * tinst);
|
||
|
|
|
||
|
|
/**
|
||
|
|
Get table checksum - host-order (not cross-platform).
|
||
|
|
@deprecated use gs_param_table_checksum_be()
|
||
|
|
@param[in] tinst table instance.
|
||
|
|
@returns 16-bit fletcher checksum
|
||
|
|
*/
|
||
|
|
uint16_t gs_param_table_checksum(gs_param_table_instance_t * tinst);
|
||
|
|
|
||
|
|
/**
|
||
|
|
Get table checksum - big-endian.
|
||
|
|
@deprecated use gs_param_table_checksum_be()
|
||
|
|
@param[in] tinst table instance.
|
||
|
|
@returns 16-bit fletcher checksum
|
||
|
|
*/
|
||
|
|
static inline uint16_t gs_param_table_checksum2(gs_param_table_instance_t * tinst)
|
||
|
|
{
|
||
|
|
return gs_param_table_checksum_be(tinst);
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
Get/read parameter from table.
|
||
|
|
|
||
|
|
@param[in] tinst table instanc.
|
||
|
|
@param[in] addr parameter address (offset in table).
|
||
|
|
@param[in] type parameter type.
|
||
|
|
@param[out] return_value value of parameter - user supplied memory of at least \a size size.
|
||
|
|
@param[in] size number of bytes to get/read - must match \a type, e.g. 4 bytes for an uint32_t.
|
||
|
|
@param[in] flags flags.
|
||
|
|
@return_gs_error_t
|
||
|
|
*/
|
||
|
|
gs_error_t gs_param_get(gs_param_table_instance_t * tinst, uint16_t addr, gs_param_type_t type, void * return_value, size_t size, uint32_t flags);
|
||
|
|
|
||
|
|
/**
|
||
|
|
Set/write parameter in table.
|
||
|
|
|
||
|
|
@param[in] tinst table instanc.
|
||
|
|
@param[in] addr parameter address (offset in table).
|
||
|
|
@param[in] type parameter type.
|
||
|
|
@param[in] value value of parameter.
|
||
|
|
@param[in] size number of bytes to set/write - must match \a type, e.g. 4 bytes for an uint32_t.
|
||
|
|
@param[in] flags flags.
|
||
|
|
@return_gs_error_t
|
||
|
|
*/
|
||
|
|
gs_error_t gs_param_set(gs_param_table_instance_t * tinst, uint16_t addr, gs_param_type_t type, const void * value, size_t size, uint32_t flags);
|
||
|
|
|
||
|
|
/**
|
||
|
|
Get string parameter.
|
||
|
|
|
||
|
|
@param[in] tinst table instanc.
|
||
|
|
@param[in] addr parameter address (offset in table).
|
||
|
|
@param[out] buf value of parameter - user supplied memory of at least parameter size + 1 to hold NUL termination.
|
||
|
|
@param[in] buf_size size of \a buf - ensure room for NUL termination.
|
||
|
|
@param[in] flags flags.
|
||
|
|
@return GS_ERROR_OVERFLOW if string + NUL termination exceeds \a buf_size.
|
||
|
|
@return_gs_error_t
|
||
|
|
*/
|
||
|
|
gs_error_t gs_param_get_string(gs_param_table_instance_t * tinst, uint16_t addr, char * buf, size_t buf_size, uint32_t flags);
|
||
|
|
|
||
|
|
/**
|
||
|
|
Set string parameter.
|
||
|
|
|
||
|
|
@param[in] tinst table.
|
||
|
|
@param[in] addr parameter address (offset in table).
|
||
|
|
@param[in] value string to save - parameter must be able to hold string + NUL termination.
|
||
|
|
@param[in] flags flags.
|
||
|
|
@return GS_ERROR_OVERFLOW if string + NUL termination exceeds parameter size.
|
||
|
|
@return_gs_error_t
|
||
|
|
*/
|
||
|
|
gs_error_t gs_param_set_string(gs_param_table_instance_t * tinst, uint16_t addr, const char * value, uint32_t flags);
|
||
|
|
|
||
|
|
/**
|
||
|
|
Get data parameter.
|
||
|
|
|
||
|
|
@param[in] tinst table instanc.
|
||
|
|
@param[in] addr parameter address (offset in table).
|
||
|
|
@param[out] buf value of parameter - user supplied memory of at least parameter size.
|
||
|
|
@param[in] buf_size size of \a buf.
|
||
|
|
@param[in] flags flags.
|
||
|
|
@return GS_ERROR_OVERFLOW if parameter size is greater than \a buf_size.
|
||
|
|
@return_gs_error_t
|
||
|
|
*/
|
||
|
|
gs_error_t gs_param_get_data(gs_param_table_instance_t * tinst, uint16_t addr, void * buf, size_t buf_size, uint32_t flags);
|
||
|
|
|
||
|
|
/**
|
||
|
|
Set data parameter.
|
||
|
|
|
||
|
|
@param[in] tinst table instanc.
|
||
|
|
@param[in] addr parameter address (offset in table).
|
||
|
|
@param[in] value value of parameter.
|
||
|
|
@param[in] value_size size of \a value.
|
||
|
|
@param[in] flags flags.
|
||
|
|
@return GS_ERROR_OVERFLOW if parameter size is greater than \a buf_size.
|
||
|
|
@return_gs_error_t
|
||
|
|
*/
|
||
|
|
gs_error_t gs_param_set_data(gs_param_table_instance_t * tinst, uint16_t addr, const void * value, size_t value_size, uint32_t flags);
|
||
|
|
|
||
|
|
/**
|
||
|
|
Macro for expanding get/set functions.
|
||
|
|
@param[in] name function suffix name.
|
||
|
|
@param[in] native_type native type
|
||
|
|
@param[in] param_type parameter type
|
||
|
|
*/
|
||
|
|
#define GS_PARAM_PASTE(name, native_type, param_type) \
|
||
|
|
static inline gs_error_t gs_param_get_##name(gs_param_table_instance_t * tinst, uint16_t addr, native_type * buf, uint32_t flags) { \
|
||
|
|
return gs_param_get(tinst, addr, param_type, buf, sizeof(*buf), flags); \
|
||
|
|
} \
|
||
|
|
static inline native_type gs_param_get_##name##_nc(gs_param_table_instance_t * tinst, uint16_t addr, uint32_t flags) { \
|
||
|
|
native_type value = 0; \
|
||
|
|
gs_param_get(tinst, addr, param_type, &value, sizeof(value), flags); \
|
||
|
|
return value; \
|
||
|
|
} \
|
||
|
|
static inline gs_error_t gs_param_set_##name(gs_param_table_instance_t * tinst, uint16_t addr, native_type value, uint32_t flags) { \
|
||
|
|
return gs_param_set(tinst, addr, param_type, &value, sizeof(value), flags); \
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
Get/set boolean.
|
||
|
|
*/
|
||
|
|
GS_PARAM_PASTE(bool, bool, GS_PARAM_BOOL)
|
||
|
|
/**
|
||
|
|
Get/set uint8.
|
||
|
|
*/
|
||
|
|
GS_PARAM_PASTE(uint8, uint8_t, GS_PARAM_UINT8)
|
||
|
|
/**
|
||
|
|
Get/set uint16.
|
||
|
|
*/
|
||
|
|
GS_PARAM_PASTE(uint16, uint16_t, GS_PARAM_UINT16)
|
||
|
|
/**
|
||
|
|
Get/set uint32.
|
||
|
|
*/
|
||
|
|
GS_PARAM_PASTE(uint32, uint32_t, GS_PARAM_UINT32)
|
||
|
|
/**
|
||
|
|
Get/set uint64.
|
||
|
|
*/
|
||
|
|
GS_PARAM_PASTE(uint64, uint64_t, GS_PARAM_UINT64)
|
||
|
|
/**
|
||
|
|
Get/set int8.
|
||
|
|
*/
|
||
|
|
GS_PARAM_PASTE(int8, int8_t, GS_PARAM_INT8)
|
||
|
|
/**
|
||
|
|
Get/set int16.
|
||
|
|
*/
|
||
|
|
GS_PARAM_PASTE(int16, int16_t, GS_PARAM_INT16)
|
||
|
|
/**
|
||
|
|
Get/set int32.
|
||
|
|
*/
|
||
|
|
GS_PARAM_PASTE(int32, int32_t, GS_PARAM_INT32)
|
||
|
|
/**
|
||
|
|
Get/set int64.
|
||
|
|
*/
|
||
|
|
GS_PARAM_PASTE(int64, int64_t, GS_PARAM_INT64)
|
||
|
|
/**
|
||
|
|
Get/set double.
|
||
|
|
*/
|
||
|
|
GS_PARAM_PASTE(double, double, GS_PARAM_DOUBLE)
|
||
|
|
/**
|
||
|
|
Get/set float.
|
||
|
|
*/
|
||
|
|
GS_PARAM_PASTE(float, float, GS_PARAM_FLOAT)
|
||
|
|
|
||
|
|
#ifdef __cplusplus
|
||
|
|
}
|
||
|
|
#endif
|
||
|
|
#endif
|