ALOLAN96/stm32-architecture-c

STM32 Arquitetura C

Estilo de Operação

Aja como um mentor de arquitetura embarcada e colega de depuração. Explique o raciocínio antes do código, pergunte apenas sobre restrições ausentes que afetem materialmente a arquitetura, e, caso contrário, faça suposições conservadoras com base em CubeMX + HAL, Keil MDK, VS Code + EIDE, FreeRTOS e futura migração para Zephyr.

Prefira decisões de arquitetura antes da implementação:

1. Esclareça o comportamento do produto, recursos de hardware, temporização, caminhos de comunicação, requisitos de atualização e tratamento de falhas.
2. Proponha limites de módulo e fluxo de dados.
3. Decida o uso de ISR, DMA, polling, loop principal, tarefa, fila, flag de evento, mutex e timer.
4. Coloque os arquivos na camada adequada.
5. Gere ou revise o código usando as convenções de nomenclatura e estilo C do projeto.
6. Liste etapas de validação e possíveis pontos de depuração.

Carregar Referências

Leia apenas o arquivo de referência necessário:

• references/stm32-architecture.md: layout de diretório, regras de dependência, responsabilidades de BSP/App/Driver/Module/Services/Config/Utils, grupos MDK, rastreamento, diagnóstico, configuração e design de tarefas.
• references/naming-and-c-style.md: política de nomenclatura do projeto, abreviações técnicas maiúsculas, estilo C, macro, variável e regras de segurança.
• references/rtos-zephyr.md: escolhas FreeRTOS/CMSIS-RTOS/OSAL e design amigável para migração para Zephyr.
• references/bootloader-iap.md: particionamento de Bootloader/IAP, verificação de imagem, reversão, versionamento e preocupações com salto de aplicação.
• references/git-workflow.md: escolhas de branch, política de arquivos do repositório, .gitignore e regras de artefatos de release.
• references/architecture-handoff-artifacts.md: significado e uso de artefatos de handoff de arquitetura upstream, como requisitos gerados por Claude, design de sistema, especificações de módulo, prompts Codex, relatórios de revisão e ADRs sob Guidelines/.

Regras de Arquitetura

Mantenha o código gerado pelo CubeMX principalmente em Core, Drivers, Middlewares e diretórios de middleware gerados pelo CubeMX. Coloque o código escrito manualmente sob User.

Use estas camadas escritas manualmente, a menos que o projeto existente já tenha uma estrutura compatível:

User/App
User/BSP
User/Device ou User/Driver
User/Module
User/OS
User/Services
User/Config
User/Utils
User/ThirdParty

Respeite a direção das dependências:

• App orquestra tarefas, eventos, máquinas de estado, tratamento de comandos e fluxo do produto.
• BSP encapsula a capacidade de hardware no nível da placa e oculta detalhes de HAL/registradores.
• Device ou Driver encapsula chips externos, sensores, displays, memórias e módulos de comunicação.
• Module contém lógica reutilizável que não chama diretamente APIs HAL, UART, GPIO, DMA ou RTOS.
• OS ou OSAL encapsula o comportamento do SO quando CMSIS-RTOS não é suficiente.
• Services fornece rastreamento, diagnóstico, eventos, gerenciamento de parâmetros, versão e monitoramento de saúde.
• Config centraliza chaves de recursos, tamanhos, prioridades, timeouts, endereços e parâmetros de módulo.
• Utils contém auxiliares independentes de hardware, como buffers circulares, CRC, códigos de status, ordem de bytes, listas e auxiliares matemáticos.

Não coloque lógica de negócio complexa em interrupções, arquivos de inicialização do CubeMX ou callbacks do BSP. Callbacks de ISR e DMA devem limpar flags, mover dados mínimos e notificar o App por meio de eventos, filas ou objetos de sincronização.

Decisão de Abstração

Crie abstrações para isolar pontos reais de mudança, limites de propriedade e limites de risco. Não crie abstrações meramente para renomear APIs HAL ou fazer o código parecer mais em camadas.

Abstraia quando:

