# 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 uses a C source and header file which defines available properties on the system, and specifies the type and name of each property. The header file is generated from the properties JSON file found in the `props` directory of the client tarball, using the `propgen.py` script. This happens automatically when using the supplied `wscript`. If building manually, the following example shows the command to generate properties for `polaris-client`, but the command is the same for other subsystems, except for changed file names:

    ./prop-client/tools/propgen.py -i $PWD/polaris_props.h -s $PWD/polaris_props.c polaris-client/props/polaris_props.json

Note that the -i and -s arguments expect absolute paths.

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.

  Parameters:

    - string – Pointer to boolean string to parse.

    - size – Size of the value pointed to by string.

    - value – Parsed boolean value.

  Returns:

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

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

  Get remote property value to string.

  Parameters:

    - node – CSP address of the property node.

    - port – CSP port 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.

  Returns:

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

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

  Set remote property value from string.

  Parameters:

    - node – CSP address of the property node.

    - port – CSP port 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.

  Returns:

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

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

  Get remote property value.

  Parameters:

    - node – CSP address of the property node.

    - port – CSP port 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.

  Returns:

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

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

  Set remote property value.

  Parameters:

    - node – CSP address of the property node.

    - port – CSP port 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.

  Returns:

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

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

  Reset remote property or group to default value.

  Parameters:

    - node – CSP address of the property node.

    - port – CSP port of the property node.

    - timeout – Timeout of the command in milliseconds.

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

  Returns:

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

