XTOS / OPEN SOURCE REAL-TIME SYSTEMOPEN SOURCE · 1.0.2 · PRERELEASE · IMAGES & SOURCE
DocsCode examples

Code examples

Three complete C examples: an RT queue, synthetic signal processing, and a BCI session.

On this page

Prerequisites

Save the three code blocks as rt-example.c, signal-example.c, and bci-example.c in the OpenXTOS repository root. Build the three SDKs first, then run the matching gcc command. The code uses only public-header APIs.

RT uses SCHED_OTHER, leaves affinity unchanged, and does not call mlock. Signal uses synthetic arrays. The BCI example retains its start/stop and statistics control path; it reads no samples and assumes no absent hardware. See libxtos-bci and the API reference for v1.0.2 sample conversion.

RT example

The example sets and reads back an ordinary policy in the calling thread, then demonstrates deep-copy push/pop and EAGAIN on an empty queue. Sequential single-thread use satisfies SPSC; it proves neither concurrent throughput nor hardware real-time latency. Input and output are caller stack objects; the queue is destroyed after all operations.

Complete file: rt-example.c
#define _GNU_SOURCE
#include <errno.h>
#include <inttypes.h>
#include <sched.h>
#include <stdint.h>
#include <stdio.h>
#include <xtos/rt.h>
#include <xtos/spsc.h>

int main(void)
{
    const struct xtos_rt_config config = {
        .policy = SCHED_OTHER, .priority = 0, .cpu = XTOS_RT_NO_CPU
    };
    struct xtos_spsc_queue *queue;
    int32_t input[2] = {1200, -3400};
    int32_t output[2];
    struct xtos_sample_frame sent = {
        .timestamp_ns = UINT64_C(1000000000), .sequence = 1,
        .channels = 2, .sample_rate_hz = 250, .quality_flags = 0,
        .samples_nv = input
    };
    struct xtos_sample_frame received;
    struct xtos_spsc_stats stats;
    int policy, priority;

    if (xtos_rt_apply(&config) < 0 ||
        xtos_rt_get_current(&policy, &priority) < 0) {
        perror("scheduler");
        return 1;
    }
    queue = xtos_spsc_create(4, 2);
    if (queue == NULL) {
        perror("queue");
        return 1;
    }
    if (xtos_spsc_push(queue, &sent) < 0 ||
        xtos_spsc_pop(queue, &received, output, 2) < 0) {
        perror("frame");
        xtos_spsc_destroy(queue);
        return 1;
    }
    printf("policy=%d priority=%d\n", policy, priority);
    printf("sequence=%" PRIu64 " timestamp_ns=%" PRIu64
           " samples_nv=%" PRId32 ",%" PRId32 "\n",
           received.sequence, received.timestamp_ns, output[0], output[1]);
    if (xtos_spsc_pop(queue, &received, output, 2) != -1 || errno != EAGAIN) {
        fputs("expected empty queue\n", stderr);
        xtos_spsc_destroy(queue);
        return 1;
    }
    xtos_spsc_get_stats(queue, &stats);
    printf("pushed=%" PRIu64 " popped=%" PRIu64 " empty=EAGAIN\n",
           stats.pushed, stats.popped);
    xtos_spsc_destroy(queue);
    return 0;
}
bash
gcc -std=c11 -Wall -Wextra -Werror -O2 \
  -Isdk/libxtos-rt/include rt-example.c \
  sdk/libxtos-rt/libxtos-rt.a -o rt-example
./rt-example

Success means exit status 0, SCHED_OTHER/0 readback, preserved samples and sequence, pushed/popped both 1, and EAGAIN from the second pop. Before FIFO/RR, verify permission, policy restoration, and shutdown.

Signal example

The example generates 256 points at 256 Hz with 10/20/9 Hz components, reconstructs and validates timestamps, then applies a 50 Hz notch and 5–40 Hz band-pass. DFT/SSVEP use the original array; filtering reports its final value separately. P300 uses a separate baseline and artificial peak for numeric demonstration only.

Complete file: signal-example.c
#include <inttypes.h>
#include <math.h>
#include <stdint.h>
#include <stdio.h>
#include <xtos/signal.h>

#define N 256
#define FS 256U
#define PI 3.14159265358979323846

