Coldwave Documentation

Appearance

Peripheral Drivers ​

Peripheral driver API and device lifecycle.

Every peripheral in coldwave-os — UART, I²C, SPI, GPIO, flash, network interfaces, modems, sensors — is exposed to application code through a uniform handle-based interface. This page explains the common lifecycle that every driver-backed API in this documentation follows; the driver-specific pages (UART, I²C, Flash, ...) only describe the operations that are unique to the respective hardware.

Device registration (sysconf) ​

A device only exists for the application after it has been declared in the system configuration. The integrator places one [sysconf_create_device(...)](/embed/2.2.0/API/Files/sysconfig_8h.md#define-sysconf-create-device) block per physical peripheral, giving it a string name and any required sysprops (pin assignments, baudrate, ...). That name is the key passed to open(const char*) at runtime. Registration of the driver itself is not described here — it is the OS integrator's responsibility and uses [sysconf_use_driver(...)](/embed/2.2.0/API/Files/sysconfig_8h.md#define-sysconf-use-driver).

Opening and closing ​

Application code obtains a handle with open(const char*) and releases it with close(int). The handle is an opaque integer; all subsequent driver calls (uart_write, i2c_read, flash_erase, ...) take this handle as their first argument and return -ENODEV if it is invalid.

Concurrency rules differ between drivers:

  • Exclusive (UART, ADC/DAC, ...): can be opened only once at a time. A second [open()](/embed/2.2.0/API//group__core__driver.md#function-open) on the same device name fails until the first holder calls [close()](/embed/2.2.0/API//group__core__driver.md#function-close).
  • Shared (I²C, GPIO, ...): multiple handles to the same device may coexist; the driver serializes access internally.

Power management ​

A device that is not currently open is eligible for sleep, which lets the OS power down the underlying peripheral block. Holding a handle unnecessarily therefore costs energy — open the device when you need it, close it when you don't.

Minimal usage pattern ​

cpp
int h = open("uart0");          // name from sysconf_create_device(...)
if (h < 0) {
    // device not declared, already open exclusively, or driver missing
    return -1;
}

uart_config(h, 115200, 8, UART_STOPBITS_1, UART_PARITY_NONE);
uart_write(h, "hi\r\n", 4, 100);

close(h);                       // releases the handle and allows sleep

Error handling ​

Driver functions return 0 on success and a negative errno value on failure. The most common codes are:

  • -ENODEV — handle is invalid or the underlying device is gone.
  • -EINVAL — argument out of range or violates a driver constraint (e.g. unaligned flash address).
  • -EBUSY — device is currently held by another user (exclusive drivers).

Modules ​

Name
Flash
On-chip / external flash memory access.

Functions Overview ​

Name
intopen(const char * device_name)
Opens a device for use by the caller and returns a handle.
intclose(int s)
Closes a previously opened device handle.

Function Details ​

function open ​

cpp
int open(
    const char * device_name
)

Opens a device for use by the caller and returns a handle.

Parameters:

  • device_name Name assigned to the device in the system configuration.

Return: A non-negative handle on success, -1 on failure.

The handle is the first argument to every driver-specific call (uart_write, i2c_read, ...). Possible reasons for failure:

  • no device with device_name was declared via sysconf_create_device;
  • the device exists but the associated driver was not registered with sysconf_use_driver;
  • the device is exclusive and already held by another caller.

Always pair a successful call with close once the handle is no longer needed so the OS can put the peripheral to sleep.

function close ​

cpp
int close(
    int s
)

Closes a previously opened device handle.

Parameters:

Return: 0 on success, -1 if s does not refer to an open device.

Releases the handle, makes the device available for other callers (exclusive devices) and lets the OS suspend the peripheral if no other handle to it is open.