Notificaciones (I)

Hasta hoy hemos visto ejemplos de tareas aisladas para demostrar algunos puntos. Sin embargo, las diferentes tareas de las que un sistema embebido está compuesto no trabajan en aislamiento; al contrario, todas ellas, aunque independientes, trabajan en equipo con un mismo objetivo. Para lograrlo las tareas deben pasarse información unas con otras y estar en sincronía. En esta lección veremos una primer forma de pasar información, y en un próxima trataremos el tema de la sincronización.

En FreeRTOS existen diferentes maneras para que una tarea pase información a otra, y cada una varía en su grado de complejidad:

Notificaciones directas (más “fácil”, pero más limitada).
Colas.
Flujos y mensajes (menos “fácil” pero más poderosa y versátil).

Las notificaciones directas son la forma más fácil y rápida para pasar información. Hoy vamos a ver cómo pasar un dato de 32 bits, y en la segunda parte veremos cómo pasar y procesar banderas (conocidas también como notificaciones). En lecciones posteriores estudiaremos las restantes.

¿Qué es y qué necesito?

Hasta antes de la versión 10.4.0 de FreeRTOS cada tarea en FreeRTOS incluía un campo de 32 bits para ser utilizado como canal de comunicaciones o de sincronización. A partir de dicha versión se incluyó un arreglo de campos. En esta lección estudiaremos las notificaciones simples (las anteriores a la versión 10.4.0).

El nombre oficial para los campos de 32 bits es “notificaciones” y pertenecen a un mecanismo de FreeRTOS llamado notificaciones directas a las tareas (en inglés, Direct to task notifications, DtTN). Aunque este nombre evoca más sincronización que comunicaciones lo utilizaré junto con el de campos para evitar futuras confusiones. Además, ten en cuenta que las notificaciones también sirven para notificar eventos a las tareas, lo cual es tema de una siguiente lección.

La idea detrás de las notificaciones es simple: si la tarea T_a debe pasarle un dato a la tarea T_b, entonces T_a deberá escribirlo en el campo de notificación de T_b, y ésta utilizarlo. Así de fácil. El campo de datos del cual estoy hablando es un entero de 32 bits, y en éste puedes pasar valores enteros, booleanos, banderas, e inclusive, apuntadores void (para pasar información más compleja).

Toma en cuenta que este mecanismo, DtTN, sólo funciona para pasar un dato a la vez de una tarea a otra. Si tu aplicación necesita pasar una colección (lista) de resultados a una o más tareas, entonces deberás utilizar colas, flujos o mensajes, los cuales son más complejos, más lentos y consumen más recursos que las notificaciones directas.

Quizás te estés preguntando, ¿porqué no simplemente usamos variables globales ? Bueno, por tres razones:

Las variables globales son malas.
La tarea receptora T_b, del ejemplo anterior, puede bloquearse (es decir, pasar al estado Blocked; en términos coloquiales, irse a “dormir”) liberando la CPU hasta que reciba la notificación por parte de la tarea T_a. Cuando el dato esté listo, entonces T_b pasa al estado Ready (lista para ejecutarse).
Si el dato no llega dentro de un cierto tiempo, entonces la tarea receptora T_b puede salir del estado Blocked y tomar las acciones necesarias. Esto es muy importante en sistemas embebidos seguros. Además, bajo ciertas configuraciones, existe la posibilidad de que la tarea productora T_a también tome acciones en caso de que por alguna razón la tarea T_b no pudiera accesar al dato.

Si quisieras utilizar variables globales en lugar de las notificaciones de FreeRTOS tu tarea receptora debería estar todo el tiempo despierta preguntando si ya hay un dato disponible; y como consecuencia estaría consumiendo valiosos ciclos de CPU. Y si eso no es suficiente, tendrías que agregar un temporizador para salir de la espera. Muy complicado, mejor usa las notificaciones.

Cuando la tarea emisora T_a escribe el dato en la tarea receptora T_b, la notificación (así se le llama en FreeRTOS) pasa al estado Pending (en español, pendiente) esperando a que T_b lo lea. Este estado Pending de la notificación es el que hace que T_b pase del estado Blocked a Ready. Luego, cuando T_b lo lee, entonces la notificación pasa al estado Not pending. El hecho de que el dato haya sido escrito en T_b no implica que tenga que ser leído inmediatamente, ya que podría pasar un tiempo entre una y otra cosa. Por ejemplo, supón que T_b es una tarea de baja prioridad, y después de que T_a escribió el dato, una tarea de más alta prioridad obtiene la CPU por lo cual, aunque T_b ya fue “notificada”, aún no ha podido leer el dato, sino hasta que le toque su turno.