int main(void)
{
    uint64_t timestamps[N];
    double input[N], filtered[N], power[N / 2 + 1];
    double epoch[N] = {0};
    struct xtos_signal_validation validation;
    struct xtos_notch_filter notch;
    struct xtos_bandpass_filter bandpass;
    struct xtos_ssvep_feature ssvep;
    struct xtos_p300_feature p300;
    int status;

    if (xtos_signal_correct_timestamps(UINT64_C(1000000000), FS,
                                        timestamps, N) < 0) {
        perror("timestamps");
        return 1;
    }
    status = xtos_signal_validate_timestamps(timestamps, N, FS, 0, &validation);
    if (status != 0) {
        if (status < 0) perror("validate");
        else fputs("timestamp anomalies\n", stderr);
        return 1;
    }
    for (size_t i = 0; i < N; ++i) {
        double phase = 2.0 * PI * (double)i / FS;
        input[i] = sin(10.0 * phase) + 0.5 * sin(20.0 * phase)
                 + 0.25 * sin(9.0 * phase);
    }
    if (xtos_notch_init(&notch, FS, 50.0, 20.0) < 0 ||
        xtos_bandpass_init(&bandpass, FS, 5.0, 40.0) < 0 ||
        xtos_notch_process(&notch, input, filtered, N) < 0 ||
        xtos_bandpass_process(&bandpass, filtered, filtered, N) < 0 ||
        xtos_signal_fft_power(input, N, power, N / 2 + 1) < 0 ||
        xtos_signal_ssvep_feature(input, N, FS, 10.0, 2, 1, &ssvep) < 0) {
        perror("signal");
        return 1;
    }
    for (size_t i = 0; i < 32; ++i)
        epoch[i] = (i & 1U) ? 1.0 : -1.0;
    epoch[128] = 5.0;
    if (xtos_signal_p300_feature(epoch, N, FS, 32, 250, 500, 4.0, &p300) < 0) {
        perror("p300");
        return 1;
    }
    printf("interval_ns=%" PRIu64 " anomalies=%zu/%zu\n",
           validation.expected_interval_ns, validation.interval_anomalies,
           validation.timestamp_anomalies);
    printf("bins=%d power[10]=%.3f filtered_last=%.6f\n",
           N / 2 + 1, power[10], filtered[N - 1]);
    printf("ssvep_bin=%zu harmonics=%zu snr=%.3f snr_db=%.3f\n",
           ssvep.target_bin, ssvep.harmonics_used, ssvep.snr, ssvep.snr_db);
    printf("p300_detected=%d z=%.3f latency_ms=%.3f\n",
           p300.detected, p300.peak_z_score, p300.peak_latency_ms);
    return 0;
}
bash
gcc -std=c11 -Wall -Wextra -Werror -O2 \
  -Isdk/libxtos-signal/include signal-example.c \
  sdk/libxtos-signal/libxtos-signal.a -lm -o signal-example
./signal-example

Output includes interval and anomaly counts, spectrum length and bin power, filtered value, SSVEP harmonics, and P300 z score and latency. Spectrum capacity is N/2+1; filters are initialized before sequential processing. There is no real EEG, diagnosis, participant experiment, or hardware-latency result.

BCI example

The example reads cached device information, prints name with a length bound, starts and immediately stops, reads driver statistics, and cleans up. It changes no rate or gain, does not call unsupported calibration, reads no float samples, and does not call driver counts consumed frames. Without a device, compile only.

Complete file: bci-example.c; check compilation only without a device
#include <inttypes.h>
#include <stdio.h>
#include <xtos/bci.h>

int main(int argc, char **argv)
{
    const char *path = argc > 1 ? argv[1] : "/dev/xtos0";
    xtos_bci_session_t *session;
    struct xtos_bci_device_info info;
    struct xtos_bci_statistics stats;
    int exit_status = 1;

    session = xtos_bci_session_create(path);
    if (session == NULL) {
        perror("session_create");
        return 1;
    }
    if (xtos_bci_get_info(session, &info) < 0) {
        perror("get_info");
        goto cleanup;
    }
    if (info.num_channels == 0 || info.sampling_rate == 0) {
        fputs("invalid cached device info\n", stderr);
        goto cleanup;
    }
    printf("device=%.*s channels=%" PRIu32 " rate=%" PRIu32 " Hz\n",
           (int)sizeof(info.name), info.name, info.num_channels, info.sampling_rate);
    if (xtos_bci_start(session) < 0) {
        perror("start");
        goto cleanup;
    }
    /* Control-path example: do not interpret the published float read ABI. */
    if (xtos_bci_stop(session) < 0) {
        perror("stop");
        goto cleanup;
    }
    if (xtos_bci_get_stats(session, &stats) < 0) {
        perror("get_stats");
        goto cleanup;
    }
    printf("driver_samples=%" PRIu64 " dropped=%" PRIu64
           " errors=%" PRIu64 " overruns=%" PRIu64 "\n",
           stats.samples_read, stats.samples_dropped, stats.errors, stats.overruns);
    exit_status = 0;
cleanup:
    xtos_bci_session_destroy(session);
    return exit_status;
}
bash
gcc -std=c11 -Wall -Wextra -Werror -O2 \
  -Isdk/libxtos-bci/include bci-example.c \
  sdk/libxtos-bci/libxtos-bci.a -o bci-example

# Run only with a registered device and read/write permission:
./bci-example /dev/xtos0

For ENOENT, check device binding and registration. For EACCES, check node permission. For EBUSY, check the existing opener. invalid cached device info can indicate GET_INFO failed during create. Preserve start/stop errors and inspect driver logs; an empty device file is not a workaround.

Verification and extension

Record the public commit ID, gcc --version, complete commands, exit status, and raw stdout/stderr. RT/signal can run on an ordinary Linux host; recheck ABI and environment on target XTOS. BCI compilation proves linkable symbols and types only; device execution also needs driver, connection, and acquisition records.

For RT, use one producer and one consumer and destroy after shutdown. For signal, check cross-block state and timing with fixed input. For BCI, check the released conversion, serial frames, channel order, and timing, and define recovery for partial data lost on non-EINTR errors before adding DSP.