Introdução e Motivação

Em sistemas embarcados modernos, especialmente aqueles baseados em FreeRTOS, a forma como o firmware reage ao mundo externo é tão importante quanto o código em si. Sensores, comunicação, interrupções, timers e pilhas de protocolo geram estímulos de forma assíncrona, e arquiteturas tradicionais baseadas apenas em superloop rapidamente se tornam difíceis de manter, escalar e depurar. É nesse contexto que surge a Arquitetura Orientada a Eventos (Event-Driven Architecture – EDA).

No FreeRTOS, uma arquitetura orientada a eventos não é um “modo especial” do sistema operacional, mas sim uma estratégia de organização do firmware, onde tarefas permanecem bloqueadas aguardando eventos específicos e acordam apenas quando algo relevante ocorre. Esses eventos podem ser sinais de interrupção, mensagens, flags, notificações, timers ou dados disponíveis em buffers. O resultado é um sistema reativo, determinístico e eficiente em consumo de CPU.

Do ponto de vista de engenharia, essa abordagem resolve três problemas clássicos:

1. Desperdício de CPU causado por polling constante
2. Acoplamento excessivo entre módulos
3. Dificuldade de sincronização entre múltiplas fontes de eventos

Ao adotar uma arquitetura orientada a eventos, o firmware passa a se comportar como um conjunto de agentes cooperativos, cada tarefa com responsabilidade clara, reagindo apenas aos eventos que lhe dizem respeito. Isso melhora a legibilidade do código, reduz latência média de resposta e facilita testes unitários e manutenção evolutiva.

No FreeRTOS, essa arquitetura é viabilizada por um conjunto muito poderoso de primitivas nativas: Task Notifications, Queues, Event Groups, Stream Buffers, Message Buffers e Software Timers. Cada uma delas atende a um tipo específico de evento e será explorada detalhadamente ao longo deste artigo, sempre com exemplos práticos e contextualizados.

O que vem a seguir

Na próxima seção, entraremos no modelo conceitual da Arquitetura Orientada a Eventos no FreeRTOS, explicando como eventos fluem pelo sistema, como tarefas devem ser estruturadas e como evitar armadilhas comuns, como event storms, inversão de prioridade e acoplamento indireto.

Modelo Conceitual da Arquitetura Orientada a Eventos

Em uma arquitetura orientada a eventos no FreeRTOS, o sistema deixa de ser centrado em fluxo sequencial de execução e passa a ser organizado em torno de eventos que representam fatos relevantes do sistema. Um evento pode significar “um dado chegou”, “um tempo expirou”, “um periférico terminou uma operação” ou “uma condição de estado foi satisfeita”. O papel central do RTOS é suspender tarefas até que esses eventos ocorram, garantindo previsibilidade temporal e uso eficiente do processador.

Do ponto de vista conceitual, essa arquitetura pode ser dividida em três elementos fundamentais: produtores de eventos, mecanismos de transporte de eventos e consumidores de eventos. Produtores normalmente são ISRs, timers de software, drivers ou tarefas de baixo nível. O transporte é feito pelas primitivas do FreeRTOS, enquanto os consumidores são tarefas que encapsulam lógica de negócio ou processamento de dados. Esse desacoplamento é essencial para sistemas escaláveis.

Um princípio importante é que tarefas orientadas a eventos devem permanecer bloqueadas na maior parte do tempo. Em FreeRTOS, isso significa usar chamadas bloqueantes como xQueueReceive(), xEventGroupWaitBits() ou ulTaskNotifyTake(), sempre com portMAX_DELAY ou tempos bem definidos. Dessa forma, não há polling ativo, e o escalonador pode dedicar CPU apenas às tarefas que realmente precisam executar naquele instante.

Outro ponto crítico do modelo é que eventos não devem carregar lógica, apenas sinalização e dados mínimos. A decisão do que fazer em resposta a um evento pertence à tarefa consumidora. Isso evita que ISRs fiquem complexas e garante que decisões de alto nível ocorram sempre em contexto de tarefa, onde mutexes, alocação de memória e chamadas de API são seguras.

Fluxo típico de eventos no FreeRTOS

Um fluxo clássico em arquitetura orientada a eventos segue o seguinte encadeamento lógico:

1. Um periférico gera uma interrupção (por exemplo, UART RX completa).
2. A ISR sinaliza o evento usando uma primitiva segura para interrupções.
3. O kernel do FreeRTOS desbloqueia a tarefa interessada.
4. A tarefa acorda, processa o evento e retorna ao estado bloqueado.

Esse modelo cria um sistema reativo e previsível, onde a latência entre o evento e o processamento é controlada diretamente pela prioridade da tarefa e pela duração das ISRs. Em projetos bem arquitetados, o tempo gasto dentro da interrupção é mínimo, e todo o processamento ocorre em nível de tarefa.

Exemplo conceitual simplificado

void vUartTask(void *pvParameters)
{
    uint8_t rxByte;

    for (;;)
    {
        if (xQueueReceive(uartRxQueue, &rxByte, portMAX_DELAY) == pdPASS)
        {
            processUartByte(rxByte);
        }
    }
}

void vUartTask(void *pvParameters)
{
    uint8_t rxByte;

    for (;;)
    {
        if (xQueueReceive(uartRxQueue, &rxByte, portMAX_DELAY) == pdPASS)
        {
            processUartByte(rxByte);
        }
    }
}

Neste exemplo, a tarefa vUartTask não executa continuamente. Ela permanece bloqueada até que um byte seja colocado na fila por uma ISR ou outra tarefa. Isso caracteriza perfeitamente o modelo orientado a eventos: o evento é a chegada de um dado, e a tarefa existe apenas para reagir a ele.

Implicações arquiteturais importantes

