# Property Client Library

The Satlab property library provides remote access to system properties. The Client Interface provides simple functions for accessing single properties, while the Query Interface allows multiple values to be read or modified in a single transaction.

## Client Interface

This file defines the main functions for accessing properties on remote systems.

Properties are identified using a 16-bit ID, with 5 bits for group and 7 bits for property in that group. The remaining 4 bits encode the type. Groups are identified with a similar ID, but with the type and property bits set to zero:

     0                   1
     0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    | Type  |  Group  |   Property  |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Each system client library contains a header file which defines available properties on the system, and specifies the type and name of each property.

Functions

int `sl_prop_parse_bool`(const char *string, size_t size, uint8_t *value)

  Parse string to boolean value.

  “1”, “yes”, and “true” are parsed to value=1 and “0”, “no”, and “false” are parsed to value=0. Any other value return -EINVAL and value is not changed.

  Return

    0 on success, and a negative error code on error.

  Parameters

    - `string`: Pointer to boolean string to parse.

    - `size`: Size of the value pointed to by string.

    - `value`: Parsed boolean value.

int `sl_prop_remote_get_to_string`(uint8_t node, uint32_t timeout, const struct prop_spec *spec, char *string, size_t size)

  Get remote property value to string.

  Return

    0 on success, and a negative error code on error.

  Parameters

    - `node`: CSP address of the property node.

    - `timeout`: Timeout of the command in milliseconds.

    - `spec`: Pointer to the property spec of the property to get.

    - `string`: Pointer to string buffer where the result is stored.

    - `size`: Size of the value pointed to by string.

int `sl_prop_remote_set_from_string`(uint8_t node, uint32_t timeout, const struct prop_spec *spec, const char *string, size_t size)

  Set remote property value from string.

  Return

    0 on success, and a negative error code on error.

  Parameters

    - `node`: CSP address of the property node.

    - `timeout`: Timeout of the command in milliseconds.

    - `spec`: Pointer to the property spec of the property to set.

    - `string`: Pointer to the string representation of the new property value. Must match the type of the property.

    - `size`: Size of the value pointed to by string.

int `sl_prop_remote_get`(uint8_t node, uint32_t timeout, prop_id_t id, void *value, size_t size)

  Get remote property value.

  Return

    0 on success, and a negative error code on error.

  Parameters

    - `node`: CSP address of the property node.

    - `timeout`: Timeout of the command in milliseconds.

    - `id`: ID of the property to get.

    - `value`: Pointer to the property value. Must match the type of the property.

    - `size`: Size of the value pointed to by value. Must match the property type size.

int `sl_prop_remote_set`(uint8_t node, uint32_t timeout, prop_id_t id, const void *value, size_t size)

  Set remote property value.

  Return

    0 on success, and a negative error code on error.

  Parameters

    - `node`: CSP address of the property node.

    - `timeout`: Timeout of the command in milliseconds.

    - `id`: ID of the property to set.

    - `value`: Pointer to the new property value. Must match the type of the property.

    - `size`: Size of the value pointed to by value. Must match the property type size.

int `sl_prop_remote_reset`(uint8_t node, uint32_t timeout, prop_id_t id)

  Reset remote property or group to default value.

  Return

    0 on success, and a negative error code on error.

  Parameters

    - `node`: CSP address of the property node.

    - `timeout`: Timeout of the command in milliseconds.

    - `id`: Property ID. Can be a single property or a group ID.

int `sl_prop_remote_save`(uint8_t node, uint32_t timeout, prop_id_t group, bool fallback)

  Save property group on remote system.

  If the group supports locking, it must be unlocked before calling this function.

  Warning

    Be very careful with this command. Modifying and saving certain properties, such as the CSP address, could render the system unresponsible.

  Return

    0 on success, and a negative error code on error.

  Parameters

    - `node`: CSP address of the property node.

    - `timeout`: Timeout of the command in milliseconds.

    - `group`: Property ID of the group to save

    - `fallback`: If true, the group is saved to the fallback store. Otherwise, it is saved to the boot store.

int `sl_prop_remote_load`(uint8_t node, uint32_t timeout, prop_id_t group, bool fallback)

  Load property group on remote system.

  Return

    0 on success, and a negative error code on error.

  Parameters

    - `node`: CSP address of the property node.

    - `timeout`: Timeout of the command in milliseconds.

    - `group`: Property ID of the group to load

    - `fallback`: If true, the group is loaded from the fallback store. Otherwise, it is loaded from the boot store.

