1.. SPDX-License-Identifier: GPL-2.0 2 3O manual da árvore tip 4====================== 5 6O que é a árvore tip? 7--------------------- 8 9A árvore tip é uma coleção de vários subsistemas e áreas de 10desenvolvimento. A árvore tip é tanto uma árvore de desenvolvimento direto quanto uma 11árvore de agregação para várias árvores de sub-mantenedores. A URL gitweb da árvore tip 12é: https://git.kernel.org/pub/scm/linux/kernel/git/tip/tip.git 13 14A árvore tip contém os seguintes subsistemas: 15 16 - **Arquitetura x86** 17 18 O desenvolvimento da arquitetura x86 ocorre na árvore tip, exceto 19 pelas partes específicas do KVM e XEN no x86, que são mantidas nos 20 subsistemas correspondentes e roteadas diretamente para a mainline a partir 21 dali. Ainda é uma boa prática enviar Cc para os mantenedores x86 nos 22 patches do KVM e XEN específicos para x86. 23 24 Alguns subsistemas x86 têm seus próprios mantenedores além dos 25 mantenedores gerais do x86. Por favor, envie Cc para os mantenedores gerais do x86 em 26 patches que toquem em arquivos em arch/x86, mesmo quando não forem indicados 27 pelo arquivo MAINTAINER. 28 29 Note que ``x86@kernel.org`` não é uma lista de discussão. É meramente um 30 alias de e-mail que distribui mensagens para a equipe de mantenedores de nível superior 31 do x86. Por favor, sempre envie Cc para a lista de discussão do Linux Kernel (LKML) 32 ``linux-kernel@vger.kernel.org``, caso contrário, seu e-mail acabará apenas nas 33 caixas de entrada privadas dos mantenedores. 34 35 - **Scheduler** 36 37 O desenvolvimento do scheduler ocorre na árvore -tip, na 38 branch sched/core - com ocasionais árvores de subtópicos para 39 conjuntos de patches em progresso. 40 41 - **Locking e atomics** 42 43 O desenvolvimento de locking (incluindo atomics e outras primitivas de 44 sincronização que estão conectadas ao locking) ocorre na árvore -tip, 45 na branch locking/core - com ocasionais árvores de subtópicos 46 para conjuntos de patches em progresso. 47 48 - **Subsistema genérico de interrupções e drivers de chip de interrupção**: 49 50 - o desenvolvimento do núcleo de interrupções ocorre na branch irq/core 51 52 - o desenvolvimento do driver de chip de interrupção também ocorre na branch 53 irq/core, mas os patches geralmente são aplicados em uma árvore de mantenedor 54 separada e depois agregados na irq/core 55 56 - **Tempo, timers, timekeeping, NOHZ e drivers de chip relacionados**: 57 58 - o desenvolvimento do timekeeping, núcleo clocksource, NTP e alarmtimer 59 ocorre na branch timers/core, mas os patches geralmente são aplicados em 60 uma árvore de mantenedor separada e depois agregados na timers/core 61 62 - o desenvolvimento do driver clocksource/event ocorre na branch 63 timers/core, mas os patches são em sua maioria aplicados em uma árvore de mantenedor 64 separada e depois agregados na timers/core 65 66 - **Núcleo de contadores de desempenho, suporte a arquitetura e ferramentas**: 67 68 - o desenvolvimento do núcleo perf e suporte a arquitetura ocorre na 69 branch perf/core 70 71 - o desenvolvimento de ferramentas perf ocorre na árvore do mantenedor 72 de ferramentas perf e é agregado à árvore tip. 73 74 - **Núcleo de hotplug de CPU** 75 76 - **Núcleo RAS** 77 78 Em sua maioria, os patches RAS específicos para x86 são coletados na branch 79 ras/core da árvore tip. 80 81 - **Núcleo EFI** 82 83 Desenvolvimento EFI na árvore git efi. Os patches coletados são 84 agregados na branch efi/core da árvore tip. 85 86 - **RCU** 87 88 O desenvolvimento do RCU ocorre na árvore linux-rcu. As mudanças resultantes 89 são agregadas na branch core/rcu da árvore tip. 90 91 - **Vários componentes de código do núcleo**: 92 93 - debugobjects 94 95 - objtool 96 97 - partes e peças aleatórias 98 99 100Notas de submissão de patch 101--------------------------- 102 103Selecionando a árvore/branch 104^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 105 106Em geral, o desenvolvimento contra o head da branch master da árvore tip é 107adequado, mas para os subsistemas que são mantidos separadamente, possuem sua 108própria árvore git e são apenas agregados na árvore tip, o desenvolvimento deve 109ocorrer contra a árvore ou branch do subsistema relevante. 110 111Correções de bugs que visam a mainline devem sempre ser aplicáveis contra a 112árvore do kernel mainline. Potenciais conflitos contra mudanças que já estão 113na fila da árvore tip são resolvidos pelos mantenedores. 114 115Assunto do patch 116^^^^^^^^^^^^^^^^ 117 118O formato preferido da árvore tip para prefixos de assunto do patch é 119'subsys/component:', ex. 'x86/apic:', 'x86/mm/fault:', 'sched/fair:', 120'genirq/core:'. Por favor, não use nomes de arquivos ou caminhos de arquivos completos como 121prefixo. 'git log path/to/file' deve lhe dar uma dica razoável na maioria 122dos casos. 123 124A descrição condensada do patch na linha de assunto deve começar com uma 125letra maiúscula e deve ser escrita em tom imperativo. 126 127 128Changelog 129^^^^^^^^^ 130 131As regras gerais sobre changelogs no :ref:`Guia de submissão de patches 132<pt_BR_describe_changes>`, se aplicam. 133 134Os mantenedores da árvore tip valorizam seguir essas regras, especialmente no 135pedido para escrever changelogs no modo imperativo e não personificando 136o código ou sua execução. Isso não é apenas um capricho dos 137mantenedores. Changelogs escritos em palavras abstratas são mais precisos e 138tendem a ser menos confusos do que aqueles escritos em forma de romances. 139 140Também é útil estruturar o changelog em vários parágrafos e não 141juntar tudo em um só. Uma boa estrutura é explicar 142o contexto, o problema e a solução em parágrafos separados e nesta 143ordem. 144 145Exemplos para ilustração: 146 147 Exemplo 1:: 148 149 x86/intel_rdt/mbm: Corrigir o manipulador de overflow do MBM durante hot cpu 150 151 Quando uma CPU está morrendo, cancelamos o worker e agendamos um novo worker em uma 152 CPU diferente no mesmo domínio. Mas se o timer já está prestes a 153 expirar (digamos 0.99s) então essencialmente dobramos o intervalo. 154 155 Modificamos o tratamento de hot cpu para cancelar o trabalho atrasado na cpu 156 que está morrendo e executar o worker imediatamente em uma cpu diferente no mesmo domínio. Não 157 fazemos o flush do worker porque o worker de overflow do MBM reagenda o 158 worker na mesma CPU e escaneia a domain->cpu_mask para obter o ponteiro 159 do domínio. 160 161 Versão melhorada:: 162 163 x86/intel_rdt/mbm: Corrigir o manipulador de overflow do MBM durante hotplug de CPU 164 165 Quando uma CPU está morrendo, o worker de overflow é cancelado e reagendado em uma 166 CPU diferente no mesmo domínio. Mas se o timer já estiver prestes a 167 expirar isso essencialmente dobra o intervalo, o que pode resultar em um overflow 168 não detectado. 169 170 Cancele o worker de overflow e reagende-o imediatamente em uma CPU diferente 171 no mesmo domínio. O trabalho também poderia sofrer um flush, mas isso iria 172 reagendá-lo na mesma CPU. 173 174 Exemplo 2:: 175 176 time: POSIX CPU timers: Garantir que a variável seja inicializada 177 178 Se cpu_timer_sample_group retornar -EINVAL, ela não terá escrito em 179 *sample. Checar o valor de retorno de cpu_timer_sample_group previne o 180 uso potencial de um valor não inicializado de now no bloco seguinte. 181 Dado um clock_idx inválido, o código anterior poderia caso contrário sobrescrever 182 *oldval de maneira indefinida. Isso agora é prevenido. Também exploramos 183 o curto-circuito do && para amostrar o timer apenas se o resultado for 184 realmente usado para atualizar *oldval. 185 186 Versão melhorada:: 187 188 posix-cpu-timers: Tornar set_process_cpu_timer() mais robusto 189 190 Como o valor de retorno de cpu_timer_sample_group() não é checado, 191 compiladores e checadores estáticos podem legitimamente avisar sobre um uso potencial 192 da variável não inicializada 'now'. Isso não é um problema de tempo de execução pois todos 193 os locais de chamada passam ids de clock válidos. 194 195 Além disso, cpu_timer_sample_group() é invocado incondicionalmente mesmo quando o 196 resultado não é usado porque *oldval é NULL. 197 198 Torne a invocação condicional e cheque o valor de retorno. 199 200 Exemplo 3:: 201 202 A entidade também pode ser usada para outros propósitos. 203 204 Vamos renomeá-la para ser mais genérica. 205 206 Versão melhorada:: 207 208 A entidade também pode ser usada para outros propósitos. 209 210 Renomeie para ser mais genérica. 211 212 213Para cenários complexos, especialmente condições de corrida (race conditions) e problemas 214de ordenação de memória, é valioso descrever o cenário com uma tabela que mostra 215o paralelismo e a ordem temporal dos eventos. Aqui está um exemplo:: 216 217 CPU0 CPU1 218 free_irq(X) interrupt X 219 spin_lock(desc->lock) 220 wake irq thread() 221 spin_unlock(desc->lock) 222 spin_lock(desc->lock) 223 remove action() 224 shutdown_irq() 225 release_resources() thread_handler() 226 spin_unlock(desc->lock) access released resources. 227 ^^^^^^^^^^^^^^^^^^^^^^^^^ 228 synchronize_irq() 229 230O Lockdep fornece uma saída útil semelhante para descrever um possível cenário 231de deadlock:: 232 233 CPU0 CPU1 234 rtmutex_lock(&rcu->rt_mutex) 235 spin_lock(&rcu->rt_mutex.wait_lock) 236 local_irq_disable() 237 spin_lock(&timer->it_lock) 238 spin_lock(&rcu->mutex.wait_lock) 239 --> Interrupt 240 spin_lock(&timer->it_lock) 241 242Referências a funções em changelogs 243^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 244 245Quando uma função é mencionada no changelog, seja no corpo do texto ou na 246linha de assunto, por favor use o formato 'nome_da_funcao()'. Omitir os 247parênteses após o nome da função pode ser ambíguo:: 248 249 Subject: subsys/component: Make reservation_count static 250 251 reservation_count is only used in reservation_stats. Make it static. 252 253A variante com parênteses é mais precisa:: 254 255 Subject: subsys/component: Make reservation_count() static 256 257 reservation_count() is only called from reservation_stats(). Make it 258 static. 259 260 261Backtraces em changelogs 262^^^^^^^^^^^^^^^^^^^^^^^^ 263 264Veja :ref:`pt_BR_backtraces`. 265 266Ordenação das tags de commit 267^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 268 269Para ter uma visão uniforme das tags de commit, os mantenedores da tip usam o 270seguinte esquema de ordenação de tags: 271 272 - Fixes: 12+char-SHA1 ("sub/sys: Original subject line") 273 274 Uma tag Fixes deve ser adicionada mesmo para alterações que não precisam ser 275 portadas de volta (backported) para kernels estáveis, ou seja, quando abordar um 276 problema recém-introduzido que afeta apenas a árvore tip ou o head atual da linha principal (mainline). Estas tags 277 são úteis para identificar o commit original e são muito mais valiosas 278 do que mencionar de forma proeminente o commit que introduziu um problema no 279 próprio texto do changelog, porque elas podem ser automaticamente 280 extraídas. 281 282 O exemplo a seguir ilustra a diferença:: 283 284 Commit 285 286 abcdef012345678 ("x86/xxx: Replace foo with bar") 287 288 deixou uma instância não utilizada da variável foo. Remova-a. 289 290 Signed-off-by: J.Dev <j.dev@mail> 291 292 Por favor, diga em vez disso:: 293 294 A recente substituição de foo por bar deixou uma instância não utilizada da 295 variável foo. Remova-a. 296 297 Fixes: abcdef012345678 ("x86/xxx: Replace foo with bar") 298 Signed-off-by: J.Dev <j.dev@mail> 299 300 O último coloca as informações sobre o patch em foco e 301 as complementa com a referência ao commit que introduziu o problema, 302 em vez de colocar o foco no commit original em primeiro lugar. 303 304 - Reported-by: ``Reporter <reporter@mail>`` 305 306 - Closes: ``URL or Message-ID of the bug report this is fixing`` 307 308 - Originally-by: ``Original author <original-author@mail>`` 309 310 - Suggested-by: ``Suggester <suggester@mail>`` 311 312 - Co-developed-by: ``Co-author <co-author@mail>`` 313 314 Signed-off-by: ``Co-author <co-author@mail>`` 315 316 Note que Co-developed-by e Signed-off-by do(s) co-autor(es) devem 317 vir em pares. 318 319 - Signed-off-by: ``Author <author@mail>`` 320 321 O primeiro Signed-off-by (SOB) após o último par Co-developed-by/SOB é o 322 SOB do autor, ou seja, a pessoa marcada como autora pelo git. 323 324 - Signed-off-by: ``Patch handler <handler@mail>`` 325 326 SOBs após o SOB do autor são de pessoas que lidam e transportam 327 o patch, mas não estiveram envolvidas no desenvolvimento. As cadeias de SOB devem 328 refletir a rota **real** que um patch tomou conforme foi propagado para nós, 329 com a primeira entrada de SOB sinalizando a autoria principal de um único 330 autor. Acks devem ser dados como linhas Acked-by e aprovações de revisão 331 como linhas Reviewed-by. 332 333 Se o manipulador fez modificações no patch ou no changelog, então 334 isso deve ser mencionado **após** o texto do changelog e **acima** 335 de todas as tags de commit no seguinte formato:: 336 337 ... o texto do changelog termina. 338 339 [ handler: Substituiu foo por bar e atualizou o changelog ] 340 341 First-tag: ..... 342 343 Observe as duas novas linhas vazias que separam o texto do changelog e as 344 tags de commit daquele aviso. 345 346 Se um patch for enviado para a lista de discussão por um manipulador, então o autor tem 347 que ser notado na primeira linha do changelog com:: 348 349 From: Author <author@mail> 350 351 O texto do changelog começa aqui.... 352 353 assim a autoria é preservada. A linha 'From:' tem que ser seguida 354 por uma nova linha vazia. Se essa linha 'From:' estiver faltando, então o patch 355 seria atribuído à pessoa que o enviou (transportou, manipulou). 356 A linha 'From:' é automaticamente removida quando o patch é aplicado 357 e não aparece no changelog final do git. Ela meramente afeta 358 a informação de autoria do commit resultante do Git. 359 360 - Tested-by: ``Tester <tester@mail>`` 361 362 - Reviewed-by: ``Reviewer <reviewer@mail>`` 363 364 - Acked-by: ``Acker <acker@mail>`` 365 366 - Cc: ``cc-ed-person <person@mail>`` 367 368 Se o patch deve ser portado para stable, então por favor adicione uma tag '``Cc: 369 stable@vger.kernel.org``', mas não coloque em Cc o stable ao enviar o seu 370 e-mail. 371 372 - Link: ``https://link/to/information`` 373 374 Para se referir a um e-mail postado nas listas de discussão do kernel, por favor 375 use o URL de redirecionamento lore.kernel.org:: 376 377 Link: https://lore.kernel.org/email-message-id@here 378 379 Esta URL deve ser usada ao se referir a tópicos de lista de discussão relevantes, 380 conjuntos de patches relacionados, ou outras threads de discussão notáveis. 381 Uma maneira conveniente de associar os trailers ``Link:`` com a mensagem de commit 382 é usar a notação de colchetes semelhante ao markdown, por exemplo:: 383 384 A similar approach was attempted before as part of a different 385 effort [1], but the initial implementation caused too many 386 regressions [2], so it was backed out and reimplemented. 387 388 Link: https://lore.kernel.org/some-msgid@here # [1] 389 Link: https://bugzilla.example.org/bug/12345 # [2] 390 391 Você também pode usar os trailers ``Link:`` para indicar a origem do 392 patch ao aplicá-lo em sua árvore git. Neste caso, por favor use o 393 domínio dedicado ``patch.msgid.link`` em vez de ``lore.kernel.org``. 394 Esta prática torna possível que as ferramentas automatizadas identifiquem 395 qual link usar para recuperar o envio do patch original. Por 396 exemplo:: 397 398 Link: https://patch.msgid.link/patch-source-message-id@here 399 400Por favor não use tags combinadas, ex. ``Reported-and-tested-by``, pois 401elas apenas complicam a extração automatizada de tags. 402 403 404Links para documentação 405^^^^^^^^^^^^^^^^^^^^^^^ 406 407Fornecer links para a documentação no changelog é uma grande ajuda para depuração e 408análise posteriores. Infelizmente, os URLs costumam quebrar muito rapidamente 409porque as empresas reestruturam seus sites frequentemente. Exceções não 'voláteis' 410incluem o Intel SDM e o AMD APM. 411 412Portanto, para documentos 'voláteis', por favor crie uma entrada no bugzilla do kernel 413https://bugzilla.kernel.org e anexe uma cópia desses documentos 414à entrada do bugzilla. Finalmente, forneça o URL da entrada do bugzilla no 415changelog. 416 417Reenvio de patch ou lembretes 418^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 419 420Veja :ref:`pt_BR_resend_reminders`. 421 422Janela de merge 423^^^^^^^^^^^^^^^ 424 425Por favor, não espere que os patches sejam revisados ou mesclados pelos mantenedores da árvore tip 426em torno ou durante a janela de merge. As árvores ficam fechadas 427para todos, exceto correções urgentes, durante esse tempo. Elas reabrem assim que a janela de merge 428fecha e um novo kernel -rc1 é lançado. 429 430Grandes séries devem ser enviadas em estado mesclável (mergeable state) *pelo* *menos* uma semana 431antes da janela de merge abrir. Exceções são feitas para correções de bugs e 432*às vezes* para pequenos drivers independentes para novos hardwares ou patches minimamente 433invasivos para ativação de hardware. 434 435Durante a janela de merge, os mantenedores se concentram em seguir as 436alterações upstream, corrigir problemas resultantes da janela de merge, coletar correções de bugs, e 437se permitir um respiro. Por favor, respeite isso. 438 439Os chamados branches _urgent_ serão mesclados na linha principal (mainline) durante a 440fase de estabilização de cada versão. 441 442 443Git 444^^^ 445 446Os mantenedores da árvore tip aceitam pull requests do git de mantenedores que fornecem 447alterações de subsistema para agregação na árvore tip. 448 449Pull requests para novos envios de patches normalmente não são aceitos e não 450substituem o envio adequado de patch para a lista de discussão. O principal motivo para 451isso é que o fluxo de trabalho de revisão é baseado em e-mail. 452 453Se você enviar uma série maior de patches, é útil fornecer um branch git 454em um repositório privado que permita que pessoas interessadas façam pull da 455série facilmente para testes. A maneira usual de oferecer isso é uma URL do git na carta de apresentação (cover letter) 456da série de patches. 457 458Testes 459^^^^^^ 460 461O código deve ser testado antes de ser enviado para os mantenedores da árvore tip. Qualquer coisa 462além de alterações menores deve ser construída, inicializada e testada com 463opções abrangentes (e pesadas) de depuração do kernel ativadas. 464 465Essas opções de depuração podem ser encontradas em kernel/configs/x86_debug.config 466e podem ser adicionadas a uma configuração de kernel existente executando: 467 468 make x86_debug.config 469 470Algumas dessas opções são específicas do x86 e podem ser deixadas de fora ao testar 471em outras arquiteturas. 472 473.. _pt_BR_maintainer-tip-coding-style: 474 475Notas de estilo de código 476------------------------- 477 478Estilo de comentário 479^^^^^^^^^^^^^^^^^^^^ 480 481Frases em comentários começam com uma letra maiúscula. 482 483Comentários de linha única:: 484 485 /* Este é um comentário de linha única */ 486 487Comentários de várias linhas:: 488 489 /* 490 * This is a properly formatted 491 * multi-line comment. 492 * 493 * Larger multi-line comments should be split into paragraphs. 494 */ 495 496Sem comentários no fim da linha (veja abaixo): 497 498 Por favor, abstenha-se de usar comentários no fim da linha. Comentários no fim da linha atrapalham o 499 fluxo de leitura em quase todos os contextos, mas especialmente em código:: 500 501 if (somecondition_is_true) /* Não coloque um comentário aqui */ 502 dostuff(); /* Nem aqui */ 503 504 seed = MAGIC_CONSTANT; /* Nem aqui */ 505 506 Use comentários independentes em vez disso:: 507 508 /* Esta condição não é óbvia sem um comentário */ 509 if (somecondition_is_true) { 510 /* Isso realmente precisa ser documentado */ 511 dostuff(); 512 } 513 514 /* Esta inicialização mágica precisa de um comentário. Talvez não? */ 515 seed = MAGIC_CONSTANT; 516 517 Use o estilo C++, comentários no fim da linha ao documentar structs em headers para 518 alcançar um layout mais compacto e melhor legibilidade:: 519 520 // eax 521 u32 x2apic_shift : 5, // Número de bits para deslocar o ID APIC para a direita 522 // para o ID de topologia no próximo nível 523 : 27; // Reservado 524 // ebx 525 u32 num_processors : 16, // Número de processadores no nível atual 526 : 16; // Reservado 527 528 versus:: 529 530 /* eax */ 531 /* 532 * Número de bits para deslocar o ID APIC para a direita para o ID de topologia 533 * no próximo nível 534 */ 535 u32 x2apic_shift : 5, 536 /* Reservado */ 537 : 27; 538 539 /* ebx */ 540 /* Número de processadores no nível atual */ 541 u32 num_processors : 16, 542 /* Reservado */ 543 : 16; 544 545Comente as coisas importantes: 546 547 Comentários devem ser adicionados onde a operação não é óbvia. Documentar 548 o óbvio é apenas uma distração:: 549 550 /* Decrementa o refcount e verifica por zero */ 551 if (refcount_dec_and_test(&p->refcnt)) { 552 do; 553 lots; 554 of; 555 magic; 556 things; 557 } 558 559 Em vez disso, os comentários devem explicar os detalhes não óbvios e documentar 560 as restrições:: 561 562 if (refcount_dec_and_test(&p->refcnt)) { 563 /* 564 * Explicação muito boa de por que as coisas mágicas abaixo 565 * precisam ser feitas, restrições de ordenação e locking, 566 * etc.. 567 */ 568 do; 569 lots; 570 of; 571 magic; 572 /* Precisa ser a última operação porque ... */ 573 things; 574 } 575 576Comentários de documentação de função: 577 578 Para documentar funções e seus argumentos por favor use o formato kernel-doc 579 e não comentários de formato livre:: 580 581 /** 582 * magic_function - Faz muitas coisas mágicas 583 * @magic: Ponteiro para os dados mágicos nos quais operar 584 * @offset: Deslocamento no array de dados de @magic 585 * 586 * Explicação profunda das coisas misteriosas feitas com @magic junto 587 * com a documentação dos valores de retorno. 588 * 589 * Note que os descritores de argumento acima estão dispostos 590 * de forma tabular. 591 */ 592 593 Isto se aplica especialmente a funções visíveis globalmente e funções 594 inline em arquivos de cabeçalho públicos. Pode ser um exagero usar o formato 595 kernel-doc para cada função (estática) que precisa de uma pequena explicação. O 596 uso de nomes de funções descritivos frequentemente substitui esses pequenos comentários. 597 Aplique o bom senso como sempre. 598 599 600Documentando requisitos de locking 601^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 602 Documentar requisitos de locking é uma coisa boa, mas comentários não 603 são necessariamente a melhor escolha. Em vez de escrever:: 604 605 /* Caller must hold foo->lock */ 606 void func(struct foo *foo) 607 { 608 ... 609 } 610 611 Por favor, use:: 612 613 void func(struct foo *foo) 614 { 615 lockdep_assert_held(&foo->lock); 616 ... 617 } 618 619 Em kernels PROVE_LOCKING, lockdep_assert_held() emite um aviso 620 se o chamador não detém o lock. Comentários não podem fazer isso. 621 622Regras de chaves 623^^^^^^^^^^^^^^^^ 624 625Chaves devem ser omitidas apenas se a instrução que se segue a 'if', 'for', 626'while' etc. for verdadeiramente uma única linha:: 627 628 if (foo) 629 do_something(); 630 631O seguinte não é considerado uma instrução de linha única mesmo 632que o C não exija chaves:: 633 634 for (i = 0; i < end; i++) 635 if (foo[i]) 636 do_something(foo[i]); 637 638Adicionar chaves ao redor do loop externo melhora o fluxo de leitura:: 639 640 for (i = 0; i < end; i++) { 641 if (foo[i]) 642 do_something(foo[i]); 643 } 644 645 646Declarações de variáveis 647^^^^^^^^^^^^^^^^^^^^^^^^ 648 649A ordem preferida das declarações de variáveis no início de uma 650função é a ordem de árvore de abeto invertida (reverse fir tree order):: 651 652 struct long_struct_name *descriptive_name; 653 unsigned long foo, bar; 654 unsigned int tmp; 655 int ret; 656 657O que está acima é mais rápido de analisar do que a ordem invertida:: 658 659 int ret; 660 unsigned int tmp; 661 unsigned long foo, bar; 662 struct long_struct_name *descriptive_name; 663 664E ainda mais do que uma ordem aleatória:: 665 666 unsigned long foo, bar; 667 int ret; 668 struct long_struct_name *descriptive_name; 669 unsigned int tmp; 670 671Também por favor tente agregar variáveis do mesmo tipo em uma única 672linha. Não há sentido em desperdiçar espaço na tela:: 673 674 unsigned long a; 675 unsigned long b; 676 unsigned long c; 677 unsigned long d; 678 679É realmente suficiente fazer:: 680 681 unsigned long a, b, c, d; 682 683Por favor, evite também introduzir divisões de linha em declarações de variáveis:: 684 685 struct long_struct_name *descriptive_name = container_of(bar, 686 struct long_struct_name, 687 member); 688 struct foobar foo; 689 690É muito melhor mover a inicialização para uma linha separada após as 691declarações:: 692 693 struct long_struct_name *descriptive_name; 694 struct foobar foo; 695 696 descriptive_name = container_of(bar, struct long_struct_name, member); 697 698 699Tipos de variáveis 700^^^^^^^^^^^^^^^^^^ 701 702Por favor use os tipos u8, u16, u32, u64 adequados para variáveis que são destinadas 703a descrever hardware ou são usadas como argumentos para funções que acessam 704hardware. Estes tipos definem claramente a largura em bits e evitam 705truncamento, expansão e confusão entre 32/64 bits. 706 707u64 também é recomendado em código que se tornaria ambíguo para kernels 708de 32 bits quando 'unsigned long' fosse usado em vez disso. Embora em tais 709situações 'unsigned long long' pudesse ser usado também, u64 é mais curto 710e também mostra claramente que a operação requer uma largura de 64 bits 711independente da CPU alvo. 712 713Por favor use 'unsigned int' em vez de 'unsigned'. 714 715 716Constantes 717^^^^^^^^^^ 718 719Por favor, não use números (hexa)decimais literais em código ou inicializadores. 720Ou use defines adequados que tenham nomes descritivos ou considere usar 721um enum. 722 723 724Declarações e inicializadores de struct 725^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 726 727As declarações de struct devem alinhar os nomes dos membros da struct de forma 728tabular:: 729 730 struct bar_order { 731 unsigned int guest_id; 732 int ordered_item; 733 struct menu *menu; 734 }; 735 736Por favor, evite documentar os membros da struct dentro da declaração, pois 737isso frequentemente resulta em comentários formatados de maneira estranha e os membros da struct 738ficam ofuscados:: 739 740 struct bar_order { 741 unsigned int guest_id; /* ID único do convidado */ 742 int ordered_item; 743 /* Ponteiro para uma instância de menu que contém todas as bebidas */ 744 struct menu *menu; 745 }; 746 747Em vez disso, por favor considere usar o formato kernel-doc em um comentário precedendo 748a declaração da struct, que é mais fácil de ler e tem a vantagem adicional 749de incluir a informação na documentação do kernel, por exemplo, da 750seguinte forma:: 751 752 753 /** 754 * struct bar_order - Descrição de um pedido de bar 755 * @guest_id: ID único do convidado 756 * @ordered_item: O número do item do menu 757 * @menu: Ponteiro para o menu do qual o item 758 * foi pedido 759 * 760 * Informação suplementar para usar a struct. 761 * 762 * Note que os descritores dos membros da struct acima estão dispostos 763 * de forma tabular. 764 */ 765 struct bar_order { 766 unsigned int guest_id; 767 int ordered_item; 768 struct menu *menu; 769 }; 770 771Inicializadores de struct estáticos devem usar inicializadores C99 e também devem ser 772alinhados de forma tabular:: 773 774 static struct foo statfoo = { 775 .a = 0, 776 .plain_integer = CONSTANT_DEFINE_OR_ENUM, 777 .bar = &statbar, 778 }; 779 780Note que embora a sintaxe C99 permita a omissão da vírgula final, 781nós recomendamos o uso de uma vírgula na última linha porque isso torna 782o reordenamento e a adição de novas linhas mais fáceis, e também torna tais 783patches futuros ligeiramente mais fáceis de ler. 784 785Quebras de linha 786^^^^^^^^^^^^^^^^ 787 788Restringir o comprimento da linha a 80 caracteres torna código profundamente indentado difícil de 789ler. Considere dividir o código em funções auxiliares para evitar quebra de 790linha excessiva. 791 792A regra de 80 caracteres não é uma regra estrita, então por favor use bom senso ao 793quebrar linhas. Especialmente strings de formato nunca devem ser divididas. 794 795Ao dividir declarações de funções ou chamadas de funções, então por favor alinhe 796o primeiro argumento na segunda linha com o primeiro argumento na primeira 797linha:: 798 799 static int long_function_name(struct foobar *barfoo, unsigned int id, 800 unsigned int offset) 801 { 802 803 if (!id) { 804 ret = longer_function_name(barfoo, DEFAULT_BARFOO_ID, 805 offset); 806 ... 807 808Namespaces 809^^^^^^^^^^ 810 811Namespaces de funções/variáveis melhoram a legibilidade e permitem 812grepping fácil. Estes namespaces são prefixos de string para nomes 813de funções e variáveis visíveis globalmente, incluindo inlines. Estes prefixos devem 814combinar o subsistema e o nome do componente como 'x86_comp\_', 815'sched\_', 'irq\_', e 'mutex\_'. 816 817Isso também inclui funções estáticas de escopo de arquivo que são imediatamente colocadas 818em templates de driver visíveis globalmente - é útil que esses símbolos 819também carreguem um bom prefixo, para legibilidade do backtrace. 820 821Prefixos de namespace podem ser omitidos para funções e variáveis 822estáticas locais. Funções verdadeiramente locais, chamadas apenas por outras funções locais, 823podem ter nomes descritivos mais curtos - nossa preocupação principal é a facilidade de grepping 824e a legibilidade do backtrace. 825 826Por favor note que os prefixos 'xxx_vendor\_' e 'vendor_xxx\_' não são 827úteis para funções estáticas em arquivos específicos de fornecedores. Afinal, 828já está claro que o código é específico do fornecedor. Além disso, nomes 829de fornecedores devem ser apenas para funcionalidades verdadeiramente específicas de fornecedores. 830 831Como sempre, aplique o bom senso e vise a consistência e a legibilidade. 832 833 834Notificações de commit 835---------------------- 836 837A árvore tip é monitorada por um bot por novos commits. O bot envia um email 838para cada novo commit para uma lista de discussão dedicada 839(``linux-tip-commits@vger.kernel.org``) e coloca em Cc todas as pessoas que são 840mencionadas em uma das tags de commit. Ele usa o ID da mensagem de email da 841tag Link no final da lista de tags para definir o cabeçalho de email In-Reply-To para que 842a mensagem seja encadeada corretamente com o email de submissão do patch. 843 844Os mantenedores e submantenedores tip tentam responder ao remetente 845ao fazer o merge de um patch, mas às vezes eles esquecem ou isso não se encaixa no 846fluxo de trabalho do momento. Embora a mensagem do bot seja puramente mecânica, ela 847também implica em um 'Obrigado! Aplicado.'. 848