Switch from TI-RTOS to SimpleLink POSIX: Threads and Semaphores

A real world migration from TI-RTOS to the POSIX API of TI SimpleLink. Texas Instruments migrated from the proprietary TI-RTOS to the open POSIX API. I'm migrating a project that extensively used the TI paradigms to that POSIX API. You're my witness. The blog assumes that you are a TI-RTOS user and want to adapt to the new ways of working.

POSIX is an open API that defines how threads can be used. It also deals with common multi-thread topics like sharing (or reserving) resources, scheduling, priorities, and what have you.

I'm using the POSIX API to program the firmware of a Programmable Electronic Load. In fact, I'm porting the firmware from TI-RTOS to POSIX. You can follow along.

Exercice 1: Threads

A TI-RTOS task turns into a POSIX thread. In the original firmware for the electronic load, I used the RTOS GUI to configure them.

In the POSIX paradigm, you declare and create them in code.

The heartbeat thread described here is a low priority job that will blink a LED on the LaunchPad. It helps to visually check the health of the RTOS while developing.

Any activity that impacts the bandwidth to run jobs regularly is easy spotted because the LED's rhythm gets disrupted. That's something that can be spotted by just looking at the board.

At the startup of the firmware, before the RTOS is started, The tasks are created.

note: BIOS_start() is TI-RTOS specific.

    /* Set priority and stack size attributes */
    pthread_attr_init(&attrs);
    priParam.sched_priority = 1;


    detachState = PTHREAD_CREATE_DETACHED;
    retc = pthread_attr_setdetachstate(&attrs, detachState);
    if (retc != 0) {
        /* pthread_attr_setdetachstate() failed */
        while (1);
    }


    pthread_attr_setschedparam(&attrs, &priParam);


    retc |= pthread_attr_setstacksize(&attrs, THREADSTACKSIZE);
    if (retc != 0) {
        /* pthread_attr_setstacksize() failed */
        while (1);
    }

    retc = pthread_create(&thread, &attrs, threadHeartBeat, NULL);
    if (retc != 0) {
        /* pthread_create() failed */
        while (1);
    }
// initiate shared hardware modules only. The ones dedicated to a task are initiated in that task
    GPIO_init();




    BIOS_start();

The thread has the same look and feel as the TI-RTOS task. You initialise the work to be done, then loop and sleep.

I still have to turn that sleep time into something that is centrally gouverned (together with priority), so that I don't loose view on what's running when.

I could pass it in arg0, but for the moment I'm planning to use just a header file where each thread's signature, sleep time and priority is defined (discuss if you think this can be done better).

/*
 *  ======== threadHeartBeat ========
 */
void *threadHeartBeat(void *arg0)
{
    /* 1 second delay */
    uint32_t time = 1;


    /* Call driver init functions */


    /* Configure the LED pin */
    GPIO_setConfig(Board_GPIO_LED0, GPIO_CFG_OUT_STD | GPIO_CFG_OUT_LOW);


    /* Turn on user LED */
    GPIO_write(Board_GPIO_LED0, Board_GPIO_LED_ON);


    while (1) {
        sleep(time);
        GPIO_toggle(Board_GPIO_LED0);
    }
}

This is an easy migration. I didn't expect complexities here because I've done this before in both FreeRTOS and TI-RTOS, both without the POSIX API.

Also, it's the main chunk of the SimpleLink RTOS "empty" example.

Exercice 2: UART , Triggers and Semaphores

I'm starting with the UART interface because it uses some interesting RTOS structures: interrupt driven IO and semaphores.

The task to read the UART is interrupt driven. Our task always sleeps and only wakes up when a character arrives at the USB Rx line.

We use a binary semaphore for that - one that always blocks unless a process (in our case, serial in interrupt) posts to that semaphore.

sem_t SEM_uart_rx; // this binary semaphore handles uart receiving interrupts

The semaphore gets initialised at the start of the UART task:

    iError = sem_init(&SEM_uart_rx, 0, 0);

Then, in that task's while loop, the process blocks on that binary semaphore and goes to sleep. Check the sem_wait() call.

   /* Loop forever echoing */
    while (1) {
        UART_read(uart, &input, 1);
        iError = sem_wait(&SEM_uart_rx); // when a character is received via UART, the interrupt handler will release the binary semaphore
        while (iError) {
            // POSIX reported error with semaphore. Can't recover.
        }
        // in my case: I get an interrupt for a single character, no need to loop.
        scpi_instrument_input((const char *)&input, 1);
    }

The task will sleep until someone wakes up the semaphore. The UART data receive interrupt will do that:

void UART00_IRQHandler(UART_Handle handle, void *buffer, size_t num)
{
    sem_post(&SEM_uart_rx);
}

This task does not have a sleep() call, because it isn't scheduled. The semaphore construct makes it reactive (and very cheap on resources while waiting).

The whole construct (including the registration of the read interrupt handler) looks like this:

void *threadUART(void *arg0)
{
    char        input;
    UART_Params uartParams;
    int iError;


    /* Call driver init functions */
//    GPIO_init();
    UART_init();


    /* Configure the LED pin */
    GPIO_setConfig(Board_GPIO_LED0, GPIO_CFG_OUT_STD | GPIO_CFG_OUT_LOW);


    /* Create a UART with data processing off. */
    UART_Params_init(&uartParams);
    uartParams.writeDataMode = UART_DATA_BINARY;
    uartParams.readDataMode = UART_DATA_BINARY;
    uartParams.readReturnMode = UART_RETURN_FULL;
    uartParams.readEcho = UART_ECHO_OFF;
    uartParams.baudRate = 9600;
    uartParams.readMode = UART_MODE_CALLBACK; // the uart uses a read interrupt
    uartParams.readCallback = &UART00_IRQHandler; // function called when the uart interrupt fires

    uart = UART_open(Board_UART0, &uartParams);

    if (uart == NULL) {
        /* UART_open() failed */
        while (1);
    }


    iError = sem_init(&SEM_uart_rx, 0, 0);

    /* Loop forever echoing */
    while (1) {
        UART_read(uart, &input, 1);
        iError = sem_wait(&SEM_uart_rx); // when a character is received via UART, the interrupt handler will release the binary semaphore
        while (iError) {
            // POSIX reported error with semaphore. Can't recover.
        }
        // in my case: I get an interrupt for a single character, no need to loop.
        scpi_instrument_input((const char *)&input, 1);
    }
}

Writing to UART hasn't changed from the original TI-RTOS implementation, because that's not using interrupts and only has dependencies on the TI Driver lib.

The task is created exactly the same as the heartbeat one:

    retc = pthread_create(&thread, &attrs, threadUART, NULL);
    if (retc != 0) {
        /* pthread_create() failed */
        while (1);
    }

I'll have to port all of the electronic load tasks. Most of that exercise will be a repeat from what you see in this post.

The exception is those locations where I use a mailbox to send info between tasks (and wait on traffic on the mailboxes).

I'll have to do some investigation first before I can do that. But if it's as easy as porting the threads and semaphores, I have good hope.