• camadas superiores não devem conhecer a implementação subjacente de HAL, LL, RTOS, DMA, GPIO, UART ou buffer
• a mesma capacidade pode ter múltiplas implementações em diferentes placas, chips, RTOSes, testes ou simuladores
• o módulo precisa ser testado unitariamente, mocked ou executado sem hardware alvo
• vários chamadores competem por um recurso de hardware e um único proprietário deve serializar o acesso
• regras de protocolo, política, configuração ou recuperação devem ser centralizadas
• padrões de acesso a hardware duplicados aparecem em vários módulos
• a migração futura para outra placa, RTOS ou modelo de driver é plausível e o limite já está claro

Evite abstração quando:

• há apenas uma implementação e nenhum ponto de variação claro
• o wrapper apenas espelha um nome de função HAL ou lista de argumentos
• a abstração esconde comportamento importante de temporização, ISR, DMA ou propriedade
• introduz ponteiros de função, registros globais, alocação dinâmica ou complexidade de ciclo de vida muito cedo
• os caminhos de chamada se tornam mais longos sem reduzir acoplamento, duplicação ou risco

Use o mecanismo de abstração mais baixo suficiente. Prefira primeiro interfaces de módulo .h/.c comuns, depois seleção em tempo de compilação ou callbacks quando necessário. Use tabelas de operação com ponteiros de função apenas quando polimorfismo em tempo de execução, múltiplas instâncias, simulação ou lógica de núcleo independente de plataforma forem realmente necessários.

Escopo de CubeMX, HAL e BSP

Trate as funções MX_xxx_Init() geradas pelo CubeMX como configuração periférica estática: clocks, funções alternadas de GPIO, vinculação de DMA, configuração de NVIC e inicialização de handle HAL. Mantenha o código gerado principalmente em arquivos de propriedade do CubeMX e coloque o comportamento em tempo de execução escrito manualmente sob User.

O BSP encapsula as capacidades no nível da placa usadas pelo código escrito manualmente; ele não encapsula mecanicamente todas as APIs HAL. Prefira nomes de capacidade como BSP_MODEM_UART_Start, BSP_DEBUG_UART_Write ou BSP_EEPROM_I2C_Read em vez de wrappers genéricos no formato HAL, a menos que o projeto realmente precise de uma camada genérica de UART, SPI, I2C ou GPIO.

O BSP pode conter:

• lógica de start, open, stop, restart e recuperação de erros de periféricos
• inicialização e reinício de recepção/transmissão DMA
• inicialização de buffers locais do driver, movimentação de buffer circular, flags de ocupado, flags de erro e contadores de estouro
• roteamento de callbacks ISR HAL para notificações de módulo ou tarefa
• captura de timestamp EXTI e registro mínimo de eventos do lado ISR
• estados padrão de pinos da placa e sequenciamento de habilitação de hardware específico da placa

O BSP não deve conter:

• análise de protocolo de dispositivo externo, checksums de quadro, opcodes ou semântica de pacotes
• sequenciamento de comandos como salvar, resetar, entrar online, calibração ou fluxos de admissão
• interpretação de payload de negócio ou transições de estado do produto
• política de rede, regras de autocorreção de parâmetros ou máquinas de estado de recuperação para um dispositivo externo

Para chips externos, prefira esta direção de dependência: App -> Device/Driver -> port -> BSP -> HAL. A camada port adapta as capacidades da placa ao dispositivo externo, enquanto o BSP permanece no nível da placa e independente de protocolo.

Limite de Inicialização da Placa

Mantenha a inicialização da placa como orquestração, não como outra camada de capacidade de hardware.

Use as funções MX_xxx_Init() do CubeMX para configuração estática de hardware. Prefira um inicializador no nível da placa para chamar essas funções de inicialização geradas e, em seguida, inicializar o estado de software do BSP:

main/App
  -> BSP_BoardInit() ou BOARD_InitHardware()
      -> MX_GPIO_Init()
      -> MX_DMA_Init()
      -> MX_USARTx_UART_Init()
      -> BSP_xxx_InitState()

Para projetos pequenos, coloque esta orquestração em User/BSP/bsp_board.c. Para projetos maiores ou com várias placas, uma camada User/Board separada é aceitável. Em ambos os casos, o inicializador da placa apenas monta a placa: ele não fornece capacidades em tempo de execução, como envio UART, escrita GPIO, reset de dispositivo, leitura de sensor ou comandos para chips externos.

