Skill de Padrões de Performance
Um catálogo crescente de padrões de código bem conhecidos que causam problemas de desempenho, com sinais de detecção e playbooks de resolução para cada um. O catálogo central de padrões se concentra em código de CPU x86, com roteamento de plataforma para ambientes Windows, WSL Linux, Linux nativo e CUDA/NVIDIA.
O conhecimento de otimização é portável quando o hardware é o mesmo. O que muda por plataforma são os mecanismos: vocabulário de profiler, flags de compilador, formato de debug-info, primitivas de sincronização, detecção de recursos da CPU e se o gargalo está no código da CPU host ou no trabalho do dispositivo CUDA.
Etapa 0 — Roteie a plataforma
Se o usuário mencionar WSL, Linux, CUDA, NVIDIA, GPU, Nsight,
incompatibilidade de driver/toolkit, contêineres ou a plataforma não estiver clara, leia
references/platform-routing.md primeiro.
Em seguida, carregue a referência específica da plataforma:
| Plataforma / sintoma | Leia |
|---|---|
| Performance CPU C/C++ nativa Windows | PORTING-NOTES.md |
| Performance CPU Linux WSL | references/wsl-linux.md, depois references/linux-native.md |
| Performance CPU Linux nativa | references/linux-native.md |
| Configuração CUDA/NVIDIA ou performance GPU | references/cuda.md |
Use scripts/collect-perf-env.ps1 no Windows e
scripts/collect-perf-env.sh dentro do WSL/Linux nativo quando o ambiente for
o problema ou o usuário não fornecer contexto suficiente sobre toolchain/profiler.
Como usar este skill
Etapa 1 — Carregue o arquivo certo para seu contexto
| Contexto | Leia este arquivo |
|---|---|
| Você tem saída de profile (VTune, AMD uProf, ETW/WPA, perf, flamegraph, resumo Nsight etc.) | triggers/from-profile.md |
| Você está lendo código-fonte existente e ainda não tem dados de profile | triggers/from-source.md |
| Você está escrevendo código novo C/C++ ou SIMD sensível a desempenho | guidelines/new-code.md |
Os arquivos de gatilho cobrem todos os mesmos padrões; eles estão separados para que você carregue
apenas o que é relevante. guidelines/new-code.md é uma lista de verificação para escrita —
carregue-o em vez de um arquivo de gatilho ao gerar código novo, não ao revisá-lo.
Etapa 2 — Identifique o padrão correspondente
Cada arquivo de gatilho contém uma tabela compacta e descrições breves — o suficiente para decidir se o código ou profile corresponde a um padrão conhecido.
Etapa 3 — Leia o arquivo de detalhes do padrão
Quando um padrão corresponder, leia o arquivo correspondente de patterns/. Não
tente corrigir de memória.
Etapa 4 — Aplique a correção e verifique
Siga as instruções passo a passo e o método de verificação no arquivo do padrão, usando os mecanismos da plataforma do arquivo de roteamento carregado na Etapa 0.
Vários padrões podem ser aplicados simultaneamente. Verifique todas as correspondências plausíveis antes de escolher uma.
Módulos de biblioteca reutilizáveis
Estes guias de implementação independentes estão disponíveis para qualquer agente que trabalhe neste skill, não apenas ao seguir um padrão específico. Carregue o arquivo relevante diretamente se a capacidade for necessária.
| Módulo | O que fornece |
|---|---|
library/cpu-dispatch.md | Detecção de recursos da CPU em tempo de execução e seleção de variantes no Windows. Dispatch manual por ponteiro de função apenas — target_clones não está disponível no alvo PE/COFF (sem IFUNC). Abrange __builtin_cpu_supports, o caminho explícito __cpuid/_xgetbv e __attribute__((target(...))) por variante. Neutro de fabricante (Intel + AMD). Use sempre que uma função tiver múltiplas implementações com diferentes níveis de desempenho que precisam ser conectadas em tempo de execução. |
patterns/simd-upconversion-impl.md | Algoritmo zipper completo passo a passo para dobrar a largura do registrador vetorial em intrínsecos (SSE→AVX2 ou AVX2→AVX-512); modelo de acumulador AVX-512; checklist pós-transformação (guards CPUID, vzeroupper, atributos de destino). |
patterns/fast-crc32c-impl.md | Biblioteca CRC32C pronta para uso: fusão AVX-512 VPCLMULQDQ, multi-acumulador SSE4.2 + PCLMULQDQ, fallback em C puro. Dispatch de CPU em tempo de execução incluído. Use sempre que um novo código CRC32C for necessário ou uma implementação existente for o gargalo. |
references/platform-routing.md | Roteie solicitações Windows / WSL / Linux nativo / CUDA antes de aplicar um padrão. |
references/cuda.md | Configuração CUDA e triagem de desempenho: visibilidade do driver/toolkit, Nsight Systems vs Nsight Compute, limites de GPU WSL. |
Integração entre skills
Skills de coleta de dados/profiler podem invocar este skill após identificar um padrão conhecido. Este skill também funciona de forma independente a partir de código-fonte, trechos de profiler ou saída de sondagem de ambiente.
Status do skill
Portado e revisado para Windows C/C++ nativo, depois estendido com notas de roteamento
para ambientes WSL Linux, Linux nativo e CUDA/NVIDIA. Os seguintes arquivos
principais estão presentes: este SKILL.md, PORTING-NOTES.md,
triggers/from-source.md, triggers/from-profile.md, guidelines/new-code.md,
design.md, library/cpu-dispatch.md, fontes da biblioteca CRC32C, referências
de plataforma, testes de benchmark e todos os arquivos de padrão:
parallel-accumulator,missing-vzeroupper,missing-restrictttas,false-sharing,per-cpu-stats,cold-path-annotationcv-thundering-herd,mutex-to-rwlock,simd-sortsimd-upconversion+simd-upconversion-implfast-crc32c+fast-crc32c-impllibrary-version-upgrade
references/library-versions.md mantém intencionalmente entradas de DLL de terceiros não verificadas
em uma tabela TODO; não promova estas a recomendações sem verificação de fonte primária
e medição no Windows.