1.. SPDX-License-Identifier: GPL-2.0 2 3KVM x86 4======= 5 6Prefácio 7-------- 8 9O KVM se esforça para ser uma comunidade acolhedora; as contribuições de 10recém-chegados são valorizadas e incentivadas. Por favor, não se sinta 11desanimado ou intimidado pela extensão deste documento e pelas muitas 12regras/diretrizes que ele contém. Todo mundo comete erros e todo mundo já foi um 13novato em algum momento. Desde que você faça um esforço honesto para seguir as 14diretrizes do KVM x86, seja receptivo ao feedback e aprenda com os erros que 15cometer, você será recebido de braços abertos, não com tochas e forquilhas. 16 17(TL;DR) 18-------- 19Testes são obrigatórios. Seja consistente com os estilos e padrões estabelecidos. 20 21Árvores 22------- 23O KVM x86 está atualmente em um período de transição: deixando de fazer parte da 24árvore principal do KVM para se tornar "apenas mais uma arquitetura KVM". Como tal, 25o KVM x86 está dividido entre a árvore principal do KVM, 26``git.kernel.org/pub/scm/virt/kvm/kvm.git``, e uma árvore específica para KVM x86, 27``github.com/kvm-x86/linux.git``. 28 29De modo geral, as correções (fixes) para o ciclo atual são aplicadas diretamente 30na árvore principal do KVM, enquanto todo o desenvolvimento para o próximo ciclo 31é roteado através da árvore do KVM x86. No caso improvável de uma correção para o 32ciclo atual ser roteada através da árvore do KVM x86, ela será aplicada à branch 33``fixes`` antes de seguir para a árvore principal do KVM. 34 35Note que espera-se que este período de transição dure bastante tempo, ou seja, 36será o status quo em um futuro próximo. 37 38Branches 39~~~~~~~~ 40A árvore do KVM x86 é organizada em múltiplas branches de tópicos (topic 41branches). O objetivo de usar branches de tópicos mais granulares é facilitar o 42acompanhamento de uma área específica de desenvolvimento e limitar os danos 43colaterais de erros humanos e/ou commits com bugs; por exemplo, descartar o 44commit HEAD de uma branch de tópico não tem impacto nos hashes SHA1 de outros 45commits em andamento, e a necessidade de rejeitar um pull request devido a bugs 46atrasa apenas aquela branch de tópico específica. 47 48Todas as branches de tópicos, exceto a ``next`` e a ``fixes``, são incorporadas 49na ``next`` via um "Cthulhu merge" conforme a necessidade, ou seja, sempre que 50uma branch de tópico é atualizada. Como resultado, force pushes para a branch 51``next`` são comuns. 52 53Ciclo de Vida 54~~~~~~~~~~~~~ 55As correções (fixes) destinadas ao lançamento atual, também conhecido como 56mainline, são normalmente aplicadas diretamente na árvore principal do KVM, ou 57seja, não passam pela árvore do KVM x86. 58 59As mudanças destinadas ao próximo lançamento são roteadas através da árvore do 60KVM x86. Pull requests (do KVM x86 para o KVM principal) são enviados para cada 61branch de tópico do KVM x86, normalmente na semana anterior à abertura da janela 62de merge por Linus, por exemplo, na semana seguinte ao rc7 para lançamentos 63"normais". Se tudo correr bem, as branches de tópicos são incorporadas ao pull 64request principal do KVM enviado durante a janela de merge de Linus. 65 66A árvore do KVM x86 não possui sua própria janela de merge oficial, mas há um 67"soft close" (fechamento flexível) por volta do rc5 para novos recursos, e um 68"soft close" por volta do rc6 para correções (para o próximo lançamento; veja 69acima para correções destinadas ao lançamento atual). 70 71Cronograma 72---------- 73As submissões são normalmente revisadas e aplicadas em ordem FIFO (primeiro a 74entrar, primeiro a sair), com alguma margem de manobra para o tamanho de uma 75série, patches que estão "cache hot", etc. Correções (fixes), especialmente para 76o lançamento atual e/ou árvores estáveis (stable trees), têm prioridade na fila. 77Patches que serão aceitos através de uma árvore não-KVM (mais frequentemente 78através da árvore "tip") e/ou que possuam outros "acks"/revisões também ganham 79certa prioridade. 80 81Note que a grande maioria das revisões é feita entre o rc1 e o rc6, 82aproximadamente. O período entre o rc6 e o próximo rc1 é usado para colocar 83outras tarefas em dia, ou seja, o "silêncio de rádio" durante este período não é 84incomum. 85 86Pings para obter uma atualização de status são bem-vindos, mas tenha em mente o 87tempo do ciclo de lançamento atual e tenha expectativas realistas. Se você está 88dando um ping para aceitação — ou seja, não apenas para feedback ou uma 89atualização — por favor, faça tudo o que puder, dentro do razoável, para garantir 90que seus patches estejam prontos para o merge! Pings em séries que quebram o 91build ou falham em testes resultam em mantenedores infelizes! 92 93Desenvolvimento 94--------------- 95 96Árvore/Branch Base 97~~~~~~~~~~~~~~~~~~ 98Correções destinadas ao lançamento atual, também conhecido como mainline, devem 99ser baseadas em ``git://git.kernel.org/pub/scm/virt/kvm/kvm.git master``. Note 100que as correções não garantem inclusão automática no lançamento atual. Não 101existe uma regra única, mas tipicamente apenas correções para bugs que sejam 102urgentes, críticos e/ou que tenham sido introduzidos no lançamento atual devem 103ser destinadas ao lançamento atual. 104 105Todo o restante deve ser baseado em ``kvm-x86/next``, ou seja, não há 106necessidade de selecionar uma branch de tópico específica como base. Se houver 107conflitos e/ou dependências entre as branches de tópicos, é trabalho do 108mantenedor resolvê-los. 109 110A única exceção ao uso da ``kvm-x86/next`` como base é se um patch/série for uma 111série multi-arquitetura (multi-arch), ou seja, possuir modificações não triviais 112no código comum do KVM e/ou possuir mudanças mais do que superficiais no código 113de outras arquiteturas. Patches/séries multi-arquitetura devem, em vez disso, 114ser baseados em um ponto comum e estável no histórico do KVM, por exemplo, o 115release candidate no qual a ``kvm-x86 next`` se baseia. Se você não tiver 116certeza se um patch/série é verdadeiramente multi-arquitetura, erre pelo lado da 117cautela e trate-o como tal, ou seja, use uma base comum. 118 119Estilo de Codificação 120~~~~~~~~~~~~~~~~~~~~~ 121Quando se trata de estilo, nomenclatura, padrões, etc., a consistência é a 122prioridade número um no KVM x86. Se tudo mais falhar, siga o que já existe. 123 124Com algumas ressalvas listadas abaixo, siga o estilo de codificação preferido 125dos mantenedores da árvore "tip" (:ref:`maintainer-tip-coding-style`), já que 126patches/séries frequentemente tocam tanto arquivos do KVM quanto arquivos x86 127não-KVM, ou seja, atraem a atenção de mantenedores do KVM *e* da árvore "tip". 128 129O uso de "reverse fir tree" (árvore de abeto invertida), também conhecido como 130"árvore de Natal invertida", para declarações de variáveis não é estritamente 131obrigatório, embora ainda seja preferido. 132 133Exceto por alguns casos excepcionais, não use comentários kernel-doc para 134funções. A grande maioria das funções "públicas" do KVM não são verdadeiramente 135públicas, pois se destinam apenas ao consumo interno do KVM (há planos para 136privatizar os headers e exports do KVM para reforçar isso). 137 138Comentários 139~~~~~~~~~~~ 140Escreva comentários usando o modo imperativo e evite pronomes. Use comentários 141para fornecer uma visão geral de alto nível do código e/ou para explicar por 142que o código faz o que faz. Não reitere o que o código faz literalmente; deixe 143o código falar por si mesmo. Se o código em si for inescrutável, comentários 144não ajudarão. 145 146Referências ao SDM e ao APM 147~~~~~~~~~~~~~~~~~~~~~~~~~~~ 148Grande parte da base de código do KVM está diretamente ligada ao comportamento 149arquitetural definido no Manual de Desenvolvimento de Software (SDM) da Intel e 150no Manual do Programador de Arquitetura (APM) da AMD. O uso de "Intel SDM" e 151"AMD APM", ou até mesmo apenas "SDM" ou "APM", sem contexto adicional, é 152perfeitamente aceitável. 153 154Não faça referência a seções, tabelas, figuras, etc., por número, especialmente 155em comentários. Em vez disso, se necessário (veja abaixo), copie e cole o trecho 156relevante e referencie seções/tabelas/figuras pelo nome. Os layouts do SDM e do 157APM mudam constantemente e, portanto, os números/rótulos não são estáveis. 158 159De modo geral, não faça referência explícita nem copie e cole do SDM ou do APM 160em comentários. Com poucas exceções, o KVM *deve* respeitar o comportamento 161arquitetural; portanto, subentende-se que o comportamento do KVM está emulando o 162comportamento do SDM e/ou do APM. Note que fazer referência ao SDM/APM em 163changelogs para justificar a mudança e fornecer contexto é perfeitamente 164aceitável e incentivado. 165 166Shortlog 167~~~~~~~~ 168O formato de prefixo preferencial é ``KVM: <topic>:``, onde ``<topic>`` é um dos 169seguintes:: 170 171 - x86 172 - x86/mmu 173 - x86/pmu 174 - x86/xen 175 - selftests 176 - SVM 177 - nSVM 178 - VMX 179 - nVMX 180 181**NÃO use x86/kvm!** ``x86/kvm`` é usado exclusivamente para mudanças no Linux 182como convidado (guest) de um KVM, ou seja, para ``arch/x86/kernel/kvm.c``. Não 183use nomes de arquivos ou caminhos completos de arquivos como prefixo do 184assunto/shortlog. 185 186Note que estes não se alinham com as branches de tópicos (as branches de tópicos 187se preocupam muito mais com conflitos de código). 188 189Todos os nomes são sensíveis a maiúsculas e minúsculas! ``KVM: x86:`` é bom, 190``kvm: vmx:`` não é. 191 192Comece com letra maiúscula a primeira palavra da descrição condensada do patch, 193mas omita a pontuação final. Ex.:: 194 195 KVM: x86: Fix a null pointer dereference in function_xyz() 196 197e não:: 198 199 kvm: x86: fix a null pointer dereference in function_xyz. 200 201Se um patch tocar em múltiplos tópicos, suba na árvore conceitual para encontrar 202o primeiro pai comum (que geralmente é apenas ``x86``). Em caso de dúvida, 203``git log caminho/do/arquivo`` deve fornecer uma dica razoável. 204 205Novos tópicos surgem ocasionalmente, mas, por favor, inicie uma discussão na 206lista se desejar propor a introdução de um novo tópico; ou seja, não aja por 207conta própria. 208 209Veja :ref:`the_canonical_patch_format` para mais informações, com uma ressalva: 210não trate o limite de 70-75 caracteres como um limite absoluto e rígido. Em 211vez disso, use 75 caracteres como um limite firme, mas não rígido, e use 80 212caracteres como um limite intransponível. Ou seja, permita que o shortlog 213ultrapasse alguns caracteres do limite padrão se você tiver um bom motivo para 214fazê-lo. 215 216Changelog 217~~~~~~~~~ 218O mais importante: escreva os changelogs usando o modo imperativo e evite o uso 219de pronomes. 220 221Veja :ref:`describe_changes` para mais informações, com uma ressalva: comece com 222uma breve descrição das mudanças reais e, em seguida, apresente o contexto e o 223histórico. Note! Esta ordem entra em conflito direto com a abordagem preferida 224da árvore "tip"! Por favor, siga o estilo preferido da árvore "tip" ao enviar 225patches que visam primariamente o código de arch/x86 que _NÃO_ seja código KVM. 226 227Declarar o que um patch faz antes de mergulhar nos detalhes é preferido pelo KVM 228x86 por vários motivos. Primeiro e mais importante, qual código está sendo 229realmente alterado é, reconhecidamente, a informação mais importante e, 230portanto, essa informação deve ser fácil de encontrar. Changelogs que escondem 231"o que está mudando de fato" em uma única linha após 3 ou mais parágrafos de 232histórico tornam muito difícil encontrar essa informação. 233 234Para uma revisão inicial, pode-se argumentar que "o que está quebrado" é mais 235importante, mas para uma leitura rápida de logs e arqueologia do git, os 236detalhes minuciosos importam cada vez menos. Por exemplo, ao fazer uma série de 237"git blame", os detalhes de cada mudança ao longo do caminho são inúteis; os 238detalhes só importam para o culpado. Fornecer "o que mudou" facilita determinar 239rapidamente se um commit pode ou não ser de interesse. 240 241Outro benefício de declarar "o que está mudando" primeiro é que quase sempre é 242possível declarar "o que está mudando" em uma única frase. Por outro lado, 243exceto pelos bugs mais simples, todos exigem várias frases ou parágrafos para 244descrever totalmente o problema. Se tanto "o que está mudando" quanto "qual é o 245bug" forem super curtos, a ordem não importa. Mas se um for mais curto (quase 246sempre o "o que está mudando"), então cobrir o mais curto primeiro é vantajoso 247porque é menos inconveniente para leitores/revisores que têm uma preferência de 248ordenação estrita. Ex: ter que pular uma frase para chegar ao contexto é menos 249doloroso do que ter que pular três parágrafos para chegar ao "o que está 250mudando". 251 252Correções (Fixes) 253~~~~~~~~~~~~~~~~~ 254Se uma mudança corrige um bug do KVM/kernel, adicione uma tag Fixes:, mesmo que 255a mudança não precise ser portada (backported) para kernels estáveis, e mesmo 256que a mudança corrija um bug em uma versão mais antiga. 257 258Por outro lado, se uma correção realmente precisar de backport, marque 259explicitamente o patch com "Cc: stable@vger.kernel.org" (embora o e-mail em si 260não precise enviar cópia para a lista stable); o KVM x86 opta por não realizar 261o backport automático de tags Fixes: por padrão. Alguns patches selecionados 262automaticamente são portados, mas exigem aprovação explícita do mantenedor 263(pesquise por MANUALSEL). 264 265Referências a Funções 266~~~~~~~~~~~~~~~~~~~~~ 267Quando uma função for mencionada em um comentário, changelog ou shortlog (ou em 268qualquer outro lugar, aliás), use o formato ``nome_da_funcao()``. Os parênteses 269fornecem contexto e removem a ambiguidade da referência. 270 271Testes 272------ 273No mínimo, *todos* os patches de uma série devem compilar sem erros para 274KVM_INTEL=m, KVM_AMD=m e KVM_WERROR=y. Compilar cada combinação possível de 275Kconfigs não é viável, mas quanto mais, melhor. KVM_SMM, KVM_XEN, PROVE_LOCKING 276e X86_64 são opções (knobs) particularmente interessantes para se testar. 277 278A execução de KVM selftests e KVM-unit-tests também é obrigatória (e, para 279afirmar o óbvio, os testes precisam passar). A única exceção é para mudanças 280que tenham probabilidade insignificante de afetar o comportamento em tempo de 281execução, por exemplo, patches que apenas modificam comentários. Sempre que 282possível e relevante, o teste tanto em Intel quanto em AMD é fortemente 283preferido. A inicialização de uma VM real é incentivada, mas não obrigatória. 284 285Para mudanças que tocam o código de shadow paging do KVM, executar com o TDP 286(EPT/NPT) desabilitado é obrigatório. Para mudanças que afetam o código comum da 287MMU do KVM, a execução com o TDP desabilitado é fortemente incentivada. Para 288todas as outras mudanças, se o código sendo modificado depender de e/ou 289interagir com um parâmetro de módulo (module param), o teste com as 290configurações relevantes é obrigatório. 291 292Note que o KVM selftests e o KVM-unit-tests possuem falhas conhecidas. Se você 293suspeitar que uma falha não se deve às suas alterações, verifique se a *exata 294mesma* falha ocorre com e sem as suas mudanças. 295 296Mudanças que tocam a documentação em reStructuredText, ou seja, arquivos .rst, 297devem compilar o htmldocs de forma limpa, ou seja, sem novos avisos (warnings) 298ou erros. 299 300Se você não puder testar totalmente uma mudança, por exemplo, devido à falta de 301hardware, declare claramente qual nível de teste você foi capaz de realizar, 302por exemplo, na cover letter (carta de apresentação). 303 304Novos Recursos 305~~~~~~~~~~~~~~ 306Com uma exceção, novos recursos *devem* vir acompanhados de cobertura de testes. 307Testes específicos do KVM não são estritamente obrigatórios, por exemplo, se a 308cobertura for fornecida ao executar uma VM convidada (guest) suficientemente 309habilitada, ou ao executar um selftest de kernel relacionado em uma VM, mas 310testes dedicados do KVM são preferidos em todos os casos. Casos de teste 311negativos, em particular, são obrigatórios para a habilitação de novos recursos 312de hardware, já que fluxos de erro e exceção raramente são exercitados 313simplesmente ao executar uma VM. 314 315A única exceção a esta regra é se o KVM estiver simplesmente anunciando suporte 316para um recurso via KVM_GET_SUPPORTED_CPUID, ou seja, para instruções/recursos 317que o KVM não pode impedir um convidado de usar e para os quais não há uma 318habilitação real. 319 320Note que "novos recursos" não significa apenas "novos recursos de hardware"! 321Novos recursos que não podem ser bem validados usando os KVM selftests e/ou 322KVM-unit-tests existentes devem vir acompanhados de testes. 323 324Enviar o desenvolvimento de novos recursos sem testes para obter feedback 325antecipado é mais do que bem-vindo, mas tais submissões devem ser marcadas como 326RFC, e a carta de apresentação (cover letter) deve declarar claramente que tipo 327de feedback é solicitado/esperado. Não abuse do processo de RFC; as RFCs 328normalmente não receberão uma revisão profunda. 329 330Correções de Bugs 331~~~~~~~~~~~~~~~~~ 332Exceto por bugs "óbvios" encontrados por inspeção, as correções devem vir 333acompanhadas de um reprodutor (reproducer) para o bug que está sendo corrigido. 334Em muitos casos, o reprodutor é implícito, por exemplo, para erros de build e 335falhas de teste, mas ainda assim deve estar claro para os leitores o que está 336quebrado e como verificar a correção. Alguma margem de manobra é dada para 337bugs encontrados através de cargas de trabalho ou testes não públicos, mas a 338disponibilização de testes de regressão para tais bugs é fortemente preferida. 339 340Em geral, testes de regressão são preferidos para qualquer bug que não seja 341trivial de ser atingido. Por exemplo, mesmo que o bug tenha sido originalmente 342encontrado por um fuzzer como o syzkaller, um teste de regressão direcionado 343pode ser justificável se o bug exigir que se atinja uma condição de corrida do 344tipo "uma em um milhão". 345 346Note que os bugs do KVM raramente são urgentes *e* não triviais de reproduzir. 347Pergunte a si mesmo se um bug é realmente o fim do mundo antes de enviar uma 348correção sem um reprodutor. 349 350Postagem 351-------- 352 353Links 354~~~~~ 355Não faça referência explícita a relatórios de bugs, versões anteriores de um 356patch/série, etc., através de cabeçalhos ``In-Reply-To:``. O uso de 357``In-Reply-To:`` torna-se uma bagunça infernal para grandes séries e/ou quando 358o número de versões aumenta, e o ``In-Reply-To:`` é inútil para qualquer 359pessoa que não tenha a mensagem original, por exemplo, se alguém não estava 360em cópia (Cc) no relatório do bug ou se a lista de destinatários mudar entre 361as versões. 362 363Para vincular a um relatório de bug, versão anterior ou qualquer coisa de 364interesse, use links do lore. Para referenciar versão(ões) anterior(es), de modo 365geral, não inclua um Link: no changelog, pois não há necessidade de registrar o 366histórico no git; ou seja, coloque o link na carta de apresentação (cover 367letter) ou na seção que o git ignora. Forneça um Link: formal para relatórios 368de bugs e/ou discussões que levaram ao patch. O contexto de por que uma mudança 369foi feita é altamente valioso para futuros leitores. 370 371Base do Git (Git Base) 372~~~~~~~~~~~~~~~~~~~~~~ 373Se você estiver usando o git versão 2.9.0 ou posterior (Googlers, isso inclui 374todos vocês!), use ``git format-patch`` com a flag ``--base`` para incluir 375automaticamente as informações da árvore base nos patches gerados. 376 377Note que ``--base=auto`` funciona conforme o esperado se, e somente se, o 378upstream de uma branch estiver definido para a branch de tópico base; por 379exemplo, ele fará a coisa errada se o seu upstream estiver definido para o seu 380repositório pessoal para fins de backup. Uma solução "auto" alternativa é 381derivar os nomes das suas branches de desenvolvimento com base no seu tópico 382KVM x86 e alimentar isso no ``--base``. Por exemplo, 383``x86/pmu/minha_branch`` e, em seguida, escrever um pequeno wrapper para 384extrair ``pmu`` do nome da branch atual para resultar em ``--base=x/pmu``, onde 385``x`` é o nome que seu repositório usa para rastrear o remoto do KVM x86. 386 387Postagem Conjunta de Testes 388~~~~~~~~~~~~~~~~~~~~~~~~~~~ 389KVM selftests que estão associados a mudanças no KVM, por exemplo, testes de 390regressão para correções de bugs, devem ser postados junto com as mudanças do 391KVM como uma única série. As regras padrão do kernel para bissecção (bisection) 392se aplicam, ou seja, mudanças no KVM que resultem em falhas de teste devem ser 393ordenadas após as atualizações dos selftests e, vice-versa, novos testes que 394falhem devido a bugs do KVM devem ser ordenados após as correções do KVM. 395 396KVM-unit-tests devem *sempre* ser postados separadamente. Ferramentas, como o 397b4 am, não sabem que o KVM-unit-tests é um repositório separado e ficam 398confusas quando os patches de uma série se aplicam a árvores diferentes. Para 399vincular os patches do KVM-unit-tests aos patches do KVM, poste primeiro as 400mudanças do KVM e, em seguida, forneça um link do lore para o patch/série do 401KVM no(s) patch(es) do KVM-unit-tests. 402 403Notificações 404------------ 405Quando um patch/série é oficialmente aceito, um e-mail de notificação será 406enviado em resposta à postagem original (carta de apresentação para séries de 407múltiplos patches). A notificação incluirá a árvore e a branch de tópico, 408juntamente com os SHA1s dos commits dos patches aplicados. 409 410Se um subconjunto de patches for aplicado, isso será claramente declarado na 411notificação. A menos que seja dito o contrário, subentende-se que quaisquer 412patches na série que não foram aceitos precisam de mais trabalho e devem ser 413enviados em uma nova versão. 414 415Se, por algum motivo, um patch for descartado após ter sido oficialmente 416aceito, uma resposta será enviada ao e-mail de notificação explicando o porquê 417do descarte, bem como os próximos passos. 418 419Estabilidade de SHA1 420~~~~~~~~~~~~~~~~~~~~ 421Os SHA1s não têm garantia de serem 100% estáveis até que cheguem na árvore do 422Linus! Um SHA1 é *geralmente* estável uma vez que a notificação tenha sido 423enviada, mas imprevistos acontecem. Na maioria dos casos, uma atualização no 424e-mail de notificação será fornecida se o SHA1 de um patch aplicado mudar. No 425entanto, em alguns cenários, por exemplo, se todas as branches do KVM x86 426precisarem de rebase, as notificações individuais não serão enviadas. 427 428Vulnerabilidades 429---------------- 430Bugs que podem ser explorados pelo convidado (guest) para atacar o hospedeiro 431(host) (kernel ou espaço do usuário), ou que podem ser explorados por uma VM 432aninhada (nested) contra o *seu* próprio hospedeiro (L2 atacando L1), são de 433interesse particular para o KVM. Por favor, siga o protocolo em 434:ref:`securitybugs` se você suspeitar que um bug possa levar a um escape, 435vazamento de dados, etc. 436