lgcosta/pf-linux-port
1
0 Fork 0
mirror of https://github.com/lgcosta/pf-linux-port.git synced 2026-11-13 02:58:03 -03:00
Code Issues Packages Projects Releases Wiki Activity
Files
131672d6ce6512d7dbdfcda33d17883222724b35
pf-linux-port/docs/pt-BR/build.md
T
lgcosta dff2185b20 Docs: bring the documentation in line with the code 
- Demo docs replaced by the screencast docs (single source of truth): the
  legacy demo-session.sh/demo-record.py and the v0.9 renderer were removed
  instead of being kept as a second convention.
- feature-matrix: stale 'M2-in-progress' vocabulary gone; the rows the 15
  gates prove now say VERIFIED-in-VM and name the gate; af-to is now an
  explicit non-goal row (INET6 0 in this build).
- guide: the queues/divert/pflog sections described a state that no longer
  exists (priq-only, divert dropping packets, pflog logging nothing); they
  now describe the shipped behaviour.
- vm-lab: the 15 real gates with what each proves, 15/15 green, and the
  pf0 -> cli/srv/gw2 ssh setup the screencasts rely on.
- install/build: pdivert and pflogd are built and ported (docs said
  otherwise); module object list now includes hfsc.c, fq_codel.c, pfk_pflog.c;
  the screencast pipeline is an optional build stage.
- pf-guide: the 'M2 scope only' framing is gone; honest gaps listed.
- caveats: three new sections about the screencast pipeline (MiniMax video
  generation blocked by the account tier, narration as a separate track, a
  video frame is not a verdict).
- porting-notes: what the recording taught us.
- README/README.pt-BR: status, milestones, layout and video section updated.

All internal doc links verified.
2026-11-12 11:51:25 -03:00