int `sl_prop_remote_erase`(uint8_t node, uint32_t timeout, prop_id_t group, bool fallback)

  Erase saved property group on remote system.

  Warning

    Be very careful with this command. Modifying and saving certain properties, such as the CSP address, could render the system unresponsible.

  Return

    0 on success, and a negative error code on error.

  Parameters

    - `node`: CSP address of the property node.

    - `timeout`: Timeout of the command in milliseconds.

    - `group`: Property ID of the group to load

    - `fallback`: If true, the fallback store is erased. Otherwise, the boot store is erased.

int `sl_prop_remote_lock`(uint8_t node, uint32_t timeout, prop_id_t group, bool fallback)

  Lock property group on remote system.

  Return

    0 on success, and a negative error code on error.

  Parameters

    - `node`: CSP address of the property node.

    - `timeout`: Timeout of the command in milliseconds.

    - `group`: Property ID of the group to load

    - `fallback`: If true, the fallback store is locked. Otherwise, the boot store is lock.

int `sl_prop_remote_unlock`(uint8_t node, uint32_t timeout, prop_id_t group, bool fallback)

  Unlock property group on remote system.

  Warning

    Be very careful with this command. Modifying and saving certain properties, such as the CSP address, could render the system unresponsible.

  Return

    0 on success, and a negative error code on error.

  Parameters

    - `node`: CSP address of the property node.

    - `timeout`: Timeout of the command in milliseconds.

    - `group`: Property ID of the group to load

    - `fallback`: If true, the fallback store is unlocked. Otherwise, the boot store is unlock.

This file contains basic functions to get/set a single remote property.

They are all wrappers around sl_prop_remote_get/set, but should be used where possible because they perform compile time validation of the function arguments.

Functions

int `sl_prop_remote_set_bool`(uint8_t node, uint32_t timeout, prop_id_t id, bool val)

  Set remote boolean property.

  Return

    0 on success, and a negative error code on error.

  Parameters

    - `node`: CSP address of the property node.

    - `timeout`: Timeout of the command in milliseconds.

    - `id`: ID of remote property to set.

    - `val`: New value of remote property.

int `sl_prop_remote_get_bool`(uint8_t node, uint32_t timeout, prop_id_t id, bool *val)

  Get remote boolean property.

  Return

    0 on success, and a negative error code on error.

  Parameters

    - `node`: CSP address of the property node.

    - `timeout`: Timeout of the command in milliseconds.

    - `id`: ID of remote property to get.

    - `val`: Pointer to reply value.

int `sl_prop_remote_set_int8`(uint8_t node, uint32_t timeout, prop_id_t id, int8_t val)

  Set remote signed 8-bit property.

  Return

    0 on success, and a negative error code on error.

  Parameters

    - `node`: CSP address of the property node.

    - `timeout`: Timeout of the command in milliseconds.

    - `id`: ID of remote property to set.

    - `val`: New value of remote property.

int `sl_prop_remote_get_int8`(uint8_t node, uint32_t timeout, prop_id_t id, int8_t *val)

  Get remote signed 8-bit property.

  Return

    0 on success, and a negative error code on error.

  Parameters

    - `node`: CSP address of the property node.

    - `timeout`: Timeout of the command in milliseconds.

    - `id`: ID of remote property to get.

    - `val`: Pointer to reply value.

int `sl_prop_remote_set_int16`(uint8_t node, uint32_t timeout, prop_id_t id, int16_t val)

  Set remote signed 16-bit property.

  Return

    0 on success, and a negative error code on error.

  Parameters

    - `node`: CSP address of the property node.

    - `timeout`: Timeout of the command in milliseconds.

    - `id`: ID of remote property to set.

    - `val`: New value of remote property.

int `sl_prop_remote_get_int16`(uint8_t node, uint32_t timeout, prop_id_t id, int16_t *val)

  Get remote signed 16-bit property.

  Return

    0 on success, and a negative error code on error.

  Parameters

    - `node`: CSP address of the property node.

    - `timeout`: Timeout of the command in milliseconds.

    - `id`: ID of remote property to get.

    - `val`: Pointer to reply value.