Por otro lado, en algunas configuraciones (que veremos después) si la notificación tiene el estado Not pending (T_b no la ha leído) y la tarea emisora T_a intenta escribir un nuevo dato, entonces la llamada T_a devolverá un error. Esto sirve porque a veces no querrás sobreescribir un valor nuevo sobre uno anterior si la tarea receptora no lo ha leído.

Para empezar a mandar información entre tareas (en inglés, intertask communication) vamos a usar dos funciones: xTaskNotify() y xTaskNotifyWait(). (Aquí puedes ver el conjunto completo de funciones para notificaciones.)

xTaskNotify()

Esta es la función que la tarea productora debe utilizar para pasar el dato. Su firma es:

xTaskToNotify. En este parámetro le pasamos el handler de la tarea receptora.

¿Recuerdas que en esta lección te mencioné que varios mecanismos de FreeRTOS requieren el handler de las tareas para operar sobre ellas? Pues no hay plazo que no se cumpla. Muchas de las funciones que estudiaremos a partir de esta lección necesitan saber sobre quién van a operar, y la única forma es a través de su handler. En FreeRTOS hay dos maneras de obtenerlo:

Guardándolo (en una variable global) cuando creas tareas con xTaskCreate() y xTaskCreateStatic().
Utilizando a la función xTaskGetHandle(), la cual utiliza a la cadena de texto que representó el nombre de la tarea cuando la creaste (aquí puedes ver su descripción).

En esta lección utilizaremos la primer forma, tanto por simplicidad, como para que veas cómo se guarda (ya que no lo hemos hecho en ejemplos anteriores).

ulValue. Aquí escribes el valor de 32 bits que quieres pasar a la tarea receptora xTaskToNotify.

De ser necesario deberás promocionar el dato que quieres escribir al tipo uint32_t.

eAction. Este parámetro le indica a la función qué hacer con el dato de 32 bits. Para efectos de pasar un dato, el cual es el tema de esta lección, deberás escribir la constante eSetValueWithOverwrite.

En la siguiente lección, Notificaciones (II), te explicaré con detalle el resto de valores que puedes escribir en este parámetro y su significado. Por lo pronto, con lo descrito es suficiente.

Para el caso que nos ocupa, esta función siempre devolverá el valor pdPASS.

xTaskNotifyWait()

La tarea receptora deberá llamar a esta función, cuya firma es:

Como ya lo había mencionado, una vez que la tarea receptora hace la llamada pasa al estado Blocked esperando a que un dato arribe, y mientras la tarea esté en ese estado no usa ciclos de la CPU, lo cual es bueno. Esta función también tiene la ventaja de que si el dato no llega dentro de un cierto tiempo, puede salir y avisarnos para que tomemos las medidas necesarias.

En el bajo mundo de los sistemas operativos cuando una tarea se queda esperando de manera indefinida por un dato o resultado que nunca llegará le llamamos starvation (en español, inanición), y como podrás imaginar, es una muy mala situación. Afortunadamente, muchas funciones de FreeRTOS incorporan una especie de software watchdog (perro guardían) que nos ayudará a salir de dicha situación.

Si deseas utilizar esta característica asegúrate que la tarea receptora tenga una prioridad alta, ya que de no ser así, el código asociado al manejo de la inanición tardará en ejecutarse, o peor aún, nunca hacerlo.

Veamos los parámetros de la función:

ulBitsToClearOnEntry. Este parámetro indica qué bits del dato deben ponerse a cero a la entrada de la función. Es una especie de máscara para eliminar bits que no nos interesan y se utiliza cuando pasas bits en lugar de valores.

En esta lección deberás escribir el valor 0x00. Con esto le estarás diciendo que no ponga ningún bit a cero, ya que eso alteraría nuestro dato. En la segunda parte de esta lección veremos cómo se usa.

ulBitsToClearOnExit. Este parámetro indica qué bits del dato deben ponerse a cero a la salida de la función. Es una especie de máscara para eliminar bits que no nos interesan y se utiliza cuando transmites bits en lugar de valores.