147 lines
7.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Pipeline de build em detalhe
English: [docs/en/build.md](../en/build.md).
Receita rápida: [install.md](install.md). Esta página explica *o que cada
etapa faz* e *o que já foi realmente exercitado*.
Tudo abaixo roda no host de build (o laptop); a bancada de VMs (host
separado, "deb") só recebe artefatos — ver [vm-lab.md](vm-lab.md).
## 0. Pré-requisitos
De `docs/pt-BR/install.md`: gcc ≥ 15, GNU make, bison (flex não é
necessário — o `parse.y` do OpenBSD traz um `yylex` escrito à mão), `bc`,
rsync, `glibc-static` para o pfctl estático, root para `insmod`. A árvore do
kernel é esperada em `../linux-7.3.4` (troque com `KERNELDIR=`; o `Makefile`
raiz usa `$(HOME)/lab/linux_kernel/linux-7.3.4`).
## 1. Baixar + verificar as fontes do OpenBSD — `scripts/fetch-sources.sh`
- Baixa `sys.tar.gz` e `src.tar.gz` do mirror primário
`https://openbsd.c3sl.ufpr.br/pub/OpenBSD/8.0/`, com fallback para
`cdn.openbsd.org`.
- Confere o sha256 contra os valores de `VERSIONS` (sys: `964b1aed…`, src:
`9984c74f…`); tarball já em cache com hash correto é pulado.
- Destino: `_vendor/openbsd/` (fora do git).
## 2. Vendorize — `scripts/vendorize.sh`
Extrai **só os arquivos que o port consome** para `_vendor/upstream/`
(fora do git): a lista `sys/net/pf*.c|h`, `ifq/hfsc/fq_codel/ip_pflog/
ip_divert`, `radix/rtable/toeplitz`, `crypto/{md5,sha2,siphash}`,
`sys/sys/*.h` e `sbin/pfctl/*` + headers (arrays `SYS_K`/`SRC_K`). Em
seguida registra o tag `$OpenBSD: …$` de cada arquivo em
`_vendor/upstream/IDS.txt` — a base forense de toda linha portada e de
futuros rebases.
## 3. Staging para o port — `scripts/stage-port.sh` (porting determinístico)
O `stage-port.sh` transforma os arquivos upstream pristinos nos arquivos em
`module/`:
1. todo `#include` é substituído por `pfk.h` + os headers `pfvar` staged
(os ramos de kernel são selecionados com `-D_KERNEL=1`);
2. o programa de renomeação compartilhado (`pf_sed`) resolve colisões de
nomes BSD↔Linux (`struct ip` → `struct pf_ip`, `ifnet` → `pfk_ifnet`,
`ip_output` → `pfk_ip_output`, atribuições a `sa_len` removidas, …);
3. **cada execução é anexada a `docs/porting-notes.md`** — esse arquivo é o
log de staging, não prosa.
Os arquivos portados são então commitados e editados à mão na árvore; o
re-staging serve só para perícia (`stage-port.sh --diff <arquivo>` compara a
nossa cópia com o texto upstream pristino). Radix/rtable/siphash/toeplitz
ficam de fora do staging automático de propósito (portados à mão).
## 4. Kernel — `scripts/build-kernel.sh` (+ `kernel-config.sh`)
- `kernel-config.sh`: parte de `defconfig` quando não há `.config` e então
ajusta (idempotente, via `scripts/config` + `make olddefconfig`):
`VIRTIO_BLK/PCI/NET=y`, `EXT4_FS=y`, `NETFILTER=y`,
`NETFILTER_ADVANCED`, `NET_SCHED=y`, `INET=y`, `IPV6=y`,
`SERIAL_8250(+CONSOLE)=y` — ou seja, tudo que o boot direto da VM pf0
precisa **sem initrd**. `kernel-config.sh test` habilita também
`DEBUG_INFO` + `DEBUG_KMEMLEAK` para builds de soak.
- `build-kernel.sh`: `make -j(nproc-2) bzImage modules_prepare`, garante que
`Module.symvers` exista (copia `vmlinux.symvers` — o kbuild não escreve o
primeiro) e que `scripts/module.lds` exista; depois deposita os artefatos
de boot em `out/`: `linux-<ver>-bzImage`, `System.map`, `.config`,
`kernelversion`, `bzImage.sha256`. Termina com
`KERNEL_BUILD_OK <kernelrelease>`.
- **Hoje não há patch de core**: `patches/kernel/` não tem nenhum
`000N-*.patch` (ver [patches.md](patches.md)).
## 5. Módulo — `scripts/build-module.sh`
`make -C "$KERNELDIR" M=module` → `module/pf.ko` (um único módulo: a
interface BSD `ifq`/`pfq` mora dentro dele, não é um qdisc `tc` separado). O
script prepara sozinho `Module.symvers` / `modules_prepare`. Lista de objetos
(`module/Makefile`): engine portado (`pf.c`, `pf_ioctl.c`, `pf_norm.c`,
`pf_if.c`, `pf_lb.c`, `pf_ruleset.c`, `pf_table.c`, `pf_osfp.c`,
`pf_syncookies.c`, `divert_sock.c`, `pfk_pflog.c`, `hfsc.c`, `fq_codel.c`) +
camada de compat (shim mbuf, glue de kernel, if/ip4/ip6/pcb/xmit/ifq, crypto,
radix, subr_tree) + `pfk_mod.c`/`pfk_hooks.c`. As flags de compilação definem
`PFLINUX=1` e `_KERNEL=1`. Termina com `MODULE_BUILD_OK`.
`insmod module/pf.ko` cria `/dev/pf` (0600) e registra os hooks netfilter; o
`dmesg` mostra linhas `pfk: …` (ver [caveats.md](caveats.md) para o que o
caminho de dados faz).
## 6. Userland — `make -C tools`
Alvos (de `tools/Makefile`): `pfctl`, `pdivert`, `pflogd`, `abitest`, `abi`,
`test`, `clean`.
- `pfctl` — as fontes do OpenBSD 8.0 compiladas contra os headers de ABI
copiados; o resultado é um **binário estático** em `tools/out/pfctl`.
Cada desvio do upstream está listado em `tools/UPSTREAM.md` (7 edições
marcadas; o resto é o conjunto de headers/fontes de compat).
- `abi` — compila `abitest` (userland) e `abitest-module` (mesma tabela com
os headers de compat de kernel), despeja as tabelas de tamanho/offset de
cada struct e as compara com `diff`; divergência = ABI de ioctl quebrada.
`out/abi-*.tbl` são as entradas de referência.
- `test` — checagens de parse offline: roda `pfctl -n -f` sobre
`tools/tests/*.conf` (básico / traduções / filas+scrub / anchor / negativa
`broken.conf`). É userland puro; não precisa de `/dev/pf`.
- `pdivert` — o relay de divert, compilado a partir de `tools/pdivert/`. Ele
fala com a família de sockets `AF_DIVERT` que o módulo registra em runtime
(`socket(PF_DIVERT=32, SOCK_RAW, IPPROTO_DIVERT=254)`); o gate
`11-divert.sh` prova a ida e a volta.
- `pflogd` — lê `/dev/pflog` e escreve um pcap DLT_PFLOG cujo layout de
registro é byte a byte compatível com o `pflog(4)` do OpenBSD; gate
`12-pflog.sh`.
## 7. Screencasts — `scripts/screencast/build-all.sh`
Não faz parte do build do kernel, mas faz parte da entrega. O pipeline:
| Etapa | Script | O que faz |
|---|---|---|
| texto da narração | `make_narration.py` | escreve `scripts/screencast/narration/<fase>.{en,pt}.json` (um segmento por batida da sessão) |
| voz | `make_audio.py` | TTS do MiniMax, um MP3 por segmento, voz feminina por idioma |
| sessão | `record.py` | sessão SSH real no lab: comandos digitados tecla a tecla, capturada como asciicast v2 |
| vídeo | `render_video.py` | reproduz a captura por um emulador de terminal, desenha o diagrama do lab, queima as legendas |
| montagem | `assemble.py` | mixa a narração na linha do tempo |
| filme completo | `join.py` | emenda as fases com crossfade sobre cartões de capítulo |
`make screencast` (ou o script) roda tudo; precisa de `MINIMAX_API_KEY` e do
lab no ar. Detalhes: [screencast.md](screencast.md).
## 8. `Makefile` raiz
`make module | tools | kernel | vm | vm-destroy | test | screencast | docs | clean` —
wrappers finos sobre os scripts acima. `make test` roda a suíte em VM
([vm-lab.md](vm-lab.md)); `make screencast` renderiza os vídeos;
`make docs` apenas lista o conjunto bilíngue.
## O que já foi exercitado vs. não
- As etapas 1–6 foram rodadas repetidamente no host de build (há artefatos
na árvore: `out/`, `module/pf.ko`, `tools/out/{pfctl,pdivert,pflogd}`), e os
scripts acima foram verificados linha a linha para este documento.
- A etapa 7 (os screencasts) foi rodada de ponta a ponta para as sete fases
nos dois idiomas; os vídeos estão em `out/screencast/{en,pt}/`.
- Uma execução **de ponta a ponta a partir de clone limpo**
(`quickstart-check.sh`, tarefa T19 do plano) **ainda não** foi feita;
trate a sequência exata do install.md como "conforme projetada e conforme
o último estado por milestone", não como verificada em CI.
Reference in new issue View Git Blame Copy Permalink