int `sl_prop_remote_set_int32`(uint8_t node, uint32_t timeout, prop_id_t id, int32_t val)

  Set remote signed 32-bit property.

  Return

    0 on success, and a negative error code on error.

  Parameters

    - `node`: CSP address of the property node.

    - `timeout`: Timeout of the command in milliseconds.

    - `id`: ID of remote property to set.

    - `val`: New value of remote property.

int `sl_prop_remote_get_int32`(uint8_t node, uint32_t timeout, prop_id_t id, int32_t *val)

  Get remote signed 32-bit property.

  Return

    0 on success, and a negative error code on error.

  Parameters

    - `node`: CSP address of the property node.

    - `timeout`: Timeout of the command in milliseconds.

    - `id`: ID of remote property to get.

    - `val`: Pointer to reply value.

int `sl_prop_remote_set_int64`(uint8_t node, uint32_t timeout, prop_id_t id, int64_t val)

  Set remote signed 64-bit property.

  Return

    0 on success, and a negative error code on error.

  Parameters

    - `node`: CSP address of the property node.

    - `timeout`: Timeout of the command in milliseconds.

    - `id`: ID of remote property to set.

    - `val`: New value of remote property.

int `sl_prop_remote_get_int64`(uint8_t node, uint32_t timeout, prop_id_t id, int64_t *val)

  Get remote signed 64-bit property.

  Return

    0 on success, and a negative error code on error.

  Parameters

    - `node`: CSP address of the property node.

    - `timeout`: Timeout of the command in milliseconds.

    - `id`: ID of remote property to get.

    - `val`: Pointer to reply value.

int `sl_prop_remote_set_uint8`(uint8_t node, uint32_t timeout, prop_id_t id, uint8_t val)

  Set remote unsigned 8-bit property.

  Return

    0 on success, and a negative error code on error.

  Parameters

    - `node`: CSP address of the property node.

    - `timeout`: Timeout of the command in milliseconds.

    - `id`: ID of remote property to set.

    - `val`: New value of remote property.

int `sl_prop_remote_get_uint8`(uint8_t node, uint32_t timeout, prop_id_t id, uint8_t *val)

  Get remote unsigned 8-bit property.

  Return

    0 on success, and a negative error code on error.

  Parameters

    - `node`: CSP address of the property node.

    - `timeout`: Timeout of the command in milliseconds.

    - `id`: ID of remote property to get.

    - `val`: Pointer to reply value.

int `sl_prop_remote_set_uint16`(uint8_t node, uint32_t timeout, prop_id_t id, uint16_t val)

  Set remote unsigned 16-bit property.

  Return

    0 on success, and a negative error code on error.

  Parameters

    - `node`: CSP address of the property node.

    - `timeout`: Timeout of the command in milliseconds.

    - `id`: ID of remote property to set.

    - `val`: New value of remote property.

int `sl_prop_remote_get_uint16`(uint8_t node, uint32_t timeout, prop_id_t id, uint16_t *val)

  Get remote unsigned 16-bit property.

  Return

    0 on success, and a negative error code on error.

  Parameters

    - `node`: CSP address of the property node.

    - `timeout`: Timeout of the command in milliseconds.

    - `id`: ID of remote property to get.

    - `val`: Pointer to reply value.

int `sl_prop_remote_set_uint32`(uint8_t node, uint32_t timeout, prop_id_t id, uint32_t val)

  Set remote unsigned 32-bit property.

  Return

    0 on success, and a negative error code on error.

  Parameters

    - `node`: CSP address of the property node.

    - `timeout`: Timeout of the command in milliseconds.

    - `id`: ID of remote property to set.

    - `val`: New value of remote property.

int `sl_prop_remote_get_uint32`(uint8_t node, uint32_t timeout, prop_id_t id, uint32_t *val)

  Get remote unsigned 32-bit property.

  Return

    0 on success, and a negative error code on error.

  Parameters

    - `node`: CSP address of the property node.

    - `timeout`: Timeout of the command in milliseconds.

    - `id`: ID of remote property to get.

    - `val`: Pointer to reply value.

int `sl_prop_remote_set_uint64`(uint8_t node, uint32_t timeout, prop_id_t id, uint64_t val)

  Set remote unsigned 64-bit property.

  Return

    0 on success, and a negative error code on error.

  Parameters

    - `node`: CSP address of the property node.

    - `timeout`: Timeout of the command in milliseconds.

    - `id`: ID of remote property to set.

    - `val`: New value of remote property.

int `sl_prop_remote_get_uint64`(uint8_t node, uint32_t timeout, prop_id_t id, uint64_t *val)

  Get remote unsigned 64-bit property.

  Return

    0 on success, and a negative error code on error.

  Parameters

    - `node`: CSP address of the property node.

    - `timeout`: Timeout of the command in milliseconds.

    - `id`: ID of remote property to get.

    - `val`: Pointer to reply value.

int `sl_prop_remote_set_float`(uint8_t node, uint32_t timeout, prop_id_t id, float val)

  Set remote single precision floating point property.

  Return

    0 on success, and a negative error code on error.

  Parameters

    - `node`: CSP address of the property node.

    - `timeout`: Timeout of the command in milliseconds.

    - `id`: ID of remote property to set.

    - `val`: New value of remote property.

int `sl_prop_remote_get_float`(uint8_t node, uint32_t timeout, prop_id_t id, float *val)

  Get remote single preceision floating point property.

  Return

    0 on success, and a negative error code on error.

  Parameters

    - `node`: CSP address of the property node.

    - `timeout`: Timeout of the command in milliseconds.

    - `id`: ID of remote property to get.

    - `val`: Pointer to reply value.

int `sl_prop_remote_set_double`(uint8_t node, uint32_t timeout, prop_id_t id, double val)

  Set remote double precision floating point property.

  Return

    0 on success, and a negative error code on error.

  Parameters

    - `node`: CSP address of the property node.

    - `timeout`: Timeout of the command in milliseconds.

    - `id`: ID of remote property to set.

    - `val`: New value of remote property.

int `sl_prop_remote_get_double`(uint8_t node, uint32_t timeout, prop_id_t id, double *val)

  Get remote double preceision floating point property.

  Return

    0 on success, and a negative error code on error.

  Parameters

    - `node`: CSP address of the property node.

    - `timeout`: Timeout of the command in milliseconds.

    - `id`: ID of remote property to get.

    - `val`: Pointer to reply value.

int `sl_prop_remote_set_string`(uint8_t node, uint32_t timeout, prop_id_t id, const char *val, size_t size)

  Set remote string property.

  Return

    0 on success, and a negative error code on error.

  Parameters

    - `node`: CSP address of the property node.

    - `timeout`: Timeout of the command in milliseconds.

    - `id`: ID of remote property to set.

    - `val`: New value of remote property.

    - `size`: Size of value string. Must match property size.

int `sl_prop_remote_get_string`(uint8_t node, uint32_t timeout, prop_id_t id, char *val, size_t size)

  Get remote string property.

  Return

    0 on success, and a negative error code on error.

  Parameters

    - `node`: CSP address of the property node.

    - `timeout`: Timeout of the command in milliseconds.

    - `id`: ID of remote property to get.

    - `val`: Pointer to reply value.

    - `size`: Size of value string. Must match property size.

## Query Interface

The property query interface allows clients to get or set multiple properties in a single transaction.

A query is either a GET or a SET query, determined by the first call to either sl_prop_remote_query_get/set.

The code excerpt below shows an example of reading out the Polaris FPGA temperature and serial number in one query. Error handling has been omitted for clarity.

    int16_t temp;
    uint32_t serial;
    struct sl_prop_query query;
    uint8_t txbuf[128], rxbuf[128];

    // Prepare query and buffers
    sl_prop_remote_query_create_static(&query, txbuf, sizeof(txbuf), rxbuf, sizeof(rxbuf));
    sl_prop_remote_query_get(&query, SL_PL_PROP_TM_TEMP_FPGA);
    sl_prop_remote_query_get(&query, SL_PL_PROP_SYS_SERIAL);

    // Send query message
    sl_prop_remote_query_send(&query, node, timeout);

    // Read reply and free query object
    sl_prop_remote_query_get_reply(&query, SL_PL_PROP_TM_TEMP_FPGA, &temp, sizeof(temp));
    sl_prop_remote_query_get_reply(&query, SL_PL_PROP_SYS_SERIAL, &serial, sizeof(serial));
    sl_prop_remote_query_destroy(&query);

    // Show results
    printf("Serial number: %08x\n", serial);
    printf("FPGA temperature: %hd\n", temp);

Defines

`SL_PROP_QUERY_MAX_ELEMENTS`

  Maximum number of elements in a query reply.

`SL_PROP_QUERY_CHUNKSIZE_DEFAULT`

  Default number of data bytes per get/set message.

Enums