int sl_prop_remote_save(uint8_t node, uint8_t port, 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.

  Parameters:

    - node – CSP address of the property node.

    - port – CSP port 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.

  Returns:

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

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

  Load property group on remote system.

  Parameters:

    - node – CSP address of the property node.

    - port – CSP port 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.

  Returns:

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

int sl_prop_remote_erase(uint8_t node, uint8_t port, 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.

  Parameters:

    - node – CSP address of the property node.

    - port – CSP port 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.

  Returns:

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

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

  Lock property group on remote system.

  Parameters:

    - node – CSP address of the property node.

    - port – CSP port 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.

  Returns:

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

int sl_prop_remote_unlock(uint8_t node, uint8_t port, 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.

  Parameters:

    - node – CSP address of the property node.

    - port – CSP port 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.

  Returns:

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

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, uint8_t port, uint32_t timeout, prop_id_t id, bool val)

  Set remote boolean property.

  Parameters:

    - node – CSP address of the property node.

    - port – CSP port of the property node.

    - timeout – Timeout of the command in milliseconds.

    - id – ID of remote property to set.

    - val – New value of remote property.

  Returns:

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

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

  Get remote boolean property.

  Parameters:

    - node – CSP address of the property node.

    - port – CSP port of the property node.

    - timeout – Timeout of the command in milliseconds.

    - id – ID of remote property to get.

    - val – Pointer to reply value.

  Returns:

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

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

  Set remote signed 8-bit property.

  Parameters:

    - node – CSP address of the property node.

    - port – CSP port of the property node.

    - timeout – Timeout of the command in milliseconds.

    - id – ID of remote property to set.

    - val – New value of remote property.

  Returns:

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

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

  Get remote signed 8-bit property.

  Parameters:

    - node – CSP address of the property node.

    - port – CSP port of the property node.

    - timeout – Timeout of the command in milliseconds.

    - id – ID of remote property to get.

    - val – Pointer to reply value.

  Returns:

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

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

  Set remote signed 16-bit property.

  Parameters:

    - node – CSP address of the property node.

    - port – CSP port of the property node.

    - timeout – Timeout of the command in milliseconds.

    - id – ID of remote property to set.

    - val – New value of remote property.

  Returns:

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

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

  Get remote signed 16-bit property.

  Parameters:

    - node – CSP address of the property node.

    - port – CSP port of the property node.

    - timeout – Timeout of the command in milliseconds.

    - id – ID of remote property to get.

    - val – Pointer to reply value.

  Returns:

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

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

  Set remote signed 32-bit property.

  Parameters:

    - node – CSP address of the property node.

    - port – CSP port of the property node.

    - timeout – Timeout of the command in milliseconds.

    - id – ID of remote property to set.

    - val – New value of remote property.

  Returns:

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

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

  Get remote signed 32-bit property.

  Parameters:

    - node – CSP address of the property node.

    - port – CSP port of the property node.

    - timeout – Timeout of the command in milliseconds.

    - id – ID of remote property to get.

    - val – Pointer to reply value.

  Returns:

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

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

  Set remote signed 64-bit property.

  Parameters:

    - node – CSP address of the property node.

    - port – CSP port of the property node.

    - timeout – Timeout of the command in milliseconds.

    - id – ID of remote property to set.

    - val – New value of remote property.

  Returns:

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

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

  Get remote signed 64-bit property.

  Parameters:

    - node – CSP address of the property node.

    - port – CSP port of the property node.

    - timeout – Timeout of the command in milliseconds.

    - id – ID of remote property to get.

    - val – Pointer to reply value.

  Returns:

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

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

  Set remote unsigned 8-bit property.

  Parameters:

    - node – CSP address of the property node.

    - port – CSP port of the property node.

    - timeout – Timeout of the command in milliseconds.

    - id – ID of remote property to set.

    - val – New value of remote property.

  Returns:

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

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

  Get remote unsigned 8-bit property.

  Parameters:

    - node – CSP address of the property node.

    - port – CSP port of the property node.

    - timeout – Timeout of the command in milliseconds.

    - id – ID of remote property to get.

    - val – Pointer to reply value.

  Returns:

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

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

  Set remote unsigned 16-bit property.

  Parameters:

    - node – CSP address of the property node.

    - port – CSP port of the property node.

    - timeout – Timeout of the command in milliseconds.

    - id – ID of remote property to set.

    - val – New value of remote property.

  Returns:

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

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

  Get remote unsigned 16-bit property.

  Parameters:

    - node – CSP address of the property node.

    - port – CSP port of the property node.

    - timeout – Timeout of the command in milliseconds.

    - id – ID of remote property to get.

    - val – Pointer to reply value.

  Returns:

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

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

  Set remote unsigned 32-bit property.

  Parameters:

    - node – CSP address of the property node.

    - port – CSP port of the property node.

    - timeout – Timeout of the command in milliseconds.

    - id – ID of remote property to set.

    - val – New value of remote property.

  Returns:

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

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

  Get remote unsigned 32-bit property.

  Parameters:

    - node – CSP address of the property node.

    - port – CSP port of the property node.

    - timeout – Timeout of the command in milliseconds.

    - id – ID of remote property to get.

    - val – Pointer to reply value.

  Returns:

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

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

  Set remote unsigned 64-bit property.

  Parameters:

    - node – CSP address of the property node.

    - port – CSP port of the property node.

    - timeout – Timeout of the command in milliseconds.

    - id – ID of remote property to set.

    - val – New value of remote property.

  Returns:

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

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

  Get remote unsigned 64-bit property.

  Parameters:

    - node – CSP address of the property node.

    - port – CSP port of the property node.

    - timeout – Timeout of the command in milliseconds.

    - id – ID of remote property to get.

    - val – Pointer to reply value.

  Returns:

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

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

  Set remote single precision floating point property.

  Parameters:

    - node – CSP address of the property node.

    - port – CSP port of the property node.

    - timeout – Timeout of the command in milliseconds.

    - id – ID of remote property to set.

    - val – New value of remote property.

  Returns:

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

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

  Get remote single preceision floating point property.

  Parameters:

    - node – CSP address of the property node.

    - port – CSP port of the property node.

    - timeout – Timeout of the command in milliseconds.

    - id – ID of remote property to get.

    - val – Pointer to reply value.

  Returns:

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

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

  Set remote double precision floating point property.

  Parameters:

    - node – CSP address of the property node.

    - port – CSP port of the property node.

    - timeout – Timeout of the command in milliseconds.

    - id – ID of remote property to set.

    - val – New value of remote property.

  Returns:

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

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

  Get remote double preceision floating point property.

  Parameters:

    - node – CSP address of the property node.

    - port – CSP port of the property node.

    - timeout – Timeout of the command in milliseconds.

    - id – ID of remote property to get.

    - val – Pointer to reply value.

  Returns:

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

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

  Set remote string property.

  Parameters:

    - node – CSP address of the property node.

    - port – CSP port 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.

  Returns:

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

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

  Get remote string property.

  Parameters:

    - node – CSP address of the property node.

    - port – CSP port 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.

  Returns:

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

int sl_prop_remote_set_binary(uint8_t node, uint8_t port, uint32_t timeout, prop_id_t id, const uint8_t *val, size_t size)

  Set remote binary property.

  Parameters:

    - node – CSP address of the property node.

    - port – CSP port 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 binary value. Must match property size.

  Returns:

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

int sl_prop_remote_get_binary(uint8_t node, uint8_t port, uint32_t timeout, prop_id_t id, uint8_t *val, size_t size)

  Get remote binary property.

  Parameters:

    - node – CSP address of the property node.

    - port – CSP port 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 binary value. Must match property size.

  Returns:

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

## 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:

  enumerator SL_PROP_QUERY_UNKNOWN
  enumerator SL_PROP_QUERY_GET
  enumerator SL_PROP_QUERY_SET

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.

  Parameters:

    - query – Query to initialize.

    - txsize – Size of transmit buffer in bytes.

    - rxsize – Size of receive buffer in bytes.

  Returns:

    0 on success, negative error code otherwise.

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.

  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.

  Returns:

    0 on success, negative error code otherwise.

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.

  Parameters:

    query – Query to reset.

  Returns:

    0 on success, negative error code otherwise.

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.

  Parameters:

    query – Query to destroy.

  Returns:

    0 on success, negative error code otherwise.

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.

  Parameters:

    - query – Query to add GET field to.

    - id – ID of property or property group to get.

  Returns:

    0 on success, negative error code otherwise.

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.

  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.

  Returns:

    0 on success, negative error code otherwise.

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.

  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.

  Returns:

    0 on success, negative error code otherwise.

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.

  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.

  Returns:

    0 on success, negative error code otherwise.

int sl_prop_remote_query_send(struct sl_prop_query *query, uint8_t node, uint8_t port, 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.

  Parameters:

    - query – Query to send.

    - node – CSP address of the property node.

    - port – CSP port of the property node.

    - timeout – Timeout of the command in milliseconds.

  Returns:

    0 on success, negative error code otherwise.

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

  enum 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.

  Param group:

    Pointer to current property group spec.

  Param arg:

    Pointer value passed to sl_prop_group_spec_iterate arg argument.

  Return:

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

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.

  Param prop:

    Pointer to current property spec.

  Param arg:

    Pointer value passed to sl_prop_spec_iterate arg argument.

  Return:

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

Functions

prop_id_t sl_prop_remote_id(const struct prop_spec *spec)

  Get property ID from spec struct.

  Parameters:

    spec – Pointer to property spec struct.

  Returns:

    Property ID of property, 0 if NULL is passed.

prop_type_t sl_prop_remote_type(const struct prop_spec *spec)

  Get property type from spec struct.

  Parameters:

    spec – Pointer to property spec struct.

  Returns:

    Property type of property, 0 if NULL is passed.

const char *sl_prop_spec_type_string(const struct prop_spec *prop)

  Get string representation of property spec type.

  Parameters:

    prop – Pointer to property spec struct.

  Returns:

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

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.

  Parameters:

    - spec – Pointer to subsystem property spec.

    - name – Name of property group to find.

  Returns:

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

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.

  Parameters:

    - spec – Pointer to subsystem property spec.

    - name – Name of property to find.

  Returns:

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

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.

  Parameters:

    - spec – Pointer to subsystem property spec.

    - iter – Pointer to iterate function.

    - arg – Context argument to pass to iterator function.

  Returns:

    0 if iteration was successfully completed, error code otherwise.

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.

  Parameters:

    - group – Pointer to property group spec.

    - iter – Pointer to iterate function.

    - arg – Context argument to pass to iterator function.

  Returns:

    0 if iteration was successfully completed, error code otherwise.