Ao adotar esse modelo, algumas decisões de projeto tornam-se fundamentais. A granularidade dos eventos deve ser cuidadosamente escolhida: eventos muito genéricos levam a tarefas complexas e difíceis de testar; eventos excessivamente específicos geram sobrecarga e fragmentação. Além disso, o uso correto de prioridades é crucial para garantir que eventos críticos sejam tratados com menor latência.

Outro aspecto frequentemente negligenciado é o tratamento de eventos concorrentes. O FreeRTOS permite que múltiplos eventos acordem a mesma tarefa, mas o firmware deve ser capaz de lidar com isso de forma determinística, normalmente utilizando estruturas de estado bem definidas ou state machines orientadas a eventos.

Na próxima seção, entraremos nos mecanismos de eventos disponíveis no FreeRTOS, começando pelo mais eficiente e subutilizado deles: Task Notifications, analisando seu funcionamento interno, vantagens, limitações e padrões de uso.

Excelente, seguimos.

Task Notifications como Mecanismo Central de Eventos

Entre todos os mecanismos oferecidos pelo FreeRTOS, as Task Notifications são, do ponto de vista arquitetural, a forma mais eficiente de implementar uma arquitetura orientada a eventos. Elas funcionam como um canal direto ponto-a-ponto entre o kernel e uma tarefa, sem a sobrecarga de filas, sem alocação dinâmica e com latência mínima.

Cada tarefa no FreeRTOS possui internamente um array de notificações (desde o FreeRTOS 10), onde cada entrada contém um valor de 32 bits e um estado. Isso transforma a task notification em algo conceitualmente próximo a um registrador de eventos privado da tarefa. Esse detalhe é fundamental para entender por que esse mecanismo é tão eficiente e, ao mesmo tempo, tão poderoso.

Diferente de filas ou event groups, uma task notification não é compartilhada. Ela pertence a uma única tarefa. Isso força uma arquitetura mais limpa, onde existe um mapeamento explícito entre quem produz e quem consome o evento. Em arquiteturas bem desenhadas, isso reduz drasticamente o acoplamento implícito e elimina ambiguidades.

Modelo mental correto para Task Notifications

É comum iniciantes tratarem task notifications como “um semáforo mais rápido”. Embora isso seja parcialmente verdadeiro, essa visão é limitada. O modelo correto é pensar nelas como:

• Um evento binário (acordar ou não acordar a task)
• Um contador (quantidade de eventos acumulados)
• Um bitmap de flags
• Um payload de 32 bits

Tudo isso usando a mesma infraestrutura, dependendo apenas da API utilizada.

Essa flexibilidade permite criar arquiteturas orientadas a eventos extremamente compactas, onde um único mecanismo substitui filas, semáforos e flags em muitos cenários.

Exemplo 1 — Evento simples (sinalização pura)

Neste primeiro exemplo, uma ISR sinaliza que um evento ocorreu, e a tarefa apenas reage.

void vEventTask(void *pvParameters)
{
    for (;;)
    {
        ulTaskNotifyTake(pdTRUE, portMAX_DELAY);

        handleEvent();
    }
}

void vEventTask(void *pvParameters)
{
    for (;;)
    {
        ulTaskNotifyTake(pdTRUE, portMAX_DELAY);

        handleEvent();
    }
}

A função ulTaskNotifyTake() bloqueia a tarefa até que uma notificação seja recebida. O parâmetro pdTRUE indica que o contador interno será limpo ao acordar, garantindo comportamento de evento simples.

A ISR responsável pelo evento:

void EXTI_IRQHandler(void)
{
    BaseType_t xHigherPriorityTaskWoken = pdFALSE;

    vTaskNotifyGiveFromISR(eventTaskHandle, &xHigherPriorityTaskWoken);

    portYIELD_FROM_ISR(xHigherPriorityTaskWoken);
}

void EXTI_IRQHandler(void)
{
    BaseType_t xHigherPriorityTaskWoken = pdFALSE;

    vTaskNotifyGiveFromISR(eventTaskHandle, &xHigherPriorityTaskWoken);

    portYIELD_FROM_ISR(xHigherPriorityTaskWoken);
}

Aqui, o evento é produzido de forma segura em contexto de interrupção, e o kernel pode realizar context switch imediato se a prioridade justificar. Esse padrão é ideal para eventos como botão pressionado, fim de conversão ADC ou término de DMA.

Exemplo 2 — Contador de eventos acumulados

Em cenários onde múltiplos eventos podem ocorrer antes da tarefa acordar, a task notification pode atuar como contador.

void vLoggerTask(void *pvParameters)
{
    uint32_t events;

    for (;;)
    {
        events = ulTaskNotifyTake(pdFALSE, portMAX_DELAY);

        while (events--)
        {
            logEvent();
        }
    }
}

void vLoggerTask(void *pvParameters)
{
    uint32_t events;

    for (;;)
    {
        events = ulTaskNotifyTake(pdFALSE, portMAX_DELAY);

        while (events--)
        {
            logEvent();
        }
    }
}

Ao usar pdFALSE, o contador não é automaticamente zerado. O valor retornado indica quantos eventos ocorreram desde a última leitura. Isso é extremamente útil em sistemas com bursts de eventos, como recepção de pacotes ou amostras rápidas de sensores.

Exemplo 3 — Task Notification como bitmap de eventos

Outra aplicação avançada é usar o valor de 32 bits como mapa de bits de eventos, substituindo completamente os Event Groups quando o evento é destinado a uma única tarefa.

#define EVT_RX_READY   (1 << 0)
#define EVT_TX_DONE   (1 << 1)
#define EVT_ERROR     (1 << 2)

void vCommTask(void *pvParameters)
{
    uint32_t events;

    for (;;)
    {
        xTaskNotifyWait(0x00, 0xFFFFFFFF, &events, portMAX_DELAY);

        if (events & EVT_RX_READY)
            handleRx();

        if (events & EVT_TX_DONE)
            handleTxDone();

        if (events & EVT_ERROR)
            handleError();
    }
}

#define EVT_RX_READY   (1 << 0)
#define EVT_TX_DONE   (1 << 1)
#define EVT_ERROR     (1 << 2)

void vCommTask(void *pvParameters)
{
    uint32_t events;

    for (;;)
    {
        xTaskNotifyWait(0x00, 0xFFFFFFFF, &events, portMAX_DELAY);

        if (events & EVT_RX_READY)
            handleRx();

        if (events & EVT_TX_DONE)
            handleTxDone();

        if (events & EVT_ERROR)
            handleError();
    }
}

Esse padrão cria uma máquina de eventos compacta, extremamente eficiente e fácil de analisar em termos de latência e consumo de recursos.

Vantagens arquiteturais das Task Notifications

Do ponto de vista de engenharia de sistemas, as task notifications oferecem:

• Menor latência entre evento e execução
• Zero uso de heap
• Menor footprint de memória
• Determinismo temporal elevado
• Código mais explícito e fácil de rastrear

Por esse motivo, em arquiteturas orientadas a eventos bem projetadas, task notifications devem ser a primeira opção, e não a última.

Na próxima seção, vamos tratar de Event Groups, explicando quando eles são necessários, como evitá-los em excesso e como integrá-los corretamente em uma arquitetura orientada a eventos sem criar dependências implícitas.

Seguimos.

The post Arquitetura Orientada a Eventos no FreeRTOS first appeared on MCU & FPGA.

Conceito de Tarefas no FreeRTOS e Estrutura Básica

Em um RTOS (Real-Time Operating System), o conceito central não é mais o superloop, mas sim a tarefa (task). Uma tarefa representa uma unidade independente de execução, com seu próprio contexto de CPU (registradores), sua própria pilha (stack) e um estado bem definido dentro do escalonador (scheduler). No FreeRTOS, tarefas são implementadas como funções C que nunca retornam, pois o controle do fluxo de execução é feito exclusivamente pelo kernel.

Do ponto de vista conceitual, uma tarefa pode ser vista como uma thread cooperativa/preemptiva, dependendo da configuração do sistema. O FreeRTOS utiliza escalonamento preemptivo por prioridade (opcionalmente cooperativo), onde a tarefa de maior prioridade pronta para execução assume o processador. Isso permite modelar sistemas embarcados de forma mais determinística, separando claramente aquisição de dados, processamento, comunicação e controle.

Assinatura de uma tarefa no FreeRTOS

Toda tarefa no FreeRTOS segue a mesma assinatura básica:

void vMinhaTarefa(void *pvParameters)
{
    for (;;)
    {
        /* Código da tarefa */
    }
}

void vMinhaTarefa(void *pvParameters)
{
    for (;;)
    {
        /* Código da tarefa */
    }
}

Alguns pontos importantes que merecem atenção:

• A função não deve retornar.
• O parâmetro pvParameters é um ponteiro genérico (void*) que permite passar dados para a tarefa no momento da criação.
• O loop infinito não é opcional: ele garante que a tarefa continue viva enquanto o sistema estiver em execução.
• Bloqueios devem ser feitos usando primitivas do RTOS (como vTaskDelay()), nunca com busy wait.

Criação de tarefas com xTaskCreate()

A API clássica para criação dinâmica de tarefas no FreeRTOS é a função xTaskCreate():

BaseType_t xTaskCreate(
    TaskFunction_t pxTaskCode,
    const char * const pcName,
    const uint16_t usStackDepth,
    void * const pvParameters,
    UBaseType_t uxPriority,
    TaskHandle_t * const pxCreatedTask
);

BaseType_t xTaskCreate(
    TaskFunction_t pxTaskCode,
    const char * const pcName,
    const uint16_t usStackDepth,
    void * const pvParameters,
    UBaseType_t uxPriority,
    TaskHandle_t * const pxCreatedTask
);

Vamos detalhar cada parâmetro com precisão técnica:

• pxTaskCode
  Ponteiro para a função que implementa a tarefa.
• pcName
  Nome simbólico da tarefa. Útil para debug, trace e ferramentas como FreeRTOS+Trace.
• usStackDepth
  Tamanho da pilha da tarefa em palavras, não em bytes.
  Em arquiteturas 32 bits (como Cortex-M), 1 palavra = 4 bytes.
• pvParameters
  Ponteiro genérico para dados passados à tarefa.
• uxPriority
  Prioridade da tarefa. Quanto maior o valor, maior a prioridade.
• pxCreatedTask
  Retorna um handle da tarefa criada, usado para controle posterior (suspender, deletar, notificar etc.).

Exemplo prático: tarefa de LED

#include "FreeRTOS.h"
#include "task.h"

void vTaskBlink(void *pvParameters)
{
    (void) pvParameters;

    for (;;)
    {
        HAL_GPIO_TogglePin(GPIOC, GPIO_PIN_13);
        vTaskDelay(pdMS_TO_TICKS(500));
    }
}

void app_main(void)
{
    xTaskCreate(
        vTaskBlink,
        "Blink",
        128,
        NULL,
        1,
        NULL
    );

    vTaskStartScheduler();
}

#include "FreeRTOS.h"
#include "task.h"

void vTaskBlink(void *pvParameters)
{
    (void) pvParameters;

    for (;;)
    {
        HAL_GPIO_TogglePin(GPIOC, GPIO_PIN_13);
        vTaskDelay(pdMS_TO_TICKS(500));
    }
}

void app_main(void)
{
    xTaskCreate(
        vTaskBlink,
        "Blink",
        128,
        NULL,
        1,
        NULL
    );

    vTaskStartScheduler();
}

