Tock Logo

Join us for TockWorld 7, June 26–28 in San Diego, CA!

Talking Tock

Talking Tock 56

New libtock-c Design

With pull request #370 merged, libtock-c now has a new, consistent format for the library API. This is a major usability upgrade for writing libtock-c apps.

The major high-level changes are:

Example of the New Format

To illustrate the changes, let’s use reading a temperature sensor as an example.

Before, we would roughly have three functions in libtock/temperature.c:

// Call the temperature driver read command syscall.
int temperature_read();
// Take a temperature reading with `upcall` called when the measurement is ready.
int temperature_read_async(subscribe_upcall upcall);
// Take a reading synchronously and store in `temperature`.
int temperature_read_sync(uint32_t* temperature);

These would be named slightly differently driver-to-driver, and to use the async version the caller would need to keep track of the upcall arguments.

After the re-write, our interface looks like this:

// In libtock/sensors/syscalls/temperature_syscalls.c:
returncode_t libtock_temperature_command_read_temperature();

// In libtock/sensors/temperature.c:
typedef void (*libtock_temperature_callback)(returncode_t, int);
returncode_t libtock_temperature_read(libtock_temperature_callback cb);

// In libtock-sync/sensors/temperature.c:
returncode_t libtocksync_temperature_read(uint32_t* temperature);

There are separate libraries for asynchronous and synchronous APIs, all functions are namespaced, and the asynchronous functions have specific callbacks with arguments that are suitable for the specific driver.

Library Design Overview

The development guide describes the full format for libtock-c going forward. The major points are: