Fiber Services

Fiber Lifecycle

A fiber can be spawned by another fiber, by a task, or by the kernel itself during system initialization. A fiber typically becomes executable immediately; however it is possible to delay the scheduling of a newly spawned fiber for a specified time period—for example, to allow device hardware which the fiber uses to become available. The kernel also supports a delayed start cancellation capability, which prevents a newly spawned fiber from executing if the fiber becomes unnecessary before its full delay period is reached.

Once a fiber is started it normally executes forever. A fiber may terminate itself gracefully by simply returning from its entry point function. If it does, it is the fiber’s responsibility to release any system resources it may own (such as a nanokernel semaphore being used in a mutex-like manner) prior to returning, since the kernel does not attempt to reclaim them so they can be reused.

A fiber may also terminate non-gracefully by aborting. The kernel automatically aborts a fiber when it generates a fatal error condition, such as dereferencing a null pointer. A fiber can also explicitly abort itself using fiber_abort(). As with graceful fiber termination, the kernel does not attempt to reclaim system resources owned by the fiber.

Fiber Scheduling

The nanokernel’s scheduler selects which of the system’s threads is allowed to execute; this thread is known as the current context. The nanokernel’s scheduler permits threads to execute only when there is no ISR that needs to execute, since ISR execution takes precedence.

When executing threads, the nanokernel’s scheduler gives fiber execution precedence over task execution. The scheduler preempts task execution whenever a fiber needs to execute, but never preempts the execution of a fiber to allow another fiber to execute—even if it is a higher priority fiber.

The kernel automatically takes care of saving an executing fiber’s CPU register values when it performs a context switch to a different fiber, a task, or an ISR, and restores these values when the fiber later resumes execution.

Fiber Options

The kernel supports several fiber options that inform the kernel about special treatment the fiber requires.

The set of kernel options associated with a fiber are specified when the fiber is spawned. If the fiber uses multiple options they are separated using |; i.e. the logical OR operator. A fiber that does not use any options is spawned using an options value of 0.

The fiber options listed below are pre-defined by the kernel.

USE_FP

Instructs the kernel to save the fiber’s x87 FPU and MMX floating point context information during context switches.

USE_SSE

Instructs the kernel to save the fiber’s SSE floating point context information during context switches. (A fiber using this option implicitly uses the USE_FP option too.)

Defining a Fiber

The following properties must be defined when spawning a fiber:

stack_name

This specifies the memory region used for the fiber’s stack and for other execution context information. To ensure proper memory alignment, it should have the following form:

char __stack <stack_name>[<stack_size>];

stack_size

This specifies the size of the stack_name memory region, in bytes.

entry_point

This specifies the name of the fiber’s entry point function, which should have the following form:

void <entry_point>(int arg1, int arg2)
{
    /* fiber mainline processing */
    ...
    /* (optional) normal fiber termination */
    return;
}

arguments

This specifies the two arguments passed to entry_point when the fiber begins executing. Non-integer arguments can be passed in by casting to an integer type.

priority

This specifies the scheduling priority of the fiber.

options

This specifies the fiber’s options.

Example: Spawning a Fiber from a Task

This code shows how the currently executing task can spawn multiple fibers, each dedicated to processing data from a different communication channel.

#define COMM_STACK_SIZE    512
#define NUM_COMM_CHANNELS  8

struct descriptor {
    ...;
};

char __stack comm_stack[NUM_COMM_CHANNELS][COMM_STACK_SIZE];
struct descriptor comm_desc[NUM_COMM_CHANNELS] = { ... };

...

void comm_fiber(int desc_arg, int unused);
{
    ARG_UNUSED(unused);

    struct descriptor  *desc = (struct descriptor *) desc_arg;

    while (1) {
        /* process packet of data from comm channel */

        ...
    }
}

void comm_main(void)
{
    ...

    for (int i = 0; i < NUM_COMM_CHANNELS; i++) {
        task_fiber_start(&comm_stack[i][0], COMM_STACK_SIZE,
                         comm_fiber, (int) &comm_desc[i], 0,
                         10, 0);
    }

    ...
}