Nesse exemplo:

• A tarefa vTaskBlink executa periodicamente a cada 500 ms.
• vTaskDelay() coloca a tarefa no estado Blocked, liberando a CPU para outras tarefas.
• pdMS_TO_TICKS() converte tempo em milissegundos para ticks do sistema, respeitando configTICK_RATE_HZ.

Estados de uma tarefa no FreeRTOS

Internamente, o kernel gerencia cada tarefa em um dos seguintes estados principais:

• Running – tarefa atualmente em execução.
• Ready – pronta para executar, aguardando CPU.
• Blocked – aguardando tempo, evento ou recurso.
• Suspended – explicitamente suspensa pelo usuário.
• Deleted – removida do sistema.

A criação correta das tarefas e o uso adequado de delays e sincronização é o que garante previsibilidade temporal, baixo consumo de CPU e bom comportamento em sistemas embarcados complexos.

Perfeito, vamos avançar mantendo o mesmo rigor técnico e didático.

The post Como Criar Tarefas e Soft Timers no FreeRTOS: Guia Prático e Didático para Sistemas Embarcados first appeared on MCU & FPGA.

Este artigo explora a convenção de nomenclatura do FreeRTOS, explicando a lógica por trás da escolha dos prefixos e sufixos, além de fornecer exemplos práticos e amplamente documentados para ajudar iniciantes no uso desse sistema operacional.

1. Convenção de Nomenclatura no FreeRTOS

O FreeRTOS segue um conjunto de regras bem definido para nomear funções, variáveis e tipos de dados. Essas regras são fundamentais para manter a legibilidade e a consistência do código. As principais características da nomenclatura são:

1. Prefixos das Funções – Indicam a categoria da função.
2. Tipos de Dados e Estruturas – Usam typedefs com convenções específicas.
3. Uso de Sufixos – Algumas funções e variáveis possuem sufixos que indicam propriedades específicas.

Nos tópicos seguintes, vamos explorar essas convenções com mais detalhes e exemplos práticos.

2. Prefixos das Funções no FreeRTOS

As funções do FreeRTOS seguem uma padronização de prefixos para indicar a categoria ou funcionalidade à qual pertencem. Isso facilita a organização do código e a compreensão rápida do que cada função faz. Os prefixos mais comuns são:

2.1. Funções de Gerenciamento de Tarefas

Essas funções lidam com a criação, suspensão, retomada e exclusão de tarefas no FreeRTOS. O prefixo usado é vTask ou xTask, dependendo do tipo de retorno. Elas são definidas no arquivo de cabeçalho tasks.h que deve ser incluído para seu uso.

• xTaskCreate() – Cria uma nova tarefa.
• vTaskDelete() – Exclui uma tarefa existente.
• vTaskDelay() – Suspende a tarefa por um período de tempo.
• xTaskGetSchedulerState() – Obtém o estado atual do escalonador.

Exemplo: Criando uma tarefa no FreeRTOS

#include "FreeRTOS.h"
#include "task.h"

void vTaskFunction(void *pvParameters) {
    while(1) {
        // Código da tarefa
        vTaskDelay(pdMS_TO_TICKS(1000)); // Atraso de 1 segundo
    }
}

void app_main(void) {
    xTaskCreate(vTaskFunction, "MinhaTarefa", configMINIMAL_STACK_SIZE, NULL, 1, NULL);
}

Neste exemplo, xTaskCreate() é usada para criar a tarefa, e vTaskDelay() para introduzir um atraso.

2.2. Funções de Gerenciamento de Filas

As filas são amplamente utilizadas no FreeRTOS para comunicação entre tarefas. As funções relacionadas a filas começam com o prefixo xQueue. As funções relativas ao Queue são definidas no header queue.h que deve ser incluído sempre que forem usadas.

• xQueueCreate() – Cria uma fila.
• xQueueSend() – Envia um item para a fila.
• xQueueReceive() – Recebe um item da fila.
• uxQueueMessagesWaiting() – Retorna o número de itens na fila.

Exemplo: Criando e usando uma fila

QueueHandle_t xQueue;

void vTaskSender(void *pvParameters) {
    int valor = 42;
    while(1) {
        xQueueSend(xQueue, &valor, portMAX_DELAY);
        vTaskDelay(pdMS_TO_TICKS(500)); // Envio a cada 500ms
    }
}

void vTaskReceiver(void *pvParameters) {
    int recebido;
    while(1) {
        if (xQueueReceive(xQueue, &recebido, portMAX_DELAY)) {
            printf("Recebido: %d\n", recebido);
        }
    }
}

void app_main(void) {
    xQueue = xQueueCreate(10, sizeof(int)); // Cria fila com 10 posições
    xTaskCreate(vTaskSender, "Sender", configMINIMAL_STACK_SIZE, NULL, 1, NULL);
    xTaskCreate(vTaskReceiver, "Receiver", configMINIMAL_STACK_SIZE, NULL, 1, NULL);
}

Aqui, xQueueCreate() cria a fila, xQueueSend() insere valores e xQueueReceive() os lê.

2.3. Funções de Semáforos e Mutexes

Os semáforos e mutexes são usados para sincronizar tarefas e gerenciar acesso a recursos compartilhados. O prefixo para essas funções é xSemaphore ou xMutex. Estas funçõe são definidas no arquivo de cabeçalho semaphore.h.

• xSemaphoreCreateBinary() – Cria um semáforo binário.
• xSemaphoreGive() – Libera um semáforo.
• xSemaphoreTake() – Captura um semáforo.
• xSemaphoreCreateMutex() – Cria um mutex.

Exemplo: Uso de mutex para evitar condições de corrida

SemaphoreHandle_t xMutex;