enum `sl_prop_query_type`

  Query types.

  Values:

  `SL_PROP_QUERY_UNKNOWN` = 0
  `SL_PROP_QUERY_GET` = 1
  `SL_PROP_QUERY_SET` = 2

Functions

int `sl_prop_remote_query_create`(struct sl_prop_query *query, size_t txsize, size_t rxsize)

  Create dynamically allocated property query.

  This function initializes a new query and dynamically allocates transmit and receive buffers. The rxsize argument can be set to 0 for pure ‘set’ queries.

  Return

    0 on success, negative error code otherwise.

  Parameters

    - `query`: Query to initialize.

    - `txsize`: Size of transmit buffer in bytes.

    - `rxsize`: Size of receive buffer in bytes.

int `sl_prop_remote_query_create_static`(struct sl_prop_query *query, uint8_t *txbuf, size_t txsize, uint8_t *rxbuf, size_t rxsize)

  Create statically allocated property query.

  This function initializes a new query using statically allocated transmit and receive buffers. The rxbuf and rxsize argument can be set to NULL and 0 for pure ‘set’ queries.

  Return

    0 on success, negative error code otherwise.

  Parameters

    - `query`: Query to initialize.

    - `txbuf`: Pointer to transmit buffer.

    - `txsize`: Size of txbuf in bytes.

    - `rxbuf`: Pointer to receive buffer.

    - `rxsize`: Size of receive buffer in bytes.

int `sl_prop_remote_query_reset`(struct sl_prop_query *query)

  Reset query so it can be reused.

  This function resets a query without the need to reallocate buffers. This allows the query to be reused multiple times.

  Return

    0 on success, negative error code otherwise.

  Parameters

    - `query`: Query to reset.

int `sl_prop_remote_query_destroy`(struct sl_prop_query *query)

  Free memory allocated for query.

  Destroy query and free any memory allocated by sl_prop_remote_query_create. The query may not be accessed after this function is called.

  Return

    0 on success, negative error code otherwise.

  Parameters

    - `query`: Query to destroy.

int `sl_prop_remote_query_get`(struct sl_prop_query *query, prop_id_t id)

  Add property get to query.

  This function adds an ID to the list of properties to get in a query. A group ID can be added to fetch a full property group in one request message.

  Return

    0 on success, negative error code otherwise.

  Parameters

    - `query`: Query to add GET field to.

    - `id`: ID of property or property group to get.

int `sl_prop_remote_query_get_reply`(struct sl_prop_query *query, prop_id_t id, void *value, size_t valsize)

  Read reply value from query.

  This function reads the reply value from a GET query. The query must have been successfully sent and replied using sl_prop_remote_query_send.

  Return

    0 on success, negative error code otherwise.

  Parameters

    - `query`: Query to read reply from.

    - `id`: ID of property to get.

    - `value`: Pointer where result should be stored.

    - `valsize`: Size of buffer pointed to by value.

int `sl_prop_remote_query_get_reply_to_string`(struct sl_prop_query *query, const struct prop_spec *prop, char *string, size_t size)

  Read reply value from query as string.

  This function is similar to sl_prop_remote_query_get_reply but outputs the reply value as a string instead of binary.

  Return

    0 on success, negative error code otherwise.

  Parameters

    - `query`: Query to read reply from.

    - `prop`: Pointer to the property spec of the property to get.

    - `string`: Pointer where string result should be stored.

    - `size`: Size of string buffer.

int `sl_prop_remote_query_set`(struct sl_prop_query *query, prop_id_t id, const void *value, size_t valsize)

  Add property set to query.

  This function adds an ID and new value to the list of properties to set in a query.

  Return

    0 on success, negative error code otherwise.

  Parameters

    - `query`: Query to add SET field to.

    - `id`: ID of property to set.

    - `value`: New value to set.

    - `valsize`: Size of buffer pointed to by value.

int `sl_prop_remote_query_send`(struct sl_prop_query *query, uint8_t node, uint32_t timeout)

  Send query and wait for reply.

  Send a property query to a remote system and wait for reply. A query can be sent multiple times, e.g. to read out the same telemetry values repeatedly.

  Return

    0 on success, negative error code otherwise.

  Parameters

    - `query`: Query to send.

    - `node`: CSP address of the property node.

    - `timeout`: Timeout of the command in milliseconds.

struct `sl_prop_query_element`
  #include <prop_query.h>

  Query reply element.

  Public Members

  prop_id_t `id`
  const void *`value`
  size_t `size`