En esta lección deberás escribir el valor 0x00. Con esto le estarás diciendo que no ponga ningún bit a cero a la salida. FreeRTOS hace una copia del dato antes de aplicarle la limpieza de bits, y luego devuelve dicha copia, así que por lo pronto no te preocupes. En la segunda parte de esta lección veremos cómo se usa.

pulNotificationValue. En este parámetro escribirás la dirección de la variable donde quieres guardar el dato. Recuerda que dicha variable debe ser de 32 bits, es decir, del tipo uint32_t.

xTicksToWait. En este parámetro indicas cuánto tiempo (en ticks) quieres esperar por el dato; puedes esperar el tiempo que quieras (especificándolo en milisegundos a través de la macro pdMS_TO_TICKS(), o esperar por siempre especificando el valor portMAX_DELAY.

En un sistema embebido bien hecho JAMÁS deberías especificar portMAX_DELAY.
Atte: Cualquier programador de sistemas embebidos.

Me permito ser repetitivo: para usar esta característica asegúrate que la prioridad de la tarea receptora sea igual o mayor que la productora para que cuando el tiempo expire FreeRTOS la escoja para ser ejecutada. Si tiene prioridad baja, entonces deberá esperar su turno, y quizás éste nunca llegue.

En los ejemplos a continuación veremos ambas formas.

Valor de retorno. Esta función devolverá pdPASS cuando se reciba una notificación, o si la notificación ya estaba lista cuando hiciste la llamada. Si el tiempo programado expiró, entonces devolverá pdFAIL.

Configuración

Antes de ejecutar los ejemplos a continuación asegúrate que las siguientes constantes simbólicas (en el archivo de configuración FreeRTOSConfig.h) tienen el valor mostrado:

#define configUSE_TASK_NOTIFICATIONS            1
#define configTASK_NOTIFICATION_ARRAY_ENTRIES   1 // o cualquier valor igual o mayor

Ejemplo 1

En este primer ejemplo veremos un programa simple donde una tarea produce un dato cada 1000 ms y una tarea receptora los procesa. El dato producido es el valor 1, 2, 3. La tarea receptora parpadeará ese mismo número de veces. El periodo de cada parpadeo es de 200 ms.

#include <FreeRTOS.h>
#include <task.h>

TaskHandle_t consumidor_h;
// la tarea productora necesita saber quién es el consumidor

void Productor_task( void* pvParameters )
{
    uint32_t cont = 1;
    // el valor que queremos transmitir debe ser uint32_t

    TickType_t last_wake_time = xTaskGetTickCount();

    while( 1 )
    {
        vTaskDelayUntil( &last_wake_time, pdMS_TO_TICKS( 1000 ) );

        Serial.println( "P" );

        xTaskNotify( consumidor_h, cont, eSetValueWithOverwrite );

        ++cont;
        if( cont > 3 ) cont = 1;
    }
}

void Consumidor_task( void* pvParameters )
{
    pinMode( 13, OUTPUT );

    uint32_t blinks;
    // la variable donde guardamos el dato debe ser uint32_t

    while( 1 )
    {
        xTaskNotifyWait( 0x00, 0x00, &blinks, portMAX_DELAY );

        Serial.println( blinks );
        // Depuración: Imprimos el número de parpadeos

        for( uint8_t i = 0; i < blinks; ++i ){

            digitalWrite( 13, HIGH );
            vTaskDelay( pdMS_TO_TICKS( 100 ) );
            digitalWrite( 13, LOW );
            vTaskDelay( pdMS_TO_TICKS( 100 ) );
        }
    }
}

void setup()
{
    Serial.begin( 115200 );

    xTaskCreate( Productor_task, "PROD", 128, NULL, tskIDLE_PRIORITY + 1, NULL );
    // nota que la prioridad del productor es más alta que la del consumidor;
    // casi siempre será así.

    xTaskCreate( Consumidor_task, "CONS", 128, NULL, tskIDLE_PRIORITY, &consumidor_h );
    // en consumidor_h guardamos el handle de la tarea consumidora

    vTaskStartScheduler();
}

void loop() 
{
}

Nota que la tarea productora tiene prioridad más alta que la consumidora. Además, no basta con que la productora escriba el dato, también debe prestarle la CPU a la tarea receptora; esto lo logra llamando a la función vTaskDelayUntil(), aunque por supuesto puedes usar cualquier otra función que haga que la tarea productora se bloquée.

Ejemplo 2

En este ejemplo agregué elementos para que la tarea productora falle (no notifique a la tarea receptora), y para que la receptora no se quede en un ciclo infinito esperando por un dato que nunca va a llegar. Ambas tareas tienen la misma prioridad.

#include <FreeRTOS.h>
#include <task.h>

TaskHandle_t consumidor_h;
// la tarea productora necesita saber quién es el consumidor

void Productor_task( void* pvParameters )
{
    uint32_t cont = 1;

    uint8_t cont_to_fail = 10;

    TickType_t last_wake_time = xTaskGetTickCount();

    while( 1 )
    {
        vTaskDelayUntil( &last_wake_time, pdMS_TO_TICKS( 1000 ) );

        Serial.println( "P" );

        xTaskNotify( consumidor_h, cont, eSetValueWithOverwrite );

        ++cont;
        if( cont > 3 ) cont = 1;

        // hacemos que falle después de 10 ciclos
        if( --cont_to_fail == 0 ){ 

           while( 1 ) taskYIELD();
           // esta tarea entrega voluntariamente la CPU,
           // aunque la vida real no es tan bonita

        }
    }
}

void Consumidor_task( void* pvParameters )
{
    pinMode( 13, OUTPUT );

    uint32_t blinks;

    while( 1 )
    {
        if( xTaskNotifyWait( 0x00, 0x00, &blinks, pdMS_TO_TICKS( 2000 ) ) == pdPASS ){

           Serial.println( blinks );

           for( uint8_t i = 0; i < blinks; ++i ){

               digitalWrite( 13, HIGH );
               vTaskDelay( pdMS_TO_TICKS( 100 ) );
               digitalWrite( 13, LOW );
               vTaskDelay( pdMS_TO_TICKS( 100 ) );

           }
         } else{ // time-over:

            digitalWrite( 13, HIGH );

            while( 1 ){
               Serial.println( "Error" );
               vTaskDelay( pdMS_TO_TICKS( 1000 ) );
            }
         }
    }
}

void setup()
{
    Serial.begin( 115200 );

    xTaskCreate( Productor_task, "PROD", 128, NULL, tskIDLE_PRIORITY + 0, NULL );

    xTaskCreate( Consumidor_task, "CONS", 128, NULL, tskIDLE_PRIORITY, &consumidor_h );

    vTaskStartScheduler();
}

void loop() 
{
}

En la siguiente imagen podrás ver una ejecución de este programa:

¿Qué sigue?

En la lección de hoy vimos cómo utilizar un mecanismo intrínseco de FreeRTOS para comunicaciones y sincronización: las notificaciones directas a las tareas. Éste es un campo de 32 bits al cual podemos darle diversos usos. Uno de ellos ya lo discutimos, y otro uso, el de las notificaciones, lo veremos en la segunda parte.

También recalqué la idea de que las tareas no deberían quedarse esperando de manera indefinida. Muchas funciones de FreeRTOS incluyen un time-out para que la tarea receptora tome las acciones necesarias en caso de inanición (starvation). Úsalo siempre que te sea posible.

En la segunda parte de esta lección estudiaremos cómo usar este mismo mecanismo pero para enviar notificaciones (banderas, señalizaciones) como bits individuales.

(En esta página encontrarás información de suma importancia sobre los flujos, mensajes y notificaciones, aunque todavía no hayamos visto tales temas. Deberías leerla en cuanto te sea posible.)

Índice del curso

Espero que esta entrada haya sido de tu interés. Si fue así podrías suscribirte a mi blog, o escríbeme a fjrg76 dot hotmail dot com, o comparte esta entrada con alguien que consideres que puede serle de ayuda.

Acerca de
Últimas entradas

Fco. Javier Rodríguez

Freelancer, Diseñador Senior en fjrg76.com

Soy Ingeniero Electrónico con 20+ años de experiencia en el diseño y desarrollo de productos electrónicos de consumo y a medida, y 12+ años como profesor. Egresado de la UNAM, también tengo el grado de Maestro en Ingeniería por la misma universidad.

Mi perfil completo lo puede encontrar en: https://www.linkedin.com/in/fjrg76-dot-com/

Últimas entradas de Fco. Javier Rodríguez (ver todo)

Is your code asking too many questions? Learn how the “Tell, Don’t Ask” principle can make your objects do the talking - enero 6, 2024
A Beginner’s Step-by-step Guide to Custom Power Symbols in KiCAD - enero 6, 2024
¡Hazlo, no preguntes! O sobre cómo dejar de abusar de los getters - diciembre 9, 2023