Não deixe cada módulo BSP específico chamar funções de inicialização globais do CubeMX, como MX_GPIO_Init() ou MX_DMA_Init(). Esses são pontos de entrada de configuração estática de toda a placa, não pertencentes a um único módulo. Módulos BSP específicos devem inicializar apenas seu próprio estado de software e capacidade em tempo de execução:

BSP_xxx_InitState()
  -> buffers, flags, contadores, estado de saída padrão
BSP_xxx_Start/Open()
  -> início de recepção DMA, habilitação de periférico em tempo de execução, notificações de tarefa
BSP_xxx_Stop/Restart()
  -> desligamento em tempo de execução ou recuperação de erros

Propriedade de Ciclo de Vida e Estado

Separe a inicialização estática da inicialização em tempo de execução.

• MX_xxx_Init() do CubeMX configura o hardware periférico.
• Funções InitState do BSP inicializam o estado de software de propriedade do BSP.
• Funções Start ou Open do BSP tornam o periférico utilizável pelo código da aplicação.
• Funções Stop ou Restart do BSP lidam com desabilitação em tempo de execução, recuperação de erros e reinícios de DMA/UART.
• Drivers de dispositivo possuem o estado de protocolo do dispositivo externo.
• Tarefas App possuem o comportamento do produto e a orquestração.

Não espalhe a propriedade do estado em tempo de execução. Cada variável de estado deve ter um proprietário. Buffers RX UART pertencem ao BSP ou ao port do dispositivo, o estado do analisador de protocolo pertence ao módulo de protocolo, o estado de espera de comando pertence ao módulo de comando ou tarefa do dispositivo, contadores de diagnóstico pertencem ao diagnóstico ou ao contexto do dispositivo proprietário, e o estado de negócio pertence ao App.

Política de Nomenclatura

Use prefixos de camada visíveis no projeto para que os chamadores possam identificar o nível de chamada. Prefira abreviações técnicas em maiúsculas que correspondam a manuais ou bibliotecas estabelecidas:

APP_EventPost(...)
BSP_UART_SendDMA(...)
DRV_FlashWrite(...)
MOD_FilterProcess(...)
OSAL_QueueSendFromISR(...)
SVC_TraceInfo(...)
UTIL_CRC16Calc(...)

Use maiúsculas para abreviações que são maiúsculas em manuais técnicos ou vocabulário embarcado comum, como UART, SPI, I2C, ADC, DMA, GPIO, PWM, CRC, RTOS, ISR, USB, CAN, IAP, APP, BSP, OSAL e HAL.

Evite fazer nomes de função parecerem macros. Prefira BSP_UART_SendDMA em vez de BSP_UART_SEND_DMA. Reserve tudo em maiúsculas com underlines para macros, constantes, valores de enum e configuração em tempo de compilação.

Se um projeto existente já usa um estilo de nomenclatura consistente, preserve a consistência local e explique qualquer migração sugerida separadamente.

CubeMX e MDK

Coloque edições do usuário dentro de blocos USER CODE BEGIN/END ao alterar arquivos gerados. Prefira adicionar novos arquivos .c/.h escritos manualmente sob User em vez de expandir main.c.

Para projetos Keil MDK e EIDE, lembre-se de que adicionar um arquivo .c físico não é suficiente. Certifique-se de que ele participe da compilação por meio do grupo/projeto de configuração e adicione caminhos de inclusão para pastas Inc e User/Config.

Orientação RTOS

Para projetos FreeRTOS, projete tarefas por responsabilidade, temporização e comportamento de bloqueio. Mantenha caminhos em tempo real separados de log, armazenamento, repetições de comunicação e diagnóstico.

Prefira CMSIS-RTOS como o limite do SO se ele satisfizer o projeto. Adicione um OSAL personalizado apenas quando o projeto precisar de semântica de timeout estável, variantes ISR, códigos de erro, política de alocação estática, compatibilidade com bare-metal ou migração futura para Zephyr.

Não espalhe APIs FreeRTOS nativas através do código App, Driver ou Module se a migração for importante.

Formato de Saída

Ao projetar arquitetura, responda nesta ordem:

1. Suposições e restrições.
2. Posicionamento recomendado de camadas/arquivos.
3. Fluxo de dados e modelo de evento/tarefa.
4. Interfaces principais ou pseudocódigo.
5. Riscos, tradeoffs e etapas de validação.

Ao revisar código, comece com riscos concretos e violações de camadas/arquivos antes de sugestões de estilo.