void vTask1(void *pvParameters) {
    while(1) {
        if (xSemaphoreTake(xMutex, portMAX_DELAY)) {
            printf("Tarefa 1 acessando recurso\n");
            vTaskDelay(pdMS_TO_TICKS(500));
            xSemaphoreGive(xMutex);
        }
        vTaskDelay(pdMS_TO_TICKS(100));
    }
}

void vTask2(void *pvParameters) {
    while(1) {
        if (xSemaphoreTake(xMutex, portMAX_DELAY)) {
            printf("Tarefa 2 acessando recurso\n");
            vTaskDelay(pdMS_TO_TICKS(500));
            xSemaphoreGive(xMutex);
        }
        vTaskDelay(pdMS_TO_TICKS(100));
    }
}

void app_main(void) {
    xMutex = xSemaphoreCreateMutex();
    xTaskCreate(vTask1, "Task1", configMINIMAL_STACK_SIZE, NULL, 1, NULL);
    xTaskCreate(vTask2, "Task2", configMINIMAL_STACK_SIZE, NULL, 1, NULL);
}

Aqui, xSemaphoreCreateMutex() cria um mutex, enquanto xSemaphoreTake() e xSemaphoreGive() garantem o acesso seguro ao recurso.

2.4. Funções de Timers

Os timers no FreeRTOS permitem a execução periódica de funções. As funções relacionadas a timers começam com xTimer. As funções de Timer são definidas no arquivo de cabeçalho timer.h.

• xTimerCreate() – Cria um novo timer.
• xTimerStart() – Inicia um timer.
• xTimerStop() – Para um timer.
• xTimerReset() – Reinicia um timer.

Exemplo: Criando um timer no FreeRTOS

TimerHandle_t xTimer;

void vTimerCallback(TimerHandle_t xTimer) {
    printf("Timer expirado!\n");
}

void app_main(void) {
    xTimer = xTimerCreate("MeuTimer", pdMS_TO_TICKS(2000), pdTRUE, NULL, vTimerCallback);
    if (xTimer != NULL) {
        xTimerStart(xTimer, 0);
    }
}

O timer dispara vTimerCallback() a cada 2 segundos.

3. Tipos de Dados e Estruturas no FreeRTOS

No FreeRTOS, a padronização dos tipos de dados e estruturas é essencial para garantir a portabilidade entre diferentes arquiteturas de microcontroladores. A nomenclatura segue convenções bem definidas para facilitar a leitura e evitar ambiguidades.

Os principais tipos de dados no FreeRTOS são:

• BaseType_t – Tipo base genérico para representar valores numéricos.
• TickType_t – Usado para armazenar valores de tempo (ticks do sistema).
• UBaseType_t – Variante sem sinal de BaseType_t, usada para contadores e índices.
• TaskHandle_t – Representa uma referência para uma tarefa.
• QueueHandle_t – Representa uma referência para uma fila.
• SemaphoreHandle_t – Representa um semáforo ou mutex.
• TimerHandle_t – Manipulador para um timer do FreeRTOS.

A seguir, exploraremos esses tipos de dados com exemplos práticos.

3.1. BaseType_t e UBaseType_t

O tipo BaseType_t é a base para a maioria dos tipos de retorno no FreeRTOS. Ele é definido de forma genérica para ser compatível com diferentes arquiteturas (8, 16, 32 ou 64 bits).

• BaseType_t pode ser positivo, negativo ou zero.
• UBaseType_t é sempre positivo e é usado para índices e contadores.

Exemplo: Verificando retorno de uma função

BaseType_t xStatus;
UBaseType_t uxCount = 0;

void app_main(void) {
    xStatus = xTaskCreatePinnedToCore(vTaskFunction, "Task", configMINIMAL_STACK_SIZE, NULL, 1, NULL, 0);

    if (xStatus == pdPASS) {
        printf("Tarefa criada com sucesso!\n");
    } else {
        printf("Falha ao criar tarefa.\n");
    }

    uxCount++;
    printf("Número de tentativas: %u\n", (unsigned int)uxCount);
}

Aqui, BaseType_t verifica se a criação da tarefa foi bem-sucedida, enquanto UBaseType_t conta as tentativas de criação.

3.2. TickType_t

O tipo TickType_t é usado para armazenar valores de tempo no FreeRTOS. O sistema mede o tempo em “ticks”, que dependem da frequência configurada (configTICK_RATE_HZ).

Exemplo: Obtendo o tempo atual do sistema

TickType_t xStartTime, xElapsedTime;

void app_main(void) {
    xStartTime = xTaskGetTickCount(); // Obtém o tempo atual em ticks
    vTaskDelay(pdMS_TO_TICKS(500)); // Aguarda 500ms
    xElapsedTime = xTaskGetTickCount() - xStartTime; // Calcula o tempo decorrido

    printf("Tempo decorrido: %lu ticks\n", (unsigned long)xElapsedTime);
}

Aqui, xTaskGetTickCount() é usado para medir o tempo decorrido de uma operação.

3.3. TaskHandle_t

O tipo TaskHandle_t é um ponteiro que referencia uma tarefa, permitindo manipulá-la dinamicamente.

Exemplo: Criando e suspendendo uma tarefa

TaskHandle_t xTaskHandle = NULL;

void vTaskFunction(void *pvParameters) {
    while (1) {
        printf("Tarefa executando...\n");
        vTaskDelay(pdMS_TO_TICKS(1000));
    }
}

void app_main(void) {
    xTaskCreate(vTaskFunction, "Task1", configMINIMAL_STACK_SIZE, NULL, 1, &xTaskHandle);

    vTaskDelay(pdMS_TO_TICKS(5000)); // Espera 5 segundos antes de suspender a tarefa
    vTaskSuspend(xTaskHandle);
    printf("Tarefa suspensa!\n");
}

