Mailboxes no Nucleus SE: Guia Prático de Configuração e Uso

Veja a série RTOS Revealed

Mailboxes foram introduzidas em artigo anterior como um dos mecanismos mais simples de comunicação inter-tarefa no Nucleus SE — logo após signals. Elas oferecem forma de baixo custo e altamente flexível de transferir dados simples entre tarefas.

Usando Mailboxes

No Nucleus SE, mailboxes são definidas em tempo de build. Máximo de 16 mailboxes podem ser configuradas por aplicação. Se você configurar zero mailboxes, o compilador omite todas estruturas de dados e código API relacionados, mantendo o binário enxuto.

Uma mailbox é essencialmente um slot de armazenamento que pode conter uma única variável do tipo ADDR. Apenas uma tarefa pode escrever em uma mailbox por vez. Uma vez cheia, tentativas subsequentes de escrita falharão até que a mailbox seja lida ou resetada. Dependendo das opções da API, tentativa de escrever em mailbox cheia pode retornar erro ou suspender a tarefa até espaço ficar disponível.

Mailboxes vs. Queues

Alguns sistemas operacionais substituem mailboxes por queue de entrada única. Embora queue possa imitar comportamento de mailbox, carrega overhead extra — ponteiros head e tail, estruturas de dados maiores, mais caminhos de código — levando a maior uso de memória e tempo de execução.

No Nucleus SE, você pode escolher entre mailboxes ou queues. Se seu design usa muitas queues mas poucas mailboxes, trocar mailbox por queue aumentará ligeiramente tamanho de dados mas removerá código API específico de mailbox, simplificando manutenção. É fácil testar ambas configurações para comparar pegada de memória e performance.

Queues serão cobertas em artigo futuro.

Configurando Mailboxes

Número de Mailboxes

A macro-chave em nuse_config.h é NUSE_MAILBOX_NUMBER. Valor padrão é 0, significando nenhuma mailbox habilitada. Você pode defini-lo para qualquer inteiro entre 1 e 16. Verificação em tempo de compilação em nuse_config_check.h disparará erro se valor estiver fora de faixa.

Definir valor não-zero ativa subsistema de mailbox: estruturas de dados são dimensionadas, e símbolos de habilitação da API são processados.

Habilitações da API

Cada chamada de API de mailbox tem #define correspondente em nuse_config.h:

• NUSE_MAILBOX_SEND
• NUSE_MAILBOX_RECEIVE
• NUSE_MAILBOX_RESET
• NUSE_MAILBOX_INFORMATION
• NUSE_MAILBOX_COUNT

Por padrão todas são FALSE, desabilitando a chamada e sua implementação. Para usar uma API, habilite a macro correspondente definindo como TRUE. Habilitar API sem mailboxes configuradas causará erro de compilação (exceto NUSE_Mailbox_Count(), sempre disponível). Usar API desabilitada produz erro de link.

/* Número de mailboxes no sistema – 0-16 */ #define NUSE_MAILBOX_NUMBER 0 /* Service call enablers: */ #define NUSE_MAILBOX_SEND FALSE #define NUSE_MAILBOX_RECEIVE FALSE #define NUSE_MAILBOX_RESET FALSE #define NUSE_MAILBOX_INFORMATION FALSE #define NUSE_MAILBOX_COUNT FALSE 

Chamadas de Serviço de Mailbox

Nucleus SE oferece nove chamadas de serviço relacionadas a mailbox. As implementadas no SE são:

• NUSE_Mailbox_Send() – escrever mensagem em mailbox.
• NUSE_Mailbox_Receive() – ler mensagem de mailbox.
• NUSE_Mailbox_Reset() – limpar mailbox sem suspender tarefas.
• NUSE_Mailbox_Information() – consultar status de mailbox.
• NUSE_Mailbox_Count() – retornar número de mailboxes configuradas.

Outras funções como criação, deleção, recuperação em massa e broadcast não são implementadas no SE.

Operações de Escrita e Leitura

Mailboxes suportam duas operações centrais: envio (escrita) e recebimento (leitura). Ambas APIs estão disponíveis no Nucleus RTOS e Nucleus SE, com diferenças em flexibilidade e tratamento de erro.

Enviando para Mailbox

No Nucleus RTOS a chamada NU_Send_To_Mailbox suporta suspensão indefinida ou temporizada se mailbox estiver cheia. Nucleus SE oferece versão simplificada: suspensão é opcional e timeouts não são suportados.

Protótipo de exemplo para Nucleus SE:

STATUS NUSE_Mailbox_Send(NUSE_MAILBOX mailbox, ADDR *message, U8 suspend);

Parâmetros:

• mailbox – índice da mailbox.
• message – ponteiro para variável ADDR.
• suspend – NUSE_NO_SUSPEND ou NUSE_SUSPEND.

Valores de retorno incluem NUSE_SUCCESS, NUSE_INVALID_MAILBOX, NUSE_MAILBOX_FULL, e NUSE_MAILBOX_WAS_RESET.

Visão Geral da Implementação

Quando bloqueio é desabilitado, rotina verifica flag de status da mailbox. Se mailbox vazia, escreve dados e marca mailbox como cheia; caso contrário retorna NUSE_MAILBOX_FULL.

Com bloqueio habilitado, código loopa até mensagem ser postada com sucesso ou tarefa acordada por operação de receive. Se tarefa está suspensa na mailbox, é resumida imediatamente após send bem-sucedido.

Trecho a seguir demonstra lógica central quando bloqueio habilitado (simplificado para legibilidade):

do { if (!NUSE_Mailbox_Status[mailbox]) { // Mailbox vazia – armazena dados e acorda tarefa esperando se houver. } else if (suspend == NUSE_NO_SUSPEND) { return NUSE_MAILBOX_FULL; } else { // Suspende tarefa até mailbox ficar vazia. } } while (suspend == NUSE_SUSPEND); 

Em resumo, API de mailbox equilibra simplicidade e flexibilidade, permitindo desenvolvedores escolher entre falha imediata ou suspensão de tarefa baseada nos requisitos de timing da aplicação.