struct `sl_prop_query`
  #include <prop_query.h>

  Query state - should not be directly modified.

  Public Members

  sl_prop_query_type `type`
  uint8_t `flags`
  uint8_t *`txbuf`
  size_t `txbufsize`
  uint8_t *`rxbuf`
  size_t `rxbufsize`
  bool `allocated`
  size_t `txsize`
  size_t `rxsize`
  size_t `chunksize`
  struct sl_prop_query_element `element`[48]
  size_t `elements`

## Protocol Specification

This file specifies the remote property access protocol.

It should not be necessary for clients to use these definitions directly. Instead, the prop_client/prop_query functions should be used which handles the protocol and performs necessary byte order conversion.

The remote system listens for messages on a single CSP port (by default port 19). The server only replies to request messages from clients, and does not transmit messages on its own.

Each message begins with an 8-bit type field. Unknown or non-request type messages are silently dropped by the property server. All request frames contain a flag byte. Currently, only a single flag is implemented, by additional flags may be added in future revisions. Messages with unknown flags are considered a protocol error and are silently dropped by the server. All reply frames contain an 8-bit error code immediately after the type field.

Protocol fields are all transmitted in big-endian (“network”) byte order.

Some protocol messages are protected with a “key” field which must be set to a predefined value before the message is accepted.

Get/set request contain packed fields. For get requests, multiple property IDs (or group IDs) can be requested by packing the 16-bit IDs in the data buffer of the get request frame. For string type properties, the ID must be followed by a 16-bit value with the size of the string. The remote system replies with a packed buffer of property IDs and property values.

For set requests, the data field contains packed property IDs, followed by the new value of the corresponding property. Again, string type property IDs must be followed by a 16-bit field with the length of the string argument.

Both the request and reply can be split over multiple frames. The first message in such a transaction must have the SL_PROP_FLAG_BEGIN flag set.

Defines

`SL_PROP_DEFAULT_PORT`

  Default property service port.

`SL_PROP_ERR_NONE`

  Error codes.

  No error

`SL_PROP_ERR_INVAL`

  Invalid argument.

`SL_PROP_ERR_NOENT`

  No such file or directory.

`SL_PROP_ERR_NOSPC`

  No space left on device.

`SL_PROP_ERR_IO`

  I/O error.

`SL_PROP_ERR_TIMEDOUT`

  Timeout while waiting for data.

`SL_PROP_GET_REQUEST`

  Message types.

  Property get request

`SL_PROP_GET_REPLY`

  Property get reply.

`SL_PROP_SET_REQUEST`

  Property set request.

`SL_PROP_SET_REPLY`

  Property set reply.

`SL_PROP_RESET_REQUEST`

  Property reset request.

`SL_PROP_RESET_REPLY`

  Property reset reply.

`SL_PROP_LOAD_REQUEST`

  Property load request.

`SL_PROP_LOAD_REPLY`

  Property load reply.

`SL_PROP_SAVE_REQUEST`

  Property save request.

`SL_PROP_SAVE_REPLY`

  Property save reply.

`SL_PROP_ERASE_REQUEST`

  Property erase request.

`SL_PROP_ERASE_REPLY`

  Property erase reply.

`SL_PROP_LOCK_REQUEST`

  Property lock request.

`SL_PROP_LOCK_REPLY`

  Property lock reply.

`SL_PROP_UNLOCK_REQUEST`

  Property unlock request.

`SL_PROP_UNLOCK_REPLY`

  Property unlock reply.

`SL_PROP_FLAG_BEGIN`

  Flag bits.

  Set on first message in set/get request

`SL_PROP_FLAGS_KNOWN`

  Known flag bits.

  Messages with unknown flags are dropped

`SL_PROP_LOAD_BOOT_KEY`

  Randomly generated magic keys.

`SL_PROP_LOAD_FALLBACK_KEY`

`SL_PROP_SAVE_BOOT_KEY`

`SL_PROP_SAVE_FALLBACK_KEY`

`SL_PROP_ERASE_BOOT_KEY`

`SL_PROP_ERASE_FALLBACK_KEY`

`SL_PROP_LOCK_BOOT_KEY`

`SL_PROP_LOCK_FALLBACK_KEY`

`SL_PROP_UNLOCK_BOOT_KEY`

`SL_PROP_UNLOCK_FALLBACK_KEY`

