Documentar a HAL/BSP (Software)

[Nyfeu]

🎯 Objetivo

Compreender e documentar a Camada de Abstração de Hardware (HAL) e o Pacote de Suporte à Placa (BSP). O foco é explicar teoricamente como as abstrações em linguagem C (macros, ponteiros e structs) mapeiam os registradores físicos do hardware, criando uma interface limpa (API) para o desenvolvimento das aplicações e roteiros de laboratório.

✍️ Roteiro de Escrita no MkDocs (.md)

1. O Mapa de Memória no Software (memory_map.h)

• Explicar a teoria do Memory-Mapped I/O (MMIO) do ponto de vista do compilador C.
• Documentar como os endereços base definidos no hardware (RTL) são traduzidos para macros no arquivo memory_map.h.
• Explicar arquiteturalmente a obrigatoriedade do uso da palavra-chave volatile em ponteiros ao lidar com registradores de hardware (para evitar que o otimizador do compilador remova leituras/escritas essenciais).

2. A Camada de Abstração de Hardware (HAL)

• Analisar os drivers implementados (ex: hal_uart.c, hal_timer.c, hal_dma.c, hal_vga.c). Documentar o padrão de projeto adotado na construção dessa HAL.
• Explicar como as estruturas (structs) em C são desenhadas para espelhar perfeitamente o layout dos registradores VHDL. Abordar conceitos como alinhamento de memória (barramento de 32 bits) e operações bit a bit (bitmasking e shifting) para acessar flags específicas sem alterar o restante do registrador.

3. Despacho de Interrupções e Operações Base

• Documentar o fluxo da API de software para interrupções (hal_irq.h e irq_dispatch.c): explicar como uma rotina de tratamento de interrupção (ISR) escrita em C é registrada no vetor e efetivamente acionada quando o hardware (PLIC/CLINT) dispara o sinal.
• Explicar brevemente o propósito das bibliotecas de suporte nativo adicionadas ao BSP, como as operações matemáticas (math_ops.c).

📁 Arquivos Fonte Alvo (Para Leitura e Base Técnica)

Definições de Base:

• fpga/sw/platform/bsp/memory_map.h

Drivers Principais (HAL):

• fpga/sw/platform/bsp/hal/hal_uart.c e .h
• fpga/sw/platform/bsp/hal/hal_dma.c e .h
• fpga/sw/platform/bsp/hal/hal_timer.c e .h
• fpga/sw/platform/bsp/hal/hal_vga.c e .h
• (Nota: O hal_npu.c pode ser referenciado aqui, mas seu detalhamento matemático profundo deve ficar a cargo da documentação específica da NPU).

Tratamento e Suporte:

• fpga/sw/platform/bsp/irq/irq_dispatch.c
• fpga/sw/platform/bsp/math_ops.c e .h

⚠️ Notas de Rigor e Qualidade

• Rigor de Engenharia de Software: Evite fazer um "tutorial de linguagem C". O texto deve focar na interface hardware-software. Como a manipulação de um ponteiro na linha 15 do C gera um pulso de write_enable no barramento físico da FPGA? É essa conexão que enriquece o TCC e a plataforma didática.