Aqui, xTaskHandle é usado para suspender a tarefa após 5 segundos.

3.4. QueueHandle_t

O tipo QueueHandle_t armazena uma referência a uma fila, permitindo sua manipulação por diferentes tarefas.

Exemplo: Criando e verificando uma fila

QueueHandle_t xQueue;

void app_main(void) {
    xQueue = xQueueCreate(5, sizeof(int)); // Cria uma fila com capacidade para 5 inteiros

    if (xQueue != NULL) {
        printf("Fila criada com sucesso!\n");
    } else {
        printf("Falha ao criar a fila.\n");
    }
}

Aqui, QueueHandle_t é usado para armazenar a referência da fila criada.

3.5. SemaphoreHandle_t

O tipo SemaphoreHandle_t é usado para armazenar referência a semáforos e mutexes.

Exemplo: Criando um semáforo binário

SemaphoreHandle_t xSemaphore;

void app_main(void) {
    xSemaphore = xSemaphoreCreateBinary();

    if (xSemaphore != NULL) {
        printf("Semáforo criado!\n");
    } else {
        printf("Falha ao criar semáforo.\n");
    }
}

Aqui, SemaphoreHandle_t armazena o manipulador do semáforo criado.

3.6. TimerHandle_t

O tipo TimerHandle_t é usado para armazenar referências a timers criados no FreeRTOS.

Exemplo: Criando um timer que dispara a cada 2 segundos

TimerHandle_t xTimer;

void vTimerCallback(TimerHandle_t xTimer) {
    printf("Timer expirado!\n");
}

void app_main(void) {
    xTimer = xTimerCreate("MeuTimer", pdMS_TO_TICKS(2000), pdTRUE, NULL, vTimerCallback);

    if (xTimer != NULL) {
        xTimerStart(xTimer, 0);
        printf("Timer iniciado!\n");
    } else {
        printf("Falha ao criar o timer.\n");
    }
}

Aqui, TimerHandle_t armazena a referência do timer criado.

4. Uso de Sufixos em Funções e Variáveis do FreeRTOS

Além dos prefixos e tipos de dados padronizados, o FreeRTOS também utiliza sufixos em funções e variáveis para indicar propriedades específicas. Esses sufixos ajudam a identificar rapidamente características como escopo, tipo de dado ou comportamento esperado da função.

Os principais sufixos usados no FreeRTOS são:

• FromISR – Indica que a função pode ser chamada a partir de uma interrupção.
• _t – Indica que o nome refere-se a um tipo de dado.
• Handle – Representa um manipulador para um objeto do FreeRTOS.
• Ticks – Refere-se a unidades de tempo do sistema (ticks).
• MS – Representa valores em milissegundos.

A seguir, exploramos cada um desses sufixos com exemplos práticos.

4.1. Sufixo FromISR

Funções que podem ser chamadas dentro de um handler de interrupção possuem o sufixo FromISR. Isso é necessário porque chamadas dentro de interrupções não podem executar determinadas operações do sistema operacional, como esperar indefinidamente (portMAX_DELAY).

Exemplo: Enviando um item para uma fila dentro de uma interrupção

QueueHandle_t xQueue;

void IRAM_ATTR vISRHandler(void *arg) {
    int valor = 10;
    BaseType_t xHigherPriorityTaskWoken = pdFALSE;

    xQueueSendFromISR(xQueue, &valor, &xHigherPriorityTaskWoken);

    if (xHigherPriorityTaskWoken == pdTRUE) {
        portYIELD_FROM_ISR();
    }
}

void app_main(void) {
    xQueue = xQueueCreate(5, sizeof(int));

    gpio_install_isr_service(0);
    gpio_isr_handler_add(GPIO_NUM_4, vISRHandler, NULL);
}

Aqui, xQueueSendFromISR() é usado para evitar bloqueios dentro da interrupção.

4.2. Sufixo _t

O sufixo _t indica que o nome representa um tipo de dado definido pelo FreeRTOS.

Exemplo: Utilizando tipos de dados do FreeRTOS

BaseType_t xStatus;
TickType_t xTime;
QueueHandle_t xQueue;

Aqui, BaseType_t, TickType_t e QueueHandle_t seguem essa convenção.

4.3. Sufixo Handle

O sufixo Handle é usado para representar manipuladores de objetos do FreeRTOS, como tarefas, filas, semáforos e timers.

Exemplo: Criando e manipulando uma tarefa

TaskHandle_t xTaskHandle = NULL;

void vTaskFunction(void *pvParameters) {
    while (1) {
        printf("Executando tarefa...\n");
        vTaskDelay(pdMS_TO_TICKS(1000));
    }
}

void app_main(void) {
    xTaskCreate(vTaskFunction, "MinhaTarefa", configMINIMAL_STACK_SIZE, NULL, 1, &xTaskHandle);
    vTaskDelay(pdMS_TO_TICKS(5000));
    vTaskDelete(xTaskHandle);
}

Aqui, TaskHandle_t armazena o manipulador da tarefa para que possamos manipulá-la posteriormente.

4.4. Sufixo Ticks

O sufixo Ticks indica que o valor da variável ou função está expresso em ticks de sistema.

Exemplo: Calculando tempo em ticks

TickType_t xStartTime, xElapsedTime;

void app_main(void) {
    xStartTime = xTaskGetTickCount(); // Obtém tempo atual
    vTaskDelay(pdMS_TO_TICKS(2000)); // Aguarda 2 segundos
    xElapsedTime = xTaskGetTickCount() - xStartTime;

    printf("Tempo decorrido: %lu ticks\n", (unsigned long)xElapsedTime);
}

Aqui, xStartTime e xElapsedTime armazenam valores em ticks do sistema.

4.5. Sufixo MS

O sufixo MS é usado para representar valores em milissegundos.

Exemplo: Definindo tempos em milissegundos

#define TEMPO_DELAY_MS 500

void app_main(void) {
    vTaskDelay(pdMS_TO_TICKS(TEMPO_DELAY_MS)); // Converte para ticks
    printf("Aguardou %d ms\n", TEMPO_DELAY_MS);
}

Aqui, TEMPO_DELAY_MS representa um tempo em milissegundos.

Resumo da Seção

Os sufixos no FreeRTOS ajudam a identificar o propósito de variáveis e funções rapidamente:

5. Prefixos de Retorno de Funções e Variáveis no FreeRTOS

Além dos prefixos usados para categorizar funções (xTask, vTask, xQueue etc.), o FreeRTOS também utiliza prefixos em variáveis e valores de retorno para indicar tipos de dados específicos. Esses prefixos ajudam a identificar rapidamente a natureza da variável ou o tipo de dado que uma função retorna.

Os principais prefixos utilizados no FreeRTOS incluem:

A seguir, exploramos cada um desses prefixos com exemplos práticos.

5.1. Prefixo u (Unsigned)

O prefixo u indica que a variável é um número inteiro sem sinal, ou seja, não pode armazenar valores negativos.

Exemplo: Contador sem sinal

uint8_t uCounter = 0;

void app_main(void) {
    for (uCounter = 0; uCounter < 10; uCounter++) {
        printf("Contador: %u\n", uCounter);
    }
}

Aqui, uCounter é uma variável do tipo uint8_t, que é um inteiro sem sinal de 8 bits.

5.2. Prefixo x (Retorno de Função)

O prefixo x é usado em funções que retornam um valor de status, geralmente do tipo BaseType_t.

Exemplo: Verificando status da criação de uma tarefa

BaseType_t xStatus;

void app_main(void) {
    xStatus = xTaskCreate(vTaskFunction, "Task1", configMINIMAL_STACK_SIZE, NULL, 1, NULL);

    if (xStatus == pdPASS) {
        printf("Tarefa criada com sucesso!\n");
    } else {
        printf("Falha ao criar a tarefa.\n");
    }
}

O xTaskCreate() retorna um BaseType_t, e o valor de retorno xStatus indica se a operação foi bem-sucedida.

5.3. Prefixo v (Void)

O prefixo v é usado para funções que não retornam valores, ou seja, cujo tipo de retorno é void.

Exemplo: Função sem retorno

void vTaskFunction(void *pvParameters) {
    while (1) {
        printf("Executando tarefa...\n");
        vTaskDelay(pdMS_TO_TICKS(1000));
    }
}

A função vTaskFunction() não retorna valores, então segue a convenção v.

5.4. Prefixo ux (Unsigned BaseType_t)

O prefixo ux é usado para variáveis do tipo UBaseType_t, que é um inteiro sem sinal usado para contadores e índices.

Exemplo: Usando UBaseType_t para armazenar um índice

UBaseType_t uxIndex;

void app_main(void) {
    for (uxIndex = 0; uxIndex < 5; uxIndex++) {
        printf("Índice: %u\n", (unsigned int)uxIndex);
    }
}

O UBaseType_t é frequentemente usado para contadores e índices em loops.

5.5. Prefixo e (Enumeração)

O prefixo e indica que a variável é uma enumeração (enum), usada para definir valores simbólicos.

Exemplo: Obtendo o estado de uma tarefa

eTaskState eState;

void app_main(void) {
    eState = eTaskGetState(NULL);
    printf("Estado da tarefa: %d\n", eState);
}

O eTaskGetState() retorna um valor do tipo eTaskState, que segue a convenção e.

5.6. Prefixo p (Pointer)

O prefixo p é usado para variáveis que armazenam ponteiros.

Exemplo: Ponteiro para uma string

char *pMessage = "Olá, FreeRTOS!";

void app_main(void) {
    printf("%s\n", pMessage);
}

O pMessage armazena um ponteiro para uma string.

5.7. Prefixo s (String)

O prefixo s indica que a variável é uma string.

Exemplo: Definição de uma string

const char *sWelcomeMessage = "Bem-vindo ao FreeRTOS!";

void app_main(void) {
    printf("%s\n", sWelcomeMessage);
}

Aqui, sWelcomeMessage representa uma string constante.

5.8. Prefixo pc e pu (Ponteiros para constantes)

Os prefixos pc e pu são usados para indicar ponteiros para constantes, diferenciando entre char e unsigned.

Exemplo: Ponteiro para constante

const char *pcMessage = "Mensagem constante";
const uint8_t *puData;

O pcMessage aponta para uma string constante, enquanto puData pode apontar para um buffer de dados constantes.

5.9. Prefixo c (Char)

O prefixo c indica que a variável é do tipo char.

Exemplo: Armazenando um caractere

char cCharacter = 'A';

void app_main(void) {
    printf("Caractere: %c\n", cCharacter);
}

Aqui, cCharacter armazena um único caractere.

5.10. Prefixo pd (Port Define)

O prefixo pd é usado para constantes internas do FreeRTOS, geralmente definindo estados ou resultados de funções.

Exemplo: Uso de pdPASS e pdFALSE

if (xTaskCreate(vTaskFunction, "Task", configMINIMAL_STACK_SIZE, NULL, 1, NULL) == pdPASS) {
    printf("Tarefa criada com sucesso!\n");
}

if (xSemaphoreTake(xSemaphore, 0) == pdFALSE) {
    printf("Semáforo não disponível.\n");
}

O pdPASS indica sucesso e pdFALSE indica falha na tentativa de captura do semáforo.

6. Boas Práticas na Nomenclatura do FreeRTOS