struct `sl_prop_get_req_t`
  #include <prop_proto.h>

  Property get request.

  Public Members

  uint8_t `type`

    Type must be SL_PROP_GET_REQUEST.

  uint8_t `flags`

    Request flags.

    SL_PROP_FLAG_BEGIN must be set on first frame

  uint8_t `chunksize`

    Max number of bytes to return per reply frame.

    Ignored if SL_PROP_FLAG_BEGIN is not set

  uint8_t `remain`

    Remaining frames after this one.

  uint8_t `data`[0]

    Packed request data.

struct `sl_prop_get_rep_t`
  #include <prop_proto.h>

  Property get reply.

  Public Members

  uint8_t `type`

    Type must be SL_PROP_GET_REPLY.

  uint8_t `error`

    Error code.

  uint8_t `remain`

    Remaining frames after this one.

  uint8_t `data`[0]

    Packed reply data.

struct `sl_prop_set_req_t`
  #include <prop_proto.h>

  Property set request.

  Public Members

  uint8_t `type`

    Type must be SL_PROP_SET_REQUEST.

  uint8_t `flags`

    Request flags.

    SL_PROP_FLAG_BEGIN must be set on first frame

  uint8_t `remain`

    Remaining frames after this one.

  uint8_t `data`[0]

    Packed request data.

struct `sl_prop_set_rep_t`
  #include <prop_proto.h>

  Property set reply.

  Public Members

  uint8_t `type`

    Type must be SL_PROP_SET_REPLY.

  uint8_t `error`

    Error code.

struct `sl_prop_reset_req_t`
  #include <prop_proto.h>

  Property reset request.

  Public Members

  uint8_t `type`

    Type must be SL_PROP_RESET_REQUEST.

  uint8_t `flags`

    Request flags.

  uint8_t `remain`

    Remaining frames after this one.

  uint16_t `id`

    Group ID.

struct `sl_prop_reset_rep_t`
  #include <prop_proto.h>

  Property reset reply.

  Public Members

  uint8_t `type`

    Type must be SL_PROP_RESET_REPLY.

  uint8_t `error`

    Error code.

struct `sl_prop_load_req_t`
  #include <prop_proto.h>

  Property load request.

  Public Members

  uint8_t `type`

    Type must be SL_PROP_LOAD_REQUEST.

  uint8_t `flags`

    Request flags.

  uint16_t `id`

    Group ID.

  uint32_t `key`

    SL_PROP_LOAD_BOOT_KEY/SL_PROP_LOAD_FALLBACK_KEY.

struct `sl_prop_load_rep_t`
  #include <prop_proto.h>

  Property load reply.

  Public Members

  uint8_t `type`

    Type must be SL_PROP_LOAD_REPLY.

  uint8_t `error`

    Error code.

struct `sl_prop_save_req_t`
  #include <prop_proto.h>

  Property save request.

  Public Members

  uint8_t `type`

    Type must be SL_PROP_SAVE_REQUEST.

  uint8_t `flags`

    Request flags.

  uint16_t `id`

    Group ID.

  uint32_t `key`

    SL_PROP_SAVE_BOOT_KEY/SL_PROP_SAVE_FALLBACK_KEY.

struct `sl_prop_save_rep_t`
  #include <prop_proto.h>

  Property save reply.

  Public Members

  uint8_t `type`

    Type must be SL_PROP_SAVE_REPLY.

  uint8_t `error`

    Error code.

struct `sl_prop_erase_req_t`
  #include <prop_proto.h>

  Property erase request.

  Public Members

  uint8_t `type`

    Type must be SL_PROP_ERASE_REQUEST.

  uint8_t `flags`

    Request flags.

  uint16_t `id`

    Group ID.

  uint32_t `key`

    SL_PROP_ERASE_BOOT_KEY/SL_PROP_ERASE_FALLBACK_KEY.

struct `sl_prop_erase_rep_t`
  #include <prop_proto.h>

  Property erase reply.

  Public Members

  uint8_t `type`

    Type must be SL_PROP_ERASE_REPLY.

  uint8_t `error`

    Error code.

struct `sl_prop_lock_req_t`
  #include <prop_proto.h>

  Property lock request.

  Public Members

  uint8_t `type`

    Type must be SL_PROP_LOCK_REQUEST.

  uint8_t `flags`

    Request flags.

  uint16_t `id`

    Group ID.

  uint32_t `key`

    SL_PROP_LOCK_KEY.

struct `sl_prop_lock_rep_t`
  #include <prop_proto.h>

  Property lock reply.

  Public Members

  uint8_t `type`

    Type must be SL_PROP_LOCK_REPLY.

  uint8_t `error`

    Error code.

struct `sl_prop_unlock_req_t`
  #include <prop_proto.h>

  Property unlock request.

  Public Members

  uint8_t `type`
  uint8_t `flags`
  uint16_t `id`
  uint32_t `key`

struct `sl_prop_unlock_rep_t`
  #include <prop_proto.h>

  Property unlock reply.

  Public Members

  uint8_t `type`
  uint8_t `error`

System properties are specified by a subsystem property spec tree (struct prop_subsys_spec) which contains a number of property groups (struct prop_group_spec) which again contains a set of properties (struct prop_spec).

Each property has a 16-bit ID, a type and a string name.

This file contains functions to iterate over the subsystem property spec and to locate properties by ID or name.

Subsystem property specs are distributed with the subsystem client library.

Typedefs

typedef int (*`sl_prop_group_spec_iter_t`)(const struct prop_group_spec *group, void *arg)

  Property group spec iterator function.

  Functions implementing this prototype can be passed to sl_prop_group_spec_iterate to iterate over a subsys property group spec.

  Return

    0 to continue iteration, non-zero to stop iterating.

  Parameters

    - `group`: Pointer to current property group spec.

    - `arg`: Pointer value passed to sl_prop_group_spec_iterate arg argument.

typedef int (*`sl_prop_spec_iter_t`)(const struct prop_spec *prop, void *arg)

  Property spec iterator function.

  Functions implementing this prototype can be passed to sl_prop_spec_iterate to iterate over properties in a property group spec.

  Return

    0 to continue iteration, non-zero to stop iterating.

  Parameters

    - `group`: Pointer to current property spec.

    - `arg`: Pointer value passed to sl_prop_spec_iterate arg argument.

Functions

prop_id_t `sl_prop_remote_id`(const struct prop_spec *spec)

  Get property ID from spec struct.

  Return

    Property ID of property, 0 if NULL is passed.

  Parameters

    - `spec`: Pointer to property spec struct.

prop_type_t `sl_prop_remote_type`(const struct prop_spec *spec)

  Get property type from spec struct.

  Return

    Property type of property, 0 if NULL is passed.

  Parameters

    - `spec`: Pointer to property spec struct.

const char *`sl_prop_spec_type_string`(const struct prop_spec *prop)

  Get string representation of property spec type.

  Return

    String representation of property type or “?” for unknown values.

  Parameters

    - `prop`: Pointer to property spec struct.

const struct prop_group_spec *`sl_prop_group_spec_find_by_name`(const struct prop_subsys_spec *spec, const char *name)

  Find property group spec from name.

  Locate pointer to property group spec from name.

  Return

    Pointer to group spec or NULL if spec could not be found.

  Parameters

    - `spec`: Pointer to subsystem property spec.

    - `name`: Name of property group to find.

const struct prop_spec *`sl_prop_spec_find_by_name`(const struct prop_subsys_spec *spec, const char *name)

  Find property spec from name.

  Locate pointer to property spec from name.

  Return

    Pointer to property spec or NULL if spec could not be found.

  Parameters

    - `spec`: Pointer to subsystem property spec.

    - `name`: Name of property to find.

int `sl_prop_group_spec_iterate`(const struct prop_subsys_spec *spec, sl_prop_group_spec_iter_t iter, void *arg)

  Iterate over property groups in a subsystem spec.

  Call iter function on each property group in subsystem spec. The parameter arg is passed unmodified to the iter function, and can be used to pass context.

  Return

    0 if iteration was successfully completed, error code otherwise.

  Parameters

    - `spec`: Pointer to subsystem property spec.

    - `iter`: Pointer to iterate function.

    - `arg`: Context argument to pass to iterator function.

int `sl_prop_spec_iterate`(const struct prop_group_spec *group, sl_prop_spec_iter_t iter, void *arg)

  Iterate over properties in a property group spec.

  Call iter function on each property in group spec. The parameter arg is passed unmodified to the iter function, and can be used to pass context.

  Return

    0 if iteration was successfully completed, error code otherwise.

  Parameters

    - `group`: Pointer to property group spec.

    - `iter`: Pointer to iterate function.

    - `arg`: Context argument to pass to iterator function.