O uso correto da nomenclatura do FreeRTOS não é apenas uma questão de padronização, mas também uma prática essencial para aumentar a legibilidade, manutenibilidade e clareza do código. Aqui estão algumas boas práticas recomendadas ao trabalhar com o FreeRTOS.

6.1. Use os Prefixos e Sufixos Corretamente

O FreeRTOS adota uma convenção de nomenclatura bem estruturada para ajudar os desenvolvedores a entender rapidamente o propósito de funções e variáveis. Para manter essa clareza:

Use os prefixos apropriados para funções:

• Funções que retornam um status devem começar com x (ex.: xTaskCreate()).
• Funções que não retornam valores devem começar com v (ex.: vTaskDelay()).
• Funções que podem ser chamadas dentro de interrupções devem terminar com FromISR (ex.: xQueueSendFromISR()).

Use os tipos de dados apropriados:

• Utilize BaseType_t e UBaseType_t para variáveis de controle.
• Use TickType_t para valores relacionados ao tempo.
• Manipuladores devem ser sempre declarados com seus respectivos tipos (TaskHandle_t, QueueHandle_t, etc.).

Respeite a nomenclatura dos sufixos:

• Para variáveis que representam tempo, use Ticks ou MS.
• Para ponteiros, use p, pc, ou pu, conforme necessário.
• Para caracteres e strings, use c e s.

6.2. Evite Modificar os Nomes das Funções do FreeRTOS

As funções do FreeRTOS seguem uma convenção bem definida e não devem ser renomeadas. Isso pode causar confusão e dificultar a manutenção do código.

Evite fazer isso:

#define CriarTarefa xTaskCreate  // NÃO RECOMENDADO
CriarTarefa(vTaskFunction, "Task1", configMINIMAL_STACK_SIZE, NULL, 1, NULL);

Forma correta:

xTaskCreate(vTaskFunction, "Task1", configMINIMAL_STACK_SIZE, NULL, 1, NULL);

Alterar nomes de funções pode tornar o código difícil de entender para outros desenvolvedores.

6.3. Nomeie Tarefas, Filas e Recursos de Forma Clara

Sempre nomeie tarefas e recursos do FreeRTOS com nomes descritivos que indiquem sua função.

Evite nomes genéricos:

TaskHandle_t xTarefa1;
QueueHandle_t xFila;

Use nomes descritivos:

TaskHandle_t xTaskSensor;
QueueHandle_t xQueueMensagens;

Nomes descritivos tornam o código mais intuitivo e fácil de depurar.

6.4. Utilize pdMS_TO_TICKS() para Conversão de Tempo

O FreeRTOS mede o tempo em ticks, então é essencial converter corretamente valores de tempo em milissegundos para ticks.

Evite valores fixos em ticks:

vTaskDelay(100); // NÃO RECOMENDADO, pois depende da configuração do sistema

Use pdMS_TO_TICKS():

vTaskDelay(pdMS_TO_TICKS(100)); // Correto e portátil

Isso garante que o código funcione corretamente em diferentes configurações de configTICK_RATE_HZ.

6.5. Declare Variáveis no Escopo Adequado

Variáveis globais podem ser úteis, mas devem ser usadas com cuidado para evitar conflitos e garantir encapsulamento.

Use escopo local sempre que possível:

void vTaskFunction(void *pvParameters) {
    uint32_t ulContador = 0; // Variável local, melhor encapsulamento
    while (1) {
        ulContador++;
        vTaskDelay(pdMS_TO_TICKS(1000));
    }
}

Evite variáveis globais desnecessárias:

uint32_t ulContadorGlobal; // Pode causar conflitos e dificultar depuração

void vTaskFunction(void *pvParameters) {
    while (1) {
        ulContadorGlobal++;
        vTaskDelay(pdMS_TO_TICKS(1000));
    }
}

Sempre prefira variáveis locais, a menos que seja essencial compartilhá-las entre tarefas.

6.6. Documente Seu Código

O FreeRTOS facilita o desenvolvimento de sistemas embarcados, mas um código mal documentado pode se tornar difícil de entender e manter.

Exemplo de código bem documentado:

/**
 * @brief  Função da tarefa que lê sensores periodicamente.
 * @param  pvParameters: Parâmetros da tarefa (não usados aqui).
 */
void vTaskSensor(void *pvParameters) {
    while (1) {
        printf("Lendo sensor...\n");
        vTaskDelay(pdMS_TO_TICKS(1000)); // Espera 1 segundo
    }
}

Uma boa documentação ajuda a equipe de desenvolvimento e facilita futuras manutenções.

6.7. Teste e Valide o Código Com Regularidade

Ao trabalhar com o FreeRTOS, é essencial testar o código regularmente para garantir que ele funcione corretamente e não tenha problemas de concorrência.

Dicas para testes eficazes:

• Use configASSERT() para verificar condições críticas.
• Monitore o uso de memória e pilha (uxTaskGetStackHighWaterMark()).
• Teste cenários de alta concorrência e preempção para evitar deadlocks e starvation.

Conclusão

O FreeRTOS fornece um sistema operacional leve e eficiente para sistemas embarcados, mas seu uso correto exige boas práticas na nomenclatura e estrutura do código. Resumindo:

Use os prefixos e sufixos corretamente para garantir legibilidade.
Não modifique nomes das funções do FreeRTOS para manter compatibilidade.
Dê nomes descritivos a tarefas, filas e semáforos para facilitar manutenção.
Sempre converta milissegundos para ticks com pdMS_TO_TICKS().
Evite variáveis globais desnecessárias para reduzir riscos de conflitos.
Documente e teste seu código regularmente para manter qualidade.

Seguindo essas boas práticas, você garantirá que seus projetos baseados no FreeRTOS sejam mais organizados, confiáveis e fáceis de manter.

The post Introdução à Nomenclatura do FreeRTOS first appeared on MCU & FPGA.