diff options
Diffstat (limited to 'Documentation/translations/pt_BR/process')
33 files changed, 4337 insertions, 92 deletions
diff --git a/Documentation/translations/pt_BR/process/2.Process.rst b/Documentation/translations/pt_BR/process/2.Process.rst index 5ff35f10aac7..0019b7404d33 100644 --- a/Documentation/translations/pt_BR/process/2.Process.rst +++ b/Documentation/translations/pt_BR/process/2.Process.rst @@ -75,16 +75,16 @@ Como exemplo, veja como ocorreu o ciclo de desenvolvimento da versão 5.4 (todas as datas são de 2019): ============== =============================== - Setembro 15 5.3 Lançamento estável do 5.3 + Setembro 15 Lançamento estável do 5.3 Setembro 30 5.4-rc1, fechamento da janela de integração Outubro 6 5.4-rc2 Outubro 13 5.4-rc3 Outubro 20 5.4-rc4 - October 27 5.4-rc5 + Outubro 27 5.4-rc5 Novembro 3 5.4-rc6 Novembro 10 5.4-rc7 Novembro 17 5.4-rc8 - Novembro 24 5.4 Lançamento estável do 5.4 + Novembro 24 Lançamento estável do 5.4 ============== =============================== Como os desenvolvedores decidem quando encerrar o ciclo de desenvolvimento @@ -330,7 +330,7 @@ A árvore de fontes do kernel contém o diretório drivers/staging/, onde reside muitos subdiretórios para drivers ou sistemas de arquivos que estão a caminho de serem adicionados à árvore do kernel. Eles permanecem em drivers/staging/ enquanto ainda precisam de mais trabalho; uma vez concluídos, podem ser movidos -para o kernel proper Esta é uma maneira de acompanhar drivers que não estão à +para o kernel propriamente dito. Esta é uma maneira de acompanhar drivers que não estão à altura dos padrões de codificação ou de qualidade do kernel Linux, mas que as pessoas podem querer usar e acompanhar o desenvolvimento. @@ -433,7 +433,7 @@ Existem algumas dicas que podem ajudar na sobrevivência na lista linux-kernel: caixa de entrada principal. É preciso ser capaz de ignorar o fluxo de e-mails por períodos prolongados de tempo. -- Não tente acompanhar cada conversa ninguém mais faz isso. É importante +- Não tente acompanhar cada conversa, ninguém mais faz isso. É importante filtrar tanto pelo tópico de interesse (embora note que conversas longas podem se desviar do assunto original sem que a linha de assunto do e-mail seja alterada) quanto pelas pessoas que estão participando. @@ -455,13 +455,13 @@ Existem algumas dicas que podem ajudar na sobrevivência na lista linux-kernel: - Use respostas intercaladas, o que torna sua resposta mais fácil de ler. (ou seja, evite o "top-posting" — a prática de colocar sua resposta acima do texto citado ao qual você está respondendo). Para mais detalhes, veja - :ref:`Documentation/process/submitting-patches.rst <interleaved_replies>`. + :ref:`Documentation/process/submitting-patches.rst <pt_BR_interleaved_replies>`. - Pergunte na lista de discussão correta. A lista linux-kernel pode até ser o ponto de encontro geral, mas não é o melhor lugar para encontrar desenvolvedores de todos os subsistemas. -O último ponto, encontrar a lista de discussão correta é um lugar comum +O último ponto, encontrar a lista de discussão correta, é um lugar comum onde os desenvolvedores iniciantes costumam errar. Alguém que faça uma pergunta relacionada a redes na lista linux-kernel quase certamente receberá uma sugestão educada para perguntar na lista netdev em seu lugar, já que essa é a diff --git a/Documentation/translations/pt_BR/process/3.Early-stage.rst b/Documentation/translations/pt_BR/process/3.Early-stage.rst index 74e741766b46..86c228353084 100644 --- a/Documentation/translations/pt_BR/process/3.Early-stage.rst +++ b/Documentation/translations/pt_BR/process/3.Early-stage.rst @@ -74,7 +74,7 @@ Discussão inicial Ao planejar um projeto de desenvolvimento do kernel, faz todo o sentido realizar discussões com a comunidade antes de iniciar a implementação. A comunicação -inicial pode economizar tempo e problemas de várias maneiras:number of ways: +inicial pode economizar tempo e problemas de várias maneiras: - Pode muito bem ser que o problema já seja tratado pelo kernel de maneiras que você não compreendeu. O kernel Linux é grande e possui uma série de @@ -121,8 +121,8 @@ comunidade do kernel. Alguns exemplos incluem: consideradas inseguras e não confiáveis. Essa preocupação (entre outras) manteve o AppArmor fora do kernel principal (*mainline*) por anos. -In each of these cases, a great deal of pain and extra work could have been -avoided with some early discussion with the kernel developers. +Em cada um desses casos, muito sofrimento e trabalho extra poderiam ter sido +evitados com alguma discussão inicial com os desenvolvedores do kernel. Como encontrar os mantenedores? @@ -200,8 +200,8 @@ prosseguir, mantendo a comunidade informada à medida que avança. Obter a aprovação oficial ------------------------- -Se o seu trabalho estiver sendo realizado em um ambiente corporativo como é o -caso da maior parte do trabalho no kernel do Linux —, você deve, obviamente, ter +Se o seu trabalho estiver sendo realizado em um ambiente corporativo, como é o +caso da maior parte do trabalho no kernel do Linux, você deve, obviamente, ter a permissão de gerentes devidamente autorizados antes de poder publicar os planos ou o código da sua empresa em uma lista de discussão pública. A publicação de código que não tenha sido liberado para lançamento sob uma diff --git a/Documentation/translations/pt_BR/process/4.Coding.rst b/Documentation/translations/pt_BR/process/4.Coding.rst index ca4c74774a91..7c7567165725 100644 --- a/Documentation/translations/pt_BR/process/4.Coding.rst +++ b/Documentation/translations/pt_BR/process/4.Coding.rst @@ -197,8 +197,8 @@ a ferramenta certa para o trabalho. Códigos que mostrem falta de atenção à concorrência terão um caminho difícil para entrar no mainline. -Regressions -*********** +Regressões +********** Um perigo final que vale a pena mencionar é este: pode ser tentador fazer uma alteração (que pode trazer grandes melhorias) que faça algo quebrar para os @@ -258,7 +258,7 @@ Note que nem todos os avisos do compilador ficam ativados por padrão. Compile o kernel com "make KCFLAGS=-W" para obter o conjunto completo. O kernel fornece várias opções de configuração que ativam recursos de -depuração; a maioria delas é encontrada no submanu "kernel hacking". Várias +depuração; a maioria delas é encontrada no submenu "kernel hacking". Várias dessas opções devem ser ativadas para qualquer kernel usado para fins de desenvolvimento ou teste. Em particular, você deve ativar: diff --git a/Documentation/translations/pt_BR/process/5.Posting.rst b/Documentation/translations/pt_BR/process/5.Posting.rst index 820a56b661db..2ac7e5557805 100644 --- a/Documentation/translations/pt_BR/process/5.Posting.rst +++ b/Documentation/translations/pt_BR/process/5.Posting.rst @@ -37,7 +37,7 @@ Antes de criar patches ---------------------- Há uma série de coisas que devem ser feitas antes de você considerar o envio -de patches para la comunidade de desenvolvimento. Elas incluem: +de patches para a comunidade de desenvolvimento. Elas incluem: - Teste o código tanto quanto puder. Faça uso das ferramentas de depuração do kernel, garanta que o kernel seja compilado com todas as combinações @@ -106,7 +106,7 @@ que podem ajudar consideravelmente: - Como uma forma de reafirmar a diretriz acima: não misture diferentes tipos de alterações no mesmo patch. Se um único patch corrige uma falha crítica de - segurança, reorganiza algumas estruturas e reformatará o código, há uma grande + segurança, reorganiza algumas estruturas e reformata o código, há uma grande chance de que ele seja ignorado e a correção importante seja perdida. - Cada patch deve resultar em um kernel que compile e funcione corretamente; se @@ -199,7 +199,7 @@ a alteração em um sistema de controle de versão. Ele será seguido por: diff associará os nomes das funções às alterações, tornando o patch resultante mais fácil de ser lido por outras pessoas. -As tags já mencionadas brevemente acima são usados para fornecer +Os marcadores (tags) já mencionados brevemente acima são usados para fornecer informações sobre como o patch surgiu. Eles são descritos em detalhes no documento :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`; o que se segue aqui é um breve resumo. @@ -215,7 +215,7 @@ documento com uma especificação implementada pelo patch:: Link: https://example.com/somewhere.html optional-other-stuff -De acordo com as orientações do Pinguim-Chefe, um marcador Link +De acordo com as orientações do Pinguim-Chefe, um marcador Link: só deve ser adicionado a um commit se ele levar a informações úteis que não são encontradas no próprio commit. @@ -279,7 +279,7 @@ Os marcadores de uso comum são: Tenha cuidado ao adicionar os marcadores mencionados acima aos seus patches, pois todos, exceto Cc:, Reported-by: e Suggested-by:, precisam de permissão explícita -fontes da pessoa nomeada. Para esses três, a permissão implícita é suficiente se +da pessoa nomeada. Para esses três, a permissão implícita é suficiente se a pessoa contribuiu para o kernel Linux usando esse nome e endereço de e-mail de acordo com os arquivos do lore ou o histórico de commits — e, no caso de Reported-by: e Suggested-by:, se fizeram o relato ou a sugestão publicamente. @@ -322,7 +322,7 @@ kernel incentiva as pessoas a pecarem pelo excesso, enviando cópias demais; nã assuma que as pessoas relevantes verão sua publicação nas listas de discussão. Em particular, as cópias devem ir para: -- O(s) mantenedor(es) do(s) subsistema(s) afetado(s). Como descrito antes, o + - O(s) mantenedor(es) do(s) subsistema(s) afetado(s). Como descrito antes, o arquivo MAINTAINERS é o primeiro lugar para procurar por essas pessoas. - Outros desenvolvedores que estiveram trabalhando na mesma área — especialmente diff --git a/Documentation/translations/pt_BR/process/6.Followthrough.rst b/Documentation/translations/pt_BR/process/6.Followthrough.rst index d6bdaa2cb8a4..dbdf479bb063 100644 --- a/Documentation/translations/pt_BR/process/6.Followthrough.rst +++ b/Documentation/translations/pt_BR/process/6.Followthrough.rst @@ -58,7 +58,17 @@ fácil se você mantiver algumas coisas em mente: de codificação e pedidos para refatorar parte do seu código em seções compartilhadas do kernel. Uma das funções dos mantenedores é manter as coisas com a mesma aparência. Às vezes, isso significa que aquele truque inteligente - (*clever hack*) em seu driver para contornar um problema + (*clever hack*) em seu driver para contornar um problema na verdade precisa + se tornar um recurso generalizado do kernel, pronto para a próxima vez. + +O que tudo isso significa é que, quando os revisores lhe enviam comentários, +você precisa prestar atenção às observações técnicas que eles estão fazendo. +Não deixe que a forma como eles se expressam, ou o seu próprio orgulho, impeçam +que isso aconteça. Quando você receber comentários de revisão em um patch, +reserve um tempo para entender o que o revisor está tentando dizer. Se +possível, corrija as coisas que o revisor está pedindo para você corrigir. E +responda ao revisor: agradeça-o e descreva como você responderá às suas +perguntas. Note que você não precisa concordar com todas as mudanças sugeridas pelos revisores. Se você acredita que o revisor entendeu mal o seu código, explique @@ -67,7 +77,7 @@ sugerida, descreva-a e justifique a sua solução para o problema. Se as suas explicações fizerem sentido, o revisor as aceitará. Contudo, caso a sua explicação não seja persuasiva — especialmente se outros começarem a concordar com o revisor —, reserve um tempo para repensar as coisas. Pode ser fácil ficar -ceguificado por sua própria solução para um problema, a ponto de não perceber +cego por sua própria solução para um problema, a ponto de não perceber que algo está fundamentalmente errado ou que, talvez, você não esteja sequer resolvendo o problema certo. diff --git a/Documentation/translations/pt_BR/process/8.Conclusion.rst b/Documentation/translations/pt_BR/process/8.Conclusion.rst index d5af31e7c4d9..2696ea16756e 100644 --- a/Documentation/translations/pt_BR/process/8.Conclusion.rst +++ b/Documentation/translations/pt_BR/process/8.Conclusion.rst @@ -21,6 +21,7 @@ encontradas através do índice do kernel do LWN em: https://lwn.net/Kernel/Index/ Além disso, um recurso valioso para os desenvolvedores do kernel é: + https://kernelnewbies.org/ E, claro, não se deve esquecer o https://kernel.org/, o local definitivo @@ -29,7 +30,7 @@ para informações sobre os lançamentos do kernel. Há uma série de livros sobre o desenvolvimento do kernel: Linux Device Drivers, 3rd Edition (Jonathan Corbet, Alessandro - Rubini, and Greg Kroah-Hartman). Online at + Rubini, e Greg Kroah-Hartman). Disponível online em https://lwn.net/Kernel/LDD3/. Linux Kernel Development (Robert Love). diff --git a/Documentation/translations/pt_BR/process/adding-syscalls.rst b/Documentation/translations/pt_BR/process/adding-syscalls.rst index cdf8b5033765..99607ee5f949 100644 --- a/Documentation/translations/pt_BR/process/adding-syscalls.rst +++ b/Documentation/translations/pt_BR/process/adding-syscalls.rst @@ -7,7 +7,7 @@ Adicionando uma Nova Chamada de Sistema Este documento descreve o que está envolvido na adição de uma nova chamada de sistema (system call) ao kernel Linux, indo além dos conselhos normais de submissão em -:ref:`Documentation/process/submitting-patches.rst <submittingpatches>`. +:ref:`Documentation/translations/pt_BR/process/submitting-patches.rst <pt_BR_submittingpatches>`. Alternativas às Chamadas de Sistema @@ -122,10 +122,10 @@ como o handle (identificador) para esse objeto -- não invente um novo tipo de handle de objeto para o espaço do usuário quando o kernel já possui mecanismos e semânticas bem definidas para o uso de descritores de arquivo. -Se a sua nova chamada de sistema (2) de fato retornar un novo descritor de +Se a sua nova chamada de sistema xyzzy(2) de fato retornar um novo descritor de arquivo, então o argumento de flags deve incluir um valor que seja equivalente a definir ``O_CLOEXEC`` no novo FD. Isso torna possível para o espaço do usuário -fechar a janela de tempo entre a chamada ``()`` e a execução de +fechar a janela de tempo entre a chamada ``xyzzy()`` e a execução de ``fcntl(fd, F_SETFD, FD_CLOEXEC)``, onde um ``fork()`` e ``execve()`` inesperados em outra thread poderiam vazar um descritor para o programa executado. (Contudo, resista à tentação de reutilizar o valor real da constante ``O_CLOEXEC``, pois @@ -138,7 +138,7 @@ deve considerar o que significa usar a família de chamadas de sistema pronto para leitura ou escrita é a maneira normal de o kernel indicar ao espaço do usuário que um evento ocorreu no objeto correspondente do kernel. -Se a sua nova chamada de sistema (2) envolver um argumento de nome de arquivo +Se a sua nova chamada de sistema xyzzy(2) envolver um argumento de nome de arquivo (filename):: int sys_xyzzy(const char __user *path, ..., unsigned int flags); @@ -152,18 +152,18 @@ o arquivo em questão; em particular, permite que o espaço do usuário solicite funcionalidade para um descritor de arquivo já aberto usando a flag ``AT_EMPTY_PATH``, fornecendo efetivamente uma operação fxyzzy(3) de graça:: - - xyzzyat(AT_FDCWD, path, ..., 0) é equivalente a (path,...) + - xyzzyat(AT_FDCWD, path, ..., 0) é equivalente a xyzzy(path,...) - xyzzyat(fd, "", ..., AT_EMPTY_PATH) é equivalente a fxyzzy(fd, ...) (Para mais detalhes sobre a justificativa das chamadas \*at(), veja a página de manual :manpage:`openat(2)`; para um exemplo de AT_EMPTY_PATH, veja a página de manual :manpage:`fstatat(2)`.) -Se a sua nova chamada de sistema (2) envolver um parâmetro que descreve um +Se a sua nova chamada de sistema xyzzy(2) envolver um parâmetro que descreve um deslocamento (offset) dentro de um arquivo, mude o seu tipo para ``loff_t`` para que offsets de 64 bits possam ser suportados mesmo em arquiteturas de 32 bits. -Se a sua nova chamada de sistema (2) envolver funcionalidades privilegiadas, +Se a sua nova chamada de sistema xyzzy(2) envolver funcionalidades privilegiadas, ela precisa ser governada pelo bit de capacidade (capability) do Linux apropriado (verificado com uma chamada a ``capable()``), conforme descrito na página de manual :manpage:`capabilities(7)`. Escolha um bit de capacidade existente que governe @@ -172,7 +172,7 @@ apenas uma vaga relação sob o mesmo bit, pois isso vai contra o propósito das capabilities de dividir o poder do root. Em particular, evite adicionar novos usos para a capacidade ``CAP_SYS_ADMIN``, que já é excessivamente generalista. -Se a sua nova chamada de sistema (2) manipular um processo diferente do +Se a sua nova chamada de sistema xyzzy(2) manipular um processo diferente do processo que a chamou, ela deve ser restrita (usando uma chamada a ``ptrace_may_access()``) para que apenas um processo chamador com as mesmas permissões do processo alvo, ou com as capacidades necessárias, possa manipular @@ -211,7 +211,7 @@ kernel, devem sempre ser enviadas com cópia (cc'ed) para linux-api@vger.kernel. Implementação Genérica de Chamadas de Sistema --------------------------------------------- -O ponto de entrada principal para a sua nova chamada de sistema (2) será chamado +O ponto de entrada principal para a sua nova chamada de sistema xyzzy(2) será chamado de ``sys_xyzzy()``, mas você deve adicionar esse ponto de entrada com a macro ``SYSCALL_DEFINEn()`` apropriada, em vez de fazer isso explicitamente. O 'n' indica o número de argumentos da chamada de sistema, e a macro recebe o nome da @@ -242,7 +242,7 @@ O arquivo ``kernel/sys_ni.c`` fornece uma implementação de stub de fallback pa cada chamada de sistema, retornando ``-ENOSYS``. Adicione a sua nova chamada de sistema aqui também:: - COND_SYSCALL(sys_xyzzy); + COND_SYSCALL(xyzzy); A sua nova funcionalidade de kernel, e a chamada de sistema que a controla, deve normalmente ser opcional, portanto adicione uma opção ``CONFIG`` (tipicamente em @@ -259,7 +259,7 @@ normalmente ser opcional, portanto adicione uma opção ``CONFIG`` (tipicamente Para resumir, você precisa de um commit que inclua: - Opção ``CONFIG`` para a nova função, normalmente em ``init/Kconfig`` - - ``SYSCALL_DEFINEn(, ...)`` para o ponto de entrada + - ``SYSCALL_DEFINEn(xyzzy, ...)`` para o ponto de entrada - Protótipo correspondente em ``include/linux/syscalls.h`` - Entrada na tabela genérica em ``include/uapi/asm-generic/unistd.h`` - Stub de fallback em ``kernel/sys_ni.c`` @@ -289,7 +289,7 @@ ajustar ``arch/*/kernel/Makefile.syscalls``. Como o ``scripts/syscall.tbl`` serve como uma tabela de syscall comum para múltiplas arquiteturas, uma nova entrada é necessária nesta tabela:: - 468 common sys_xyzzy + 468 common xyzzy sys_xyzzy Note que adicionar uma entrada ao ``scripts/syscall.tbl`` com a ABI "common" também afeta todas as arquiteturas que compartilham essa tabela. Para alterações @@ -304,7 +304,7 @@ correspondentes também devem ser feitas em ``arch/*/kernel/Makefile.syscalls``: Para resumir, você precisa de um commit que inclua: - Opção ``CONFIG`` para a nova função, normalmente em ``init/Kconfig`` - - ``SYSCALL_DEFINEn(, ...)`` para o ponto de entrada + - ``SYSCALL_DEFINEn(xyzzy, ...)`` para o ponto de entrada - Protótipo correspondente em ``include/linux/syscalls.h`` - Nova entrada em ``scripts/syscall.tbl`` - (Se necessário) Atualizações de Makefile em ``arch/*/kernel/Makefile.syscalls`` @@ -320,11 +320,11 @@ de sistema não seja especial de alguma forma (veja abaixo), isso envolve uma entrada "common" (para x86_64 e x32) em ``arch/x86/entry/syscalls/syscall_64.tbl``:: - 333 common sys_xyzzy + 333 common xyzzy sys_xyzzy e uma entrada "i386" em ``arch/x86/entry/syscalls/syscall_32.tbl``:: - 380 i386 sys_xyzzy + 380 i386 xyzzy sys_xyzzy Novamente, esses números estão sujeitos a alterações caso ocorram conflitos na janela de mesclagem (merge window) relevante. @@ -414,7 +414,7 @@ a versão compat; a entrada em ``include/uapi/asm-generic/unistd.h`` deve usar Para resumir, você precisa de: - - uma macro ``COMPAT_SYSCALL_DEFINEn(, ...)`` para o ponto de entrada compat + - uma macro ``COMPAT_SYSCALL_DEFINEn(xyzzy, ...)`` para o ponto de entrada compat - protótipo correspondente em ``include/linux/compat.h`` - (se necessário) struct de mapeamento de 32 bits em ``include/linux/compat.h`` - instância de ``__SC_COMP``, e não de ``__SYSCALL``, em @@ -433,11 +433,11 @@ Você precisa estender a entrada em ``scripts/syscall.tbl`` com uma coluna extra para indicar que um programa de espaço do usuário de 32 bits rodando em um kernel de 64 bits deve atingir o ponto de entrada compat:: - 468 common sys_xyzzy compat_sys_xyzzy + 468 common xyzzy sys_xyzzy compat_sys_xyzzy Para resumir, você precisa de: - - ``COMPAT_SYSCALL_DEFINEn(, ...)`` para o ponto de entrada compat + - ``COMPAT_SYSCALL_DEFINEn(xyzzy, ...)`` para o ponto de entrada compat - Protótipo correspondente em ``include/linux/compat.h`` - Modificação da entrada em ``scripts/syscall.tbl`` para incluir uma coluna "compat" extra @@ -454,7 +454,7 @@ compatibilidade voltadas para o espaço do usuário de 32 bits (AArch32): ``arch/arm64/tools/syscall_32.tbl``. Você precisa adicionar uma linha adicional a esta tabela especificando o ponto de entrada compat:: - 468 common sys_xyzzy compat_sys_xyzzy + 468 common xyzzy sys_xyzzy compat_sys_xyzzy Chamadas de Sistema de Compatibilidade (x86) @@ -467,7 +467,7 @@ Primeiro, a entrada em ``arch/x86/entry/syscalls/syscall_32.tbl`` ganha uma coluna extra para indicar que um programa de espaço do usuário de 32 bits rodando em um kernel de 64 bits deve atingir o ponto de entrada compat:: - 380 i386 sys_xyzzy __ia32_compat_sys_xyzzy + 380 i386 xyzzy sys_xyzzy __ia32_compat_sys_xyzzy Segundo, você precisa definir o que deve acontecer para a versão da ABI x32 da nova chamada de sistema. Há uma escolha aqui: o layout dos argumentos deve @@ -479,9 +479,9 @@ corresponder à versão de 32 bits, e a entrada em ``arch/x86/entry/syscalls/syscall_64.tbl`` é dividida para que os programas x32 atinjam o wrapper de compatibilidade:: - 333 64 sys_xyzzy + 333 64 xyzzy sys_xyzzy ... - 555 x32 __x32_compat_sys_xyzzy + 555 x32 xyzzy __x32_compat_sys_xyzzy Se não houver ponteiros envolvidos, então é preferível reutilizar a chamada de sistema de 64 bits para a ABI x32 (e, consequentemente, a entrada em @@ -518,14 +518,14 @@ Para x86_64, isso é implementado como um ponto de entrada ``stub_xyzzy`` em ``arch/x86/entry/entry_64.S``, e a entrada correspondente na tabela de syscalls (``arch/x86/entry/syscalls/syscall_64.tbl``) é ajustada para refletir:: - 333 common stub_xyzzy + 333 common xyzzy stub_xyzzy O equivalente para programas de 32 bits executados em um kernel de 64 bits é normalmente chamado de ``stub32_xyzzy`` e implementado em ``arch/x86/entry/entry_64_compat.S``, com o respectivo ajuste na tabela de syscalls em ``arch/x86/entry/syscalls/syscall_32.tbl``:: - 380 i386 sys_xyzzy stub32_xyzzy + 380 i386 xyzzy sys_xyzzy stub32_xyzzy Se a chamada de sistema precisar de uma camada de compatibilidade (como na seção anterior), a versão ``stub32_`` precisará chamar a versão @@ -579,12 +579,16 @@ espaço do usuário, o cabeçalho correspondente precisará ser instalado para compilar o teste. Certifique-se de que o autoteste seja executado com sucesso em todas as -arquiteturas suportadas. Por exemplo, verifique se ele funciona quando compitado +arquiteturas suportadas. Por exemplo, verifique se ele funciona quando compilado como um programa ABI x86_64 (-m64), x86_32 (-m32) e x32 (-mx32). Para testes mais extensos e minuciosos de novas funcionalidades, você também deve considerar a adição de testes ao Linux Test Project ou ao projeto -xfstests para alterações relacionadas +xfstests para alterações relacionadas a sistemas de arquivos. + + - https://linux-test-project.github.io/ + - git://git.kernel.org/pub/scm/fs/xfs/xfstests-dev.git + Página de Manual (Man Page) --------------------------- diff --git a/Documentation/translations/pt_BR/process/applying-patches.rst b/Documentation/translations/pt_BR/process/applying-patches.rst index 313401bc2335..143603b991f7 100644 --- a/Documentation/translations/pt_BR/process/applying-patches.rst +++ b/Documentation/translations/pt_BR/process/applying-patches.rst @@ -1,5 +1,7 @@ .. SPDX-License-Identifier: GPL-2.0 +.. _pt_BR_applying_patches: + Aplicando Patches ao Kernel Linux +++++++++++++++++++++++++++++++++ @@ -12,7 +14,7 @@ Autor Original: manualmente, você quase certamente desejará considerar o uso do Git. Uma pergunta feita com frequência na Linux Kernel Mailing List é como aplicar -an patch ao kernel ou, mais especificamente, a qual kernel base um patch para +um patch ao kernel ou, mais especificamente, a qual kernel base um patch para uma das muitas árvores/branches deve ser aplicado. Esperamos que este documento explique isso a você. @@ -171,7 +173,7 @@ fazer a alteração para fazê-la caber). O arquivo resultante pode ou não estar correto, dependendo do motivo pelo qual o arquivo estava diferente do esperado. -Isso geralmente acontece se você tentar aplicar un patch que foi gerado contra uma +Isso geralmente acontece se você tentar aplicar um patch que foi gerado contra uma versão de kernel diferente daquela que você está tentando modificar. Se você receber uma mensagem como ``Hunk #3 FAILED at 2387.``, significa que o diff --git a/Documentation/translations/pt_BR/process/backporting.rst b/Documentation/translations/pt_BR/process/backporting.rst index ce3f9fb4fc5b..afcff7085700 100644 --- a/Documentation/translations/pt_BR/process/backporting.rst +++ b/Documentation/translations/pt_BR/process/backporting.rst @@ -357,7 +357,7 @@ Processo de resolução ~~~~~~~~~~~~~~~~~~~~~ Às vezes, a coisa mais fácil a fazer é apenas remover tudo, exceto a primeira -parteda do conflito, deixando o arquivo essencialmente inalterado, e aplicar +parte do conflito, deixando o arquivo essencialmente inalterado, e aplicar as alterações manualmente. Talvez o patch esteja alterando um argumento de chamada de função de ``0`` para ``1``, enquanto uma alteração conflitante adicionou um parâmetro totalmente novo (e insignificante) ao final da lista de @@ -403,7 +403,7 @@ de volta (``git mv`` e commitando novamente) e, finalmente, esmagar (squash) o resultado usando ``git rebase -i`` (veja o `tutorial de rebase`_) para que ele apareça como um único commit quando você terminar. -.. _tutorial de rebase: [https://medium.com/@slamflipstrom/a-beginners-guide-to-squashing-commits-with-git-rebase-8185cf6e62ec](https://medium.com/@slamflipstrom/a-beginners-guide-to-squashing-commits-with-git-rebase-8185cf6e62ec) +.. _tutorial de rebase: https://medium.com/@slamflipstrom/a-beginners-guide-to-squashing-commits-with-git-rebase-8185cf6e62ec Pegadinhas ---------- diff --git a/Documentation/translations/pt_BR/process/code-of-conduct-interpretation.rst b/Documentation/translations/pt_BR/process/code-of-conduct-interpretation.rst index 866c9f7e7a12..c40886e3d3ce 100644 --- a/Documentation/translations/pt_BR/process/code-of-conduct-interpretation.rst +++ b/Documentation/translations/pt_BR/process/code-of-conduct-interpretation.rst @@ -1,5 +1,7 @@ .. SPDX-License-Identifier: GPL-2.0 +.. _pt_BR_code_of_conduct_interpretation: + Interpretação do Código de Conduta do Kernel Linux ================================================== diff --git a/Documentation/translations/pt_BR/process/code-of-conduct.rst b/Documentation/translations/pt_BR/process/code-of-conduct.rst index 1ab171bf21cf..8a3da70b7e6b 100644 --- a/Documentation/translations/pt_BR/process/code-of-conduct.rst +++ b/Documentation/translations/pt_BR/process/code-of-conduct.rst @@ -84,5 +84,5 @@ disponível em https://www.contributor-covenant.org/version/1/4/code-of-conduct. Interpretação ============= -Consulte o documento :ref:`code_of_conduct_interpretation` para entender como a -comunidade do kernel Linux interpretará este documento. +Consulte o documento :ref:`pt_BR_code_of_conduct_interpretation` para +entender como a comunidade do kernel Linux interpretará este documento. diff --git a/Documentation/translations/pt_BR/process/coding-assistants.rst b/Documentation/translations/pt_BR/process/coding-assistants.rst new file mode 100644 index 000000000000..2055af34a908 --- /dev/null +++ b/Documentation/translations/pt_BR/process/coding-assistants.rst @@ -0,0 +1,60 @@ +.. SPDX-License-Identifier: GPL-2.0 + +IA Assistente de código ++++++++++++++++++++++++ + +Esta documentação fornece um guia para ferramentas de IA e desenvolvedores que +usam IA como assistente para contribuir para o kernel do Linux. + +Ferramentas de IA que ajudam desenvolvedores do Linux kernel devem seguir os +padrões de desenvolvimento do kernel: + +* Documentation/process/development-process.rst +* Documentation/process/coding-style.rst +* Documentation/process/submitting-patches.rst + +Para guias e conteúdo sobre códigos gerados por assistentes de IA veja: + +* Documentation/process/generated-content.rst + +Licenças e Requisitos Legais +============================ + +Todas as contribuições devem estar de acordo com os requisitos de licença do +kernel: + +* Todo código deve ser compatível apenas com GPL-2.0 +* Use identificadores SPDX de licença apropriados +* Veja Documentation/process/license-rules.rst para mais detalhes + +Assinatura e certificado de origem do desenvolvedor +=================================================== + +Agentes de IA NÃO DEVEM adicionar tags Signed-off-by. Apenas pessoas +podem legalmente certificar o Certificado de Origem do Desenvolvedor (DCO). +A pessoa que envia é responsável por: + +* Revisar todo código gerado por IA +* Garantir conformidade com os requisitos de licença +* Acrescentar sua própria tag Signed-off-by para certificar o DCO +* Assumir toda responsabilidade pela contribuição + +Atribuições +=========== + +Quando ferramentas de IA contribuírem para o desenvolvimento do kernel, +a atribuição adequada ajuda a rastrear a função da IA no processo de +desenvolvimento. Contribuições devem incluir a tag de assistência seguindo este +formato:: + + Assisted-by: LLM [FERRAMENTA1] [FERRAMENTA2] + +* ``[FERRAMENTA1] [FERRAMENTA2]`` são ferramentas de análise especializada + opcionais (Exemplo: coccinelle, sparse, smatch, clang-tidy) + +Ferramentas básicas de desenvolvimento (git, gcc, make, editors) não são +listadas. + +Exemplo:: + + Assisted-by: LLM coccinelle sparse
\ No newline at end of file diff --git a/Documentation/translations/pt_BR/process/coding-style.rst b/Documentation/translations/pt_BR/process/coding-style.rst new file mode 100644 index 000000000000..ac9bf0a716bc --- /dev/null +++ b/Documentation/translations/pt_BR/process/coding-style.rst @@ -0,0 +1,1320 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _pt_BR_codingstyle: + +Estilo de codificação do kernel Linux +===================================== + +Este é um breve documento descrevendo o estilo de codificação preferido +para o kernel Linux. O estilo de codificação é muito pessoal, e eu não +**forçarei** minhas opiniões a ninguém, mas isso é o que vale para tudo +que eu tenha que manter, e eu preferiria isso para a maioria das outras +coisas também. Por favor, considere pelo menos os pontos aqui apresentados. + +Primeiramente, eu sugiro imprimir uma cópia dos padrões de codificação do GNU, +e NÃO lê-la. Queime-as, é um grande gesto simbólico. + +De qualquer forma, aqui vai: + + +1) Indentação +------------- + +As tabulações têm 8 caracteres, e portanto as indentações também têm 8 +caracteres. Há movimentos heréticos que tentam fazer com que as indentações +tenham 4 (ou até 2!) caracteres de profundidade, e isso é semelhante a +tentar definir o valor de PI como 3. + +Justificativa: A ideia central da indentação é definir claramente onde um +bloco de controle começa e termina. Especialmente quando você esteve olhando +para a tela por 20 horas seguidas, você vai achar muito mais fácil ver como +a indentação funciona se ela for mais ampla. + +Agora, algumas pessoas afirmarão que ter indentações de 8 caracteres faz +o código se deslocar demais para a direita e dificultam a leitura em um +terminal de 80 caracteres. A resposta é que, se você precisar de mais de 3 +níveis de indentação, você já está em apuros de qualquer forma, e deve +corrigir seu programa. + +Em resumo, indentações de 8 caracteres deixam as coisas mais fáceis de ler, e +têm o benefício adicional de avisar quando você está aninhando suas funções +em excesso. Atenda a esse aviso. + +A maneira preferida de aliviar vários níveis de indentação em uma instrução +``switch`` é alinhar o ``switch`` e seus rótulos subordinados ``case`` na +mesma coluna, em vez de indentar duplamente os rótulos ``case``. Por exemplo: + +.. code-block:: c + + switch (suffix) { + case 'G': + case 'g': + mem <<= 30; + break; + case 'M': + case 'm': + mem <<= 20; + break; + case 'K': + case 'k': + mem <<= 10; + fallthrough; + default: + break; + } + +Não coloque múltiplas instruções em uma única linha, a menos que você tenha +algo para esconder: + +.. code-block:: c + + if (condition) do_this; + do_something_everytime; + +Não use vírgulas para evitar usar chaves: + +.. code-block:: c + + if (condition) + do_this(), do_that(); + +Sempre use chaves para múltiplas instruções: + +.. code-block:: c + + if (condition) { + do_this(); + do_that(); + } + +Também não coloque múltiplas atribuições em uma única linha. O estilo de +codificação do kernel é extremamente simples. Evite expressões complicadas. + + +Fora de comentários, documentação e, exceto em Kconfig, espaços nunca são +usados para indentação, e o exemplo acima foi deliberadamente quebrado. + +Obtenha um editor decente e não deixe espaços em branco no final das linhas. + + +2) Quebrando linhas longas e strings +------------------------------------ + +O estilo de codificação trata principalmente da legibilidade e da +manutenibilidade usando ferramentas comumente disponíveis. + +O limite preferido para o comprimento de uma única linha é de 80 colunas. + +Instruções com mais de 80 colunas devem ser quebradas em partes sensatas, +a menos que exceder 80 colunas aumente significativamente a legibilidade e +não esconda informações. + +Os descendentes são sempre substancialmente mais curtos do que o pai e são +colocados substancialmente à direita. Um estilo muito usado é alinhar os +descendentes ao parêntese de abertura de uma função. + +Essas mesmas regras são aplicadas aos cabeçalhos de função com uma lista de +argumentos longa. + +No entanto, nunca quebre strings visíveis ao usuário, como mensagens +``printk``, porque isso prejudica a capacidade de fazer ``grep`` nelas. + + +3) Posicionamento de chaves e espaços +------------------------------------- + +A outra questão que sempre surge no estilo em C é o posicionamento das +chaves. Ao contrário do tamanho da indentação, há poucos motivos técnicos +para escolher uma estratégia de posicionamento em vez de outra, mas a forma +preferida, como nos mostraram os profetas Kernighan e Ritchie, é colocar a +chave de abertura no final da linha e a chave de fechamento no início, assim: + +.. code-block:: c + + if (x is true) { + we do y + } + +Isso se aplica a todos os blocos de instruções que não sejam funções (if, +switch, for, while, do). Por exemplo: + +.. code-block:: c + + switch (action) { + case KOBJ_ADD: + return "add"; + case KOBJ_REMOVE: + return "remove"; + case KOBJ_CHANGE: + return "change"; + default: + return NULL; + } + +No entanto, há um caso especial: as funções, que têm a chave de abertura no +início da linha seguinte, assim: + +.. code-block:: c + + int function(int x) + { + body of function + } + +Pessoas heréticas por todo o mundo afirmaram que essa inconsistência é ... +bem ... inconsistente, mas todas as pessoas de bom senso sabem que (a) K&R +estão **corretos** e (b) K&R estão certos. Além disso, as funções são +especiais de qualquer forma (você não pode aninhá-las em C). + +Observe que a chave de fechamento fica vazia em uma linha própria, **exceto** +nos casos em que ela é seguida por uma continuação da mesma instrução, ou +seja, um ``while`` em um do-statement ou um ``else`` em um if-statement, como +neste exemplo: + +.. code-block:: c + + do { + body of do-loop + } while (condition); + +e + +.. code-block:: c + + if (x == y) { + .. + } else if (x > y) { + ... + } else { + .... + } + +Justificativa: K&R. + +Além disso, observe que esse posicionamento de chaves também minimiza o +número de linhas vazias (ou quase vazias), sem qualquer perda de +legibilidade. Assim, como o suprimento de linhas novas na sua tela não é um +recurso renovável (pense em telas de terminal de 25 linhas), você tem mais +linhas vazias para colocar comentários. + +Não use chaves desnecessariamente quando uma única instrução basta. + +.. code-block:: c + + if (condition) + action(); + +e + +.. code-block:: c + + if (condition) + do_this(); + else + do_that(); + +Isso não se aplica se apenas um ramo de uma instrução condicional for uma +única instrução; nesse último caso, use chaves em ambos os ramos: + +.. code-block:: c + + if (condition) { + do_this(); + do_that(); + } else { + otherwise(); + } + +Além disso, use chaves quando um laço contiver mais de uma instrução simples: + +.. code-block:: c + + while (condition) { + if (test) + do_something(); + } + +3.1) Espaços +************ + +O estilo do kernel Linux para o uso de espaços depende (em grande parte) do +uso de função versus palavra-chave. Use um espaço após (a maioria das) +palavras-chave. As exceções notáveis são ``sizeof``, ``typeof``, ``alignof`` e +``__attribute__``, que parecem um pouco com funções (e geralmente são usadas +com parênteses no Linux, embora não sejam obrigatórias na linguagem, como em: +``sizeof info`` depois que ``struct fileinfo info;`` é declarado). + +Então use um espaço após estas palavras-chave:: + + if, switch, case, for, do, while + +mas não com ``sizeof``, ``typeof``, ``alignof`` ou ``__attribute__``. Por +exemplo, + +.. code-block:: c + + + s = sizeof(struct file); + +Não adicione espaços ao redor (dentro) de expressões entre parênteses. Este +exemplo é **ruim**: + +.. code-block:: c + + + s = sizeof( struct file ); + +Ao declarar dados de ponteiro ou uma função que retorna um tipo de ponteiro, o +uso preferido de ``*`` fica adjacente ao nome dos dados ou ao nome da função e +não adjacente ao nome do tipo. Exemplos: + +.. code-block:: c + + + char *linux_banner; + unsigned long long memparse(char *ptr, char **retptr); + char *match_strdup(substring_t *s); + +Use um espaço em volta (de cada lado) da maioria dos operadores binários e +ternários, como qualquer um destes:: + + = + - < > * / % | & ^ <= >= == != ? : + +mas sem espaço após operadores unários:: + + & * + - ~ ! sizeof typeof alignof __attribute__ defined + +sem espaço antes dos operadores unários pós-fixados de incremento e +decremento:: + + ++ -- + +sem espaço após os operadores unários prefixados de incremento e +decremento:: + + ++ -- + +e sem espaço ao redor dos operadores de membro de estrutura ``.`` e ``->``. + +Não deixe espaços em branco no final das linhas. Alguns editores com +indentação ``inteligente`` inserem espaços no início das novas linhas conforme +apropriado, para que você possa começar a digitar a próxima linha de código +imediatamente. No entanto, alguns desses editores não removem o espaço em +branco se você acabar não colocando uma linha de código ali, como quando deixa +uma linha em branco. Como resultado, você termina com linhas contendo espaço +em branco no final. + +O Git avisará você sobre patches que introduzem espaço em branco no final e +pode remover esse espaço automaticamente para você; entretanto, se você +aplicar uma série de patches, isso pode fazer com que patches posteriores da +série falhem ao alterar suas linhas de contexto. + + +4) Nomeação +----------- + +C é uma linguagem espartana, e suas convenções de nomenclatura devem seguir o +mesmo caminho. Ao contrário dos programadores em Modula-2 e Pascal, os +programadores em C não usam nomes bonitinhos como ThisVariableIsATemporaryCounter. +Um programador em C chamaria essa variável de ``tmp``, o que é muito mais fácil +de escrever e não é menos fácil de entender. + +ENTRETANTO, embora nomes em camelCase sejam desencorajados, nomes descritivos +para variáveis globais são essenciais. Chamar uma função global de ``foo`` é +um crime. + +Variáveis GLOBAIS (a serem usadas somente se você **realmente** precisar) devem +ter nomes descritivos, assim como as funções globais. Se você tiver uma função +que conta o número de usuários ativos, você deve chamá-la de +``count_active_users()`` ou algo parecido; você **não** deve chamá-la de +``cntusr()``. + +Codificar o tipo de uma função no nome (a chamada notação Húngara) é absurdo - +o compilador conhece os tipos de qualquer forma e pode verificar isso, e isso +só confunde o programador. + +Nomes de variáveis locais devem ser curtos e diretos. Se você tiver algum +contador inteiro aleatório de loop, provavelmente deve ser chamado de ``i``. +Chamá-lo de ``loop_counter`` é improdutivo, se não houver chance de ser mal +interpretado. Da mesma forma, ``tmp`` pode ser praticamente qualquer tipo de +variável usada para manter um valor temporário. + +Se você tem medo de misturar os nomes de variáveis locais, você tem outro +problema, chamado síndrome de desequilíbrio de hormônio de crescimento da +função. Veja o capítulo 6 (Funções). + +Para nomes de símbolos e documentação, evite introduzir o uso novo de +'master / slave' (ou 'slave' independente de 'master') e 'blacklist / +whitelist'. + +Substituições recomendadas para 'master / slave' são: + '{primary,main} / {secondary,replica,subordinate}' + '{initiator,requester} / {target,responder}' + '{controller,host} / {device,worker,proxy}' + 'leader / follower' + 'director / performer' + +Substituições recomendadas para 'blacklist/whitelist' são: + 'denylist / allowlist' + 'blocklist / passlist' + +Exceções para introduzir novos usos são manter uma ABI/API do espaço do +usuário, ou ao atualizar código para um hardware ou especificação de +protocolo existente (a partir de 2020) que exija esses termos. Para novas +especificações, traduza o uso da terminologia na especificação para o padrão +de codificação do kernel quando possível. + +5) Tipos definidos (typedefs) +----------------------------- + +Por favor, não use coisas como ``vps_t``. +É um **erro** usar ``typedef`` para estruturas e ponteiros. Quando você vê + +.. code-block:: c + + + vps_t a; + +no código-fonte, o que isso significa? +Em contraste, se diz + +.. code-block:: c + + struct virtual_container *a; + +você consegue dizer o que ``a`` é. + +Muitas pessoas pensam que ``typedef``s ``ajudam na legibilidade``. Não é bem +assim. Eles são úteis apenas para: + + (a) objetos totalmente opacos (onde o ``typedef`` é usado ativamente para + **ocultar** o que o objeto é). + + Exemplo: ``pte_t`` etc. Objetos opacos que você só pode acessar usando + as funções de acesso apropriadas. + + .. note:: + + Opacidade e ``funções de acesso`` não são boas em si mesmas. + A razão pela qual as temos para coisas como ``pte_t`` etc. é que + realmente existe absolutamente **zero** informação acessível de forma portátil + ali. + + (b) tipos inteiros claros, em que a abstração **ajuda** a evitar confusão + sobre se é ``int`` ou ``long``. + + ``u8/u16/u32`` são typedefs perfeitamente aceitáveis, embora se + encaixem melhor na categoria (d) do que aqui. + + .. note:: + + Novamente - precisa haver uma **razão** para isso. Se algo é + ``unsigned long``, não há motivo para fazer + + typedef unsigned long myflags_t; + + mas se houver uma razão clara para que em certas circunstâncias possa + ser ``unsigned int`` e em outras configurações possa ser ``unsigned + long``, então, claro, use um ``typedef``. + + (c) quando você usa ``sparse`` para criar literalmente um **novo** tipo para + verificação de tipos. + + (d) novos tipos idênticos aos tipos padrão do C99, em certas + circunstâncias excepcionais. + + Embora levasse apenas um curto período para os olhos e o cérebro se + acostumarem aos tipos padrão como ``uint32_t``, algumas pessoas ainda + se opõem ao seu uso. + + Portanto, os tipos específicos do Linux ``u8/u16/u32/u64`` e seus + equivalentes assinados, que são idênticos aos tipos padrão, são + permitidos -- embora não sejam obrigatórios em código novo seu. + + Ao editar código existente que já usa um ou outro conjunto de tipos, você + deve seguir as escolhas existentes nesse código. + + (e) tipos seguros para uso em espaço do usuário. + + Em certas estruturas visíveis ao espaço do usuário, não podemos exigir + tipos C99 nem usar a forma ``u32`` acima. Portanto, usamos ``__u32`` e + tipos semelhantes em todas as estruturas compartilhadas com o espaço do + usuário. + +Pode haver outros casos também, mas a regra básica deve ser: NUNCA use um +``typedef`` a menos que você consiga encaixar claramente em uma dessas regras. + +Em geral, um ponteiro, ou uma estrutura com elementos que podem ser acessados +diretamente, **nunca** deve ser um ``typedef``. + + +6) Funções +---------- + +As funções devem ser curtas e diretas, e fazer apenas uma coisa. Elas devem +caber em uma ou duas telas de texto (o tamanho de tela ISO/ANSI é 80x24, +como todos sabem), e fazer uma coisa e fazê-la bem. + +O comprimento máximo de uma função é inversamente proporcional à complexidade +e ao nível de indentação dessa função. Então, se você tiver uma função +conceitualmente simples que seja apenas uma longa (mas simples) instrução +``switch``, em que você precisa fazer várias pequenas coisas para muitos casos +diferentes, é aceitável ter uma função mais longa. + +No entanto, se você tiver uma função complexa e suspeitar que um estudante +do primeiro ano do ensino médio, menos talentoso, talvez nem entenda do que +se trata a função, você deve obedecer aos limites máximos ainda mais de +perto. Use funções auxiliares com nomes descritivos (você pode pedir ao +compilador para incorporá-las em linha se achar que é crítico para o +desempenho, e provavelmente ele fará um trabalho melhor do que você faria). + +Outra medida da função é o número de variáveis locais. Elas não devem exceder +5-10, ou algo está errado. Reflita sobre a função e divida em partes menores. +Um cérebro humano geralmente consegue rastrear facilmente cerca de 7 coisas +diferentes; qualquer quantidade acima disso o confunde. Você sabe que é +brilhante, mas talvez queira entender o que fez daqui a 2 semanas. + +Nos arquivos de código-fonte, separe as funções com uma linha em branco. Se a +função for exportada, a macro **EXPORT** para ela deve seguir imediatamente +depois da linha da chave de fechamento da função. Por exemplo: + +.. code-block:: c + + int system_is_up(void) + { + return system_state == SYSTEM_RUNNING; + } + EXPORT_SYMBOL(system_is_up); + +6.1) Protótipos de função +************************* + +Nos protótipos de função, inclua nomes de parâmetros junto com seus tipos de +dados. Embora isso não seja obrigatório pela linguagem C, é preferido no Linux +porque é uma maneira simples de adicionar informações valiosas para o leitor. + +Não use a palavra-chave ``extern`` em declarações de função, pois isso torna +as linhas mais longas e não é estritamente necessário. + +Ao escrever protótipos de função, por favor mantenha a `ordem dos elementos +regular <https://lore.kernel.org/mm-commits/CAHk-=wiOCLRny5aifWNhr621kYrJwhfURsa0vFPeUEm8mF0ufg@mail.gmail.com/>`_. +Por exemplo, usando este exemplo de declaração de função:: + + __init void * __must_check action(enum magic value, size_t size, u8 count, + char *fmt, ...) __printf(4, 5) __malloc; + +A ordem preferida dos elementos para um protótipo de função é: + +- classe de armazenamento (abaixo, ``static __always_inline``, observando que + ``__always_inline`` é tecnicamente um atributo, mas é tratado como ``inline``) +- atributos de classe de armazenamento (aqui, ``__init`` -- ou seja, + declarações de seção, mas também coisas como ``__cold``) +- tipo de retorno (aqui, ``void *``) +- atributos do tipo de retorno (aqui, ``__must_check``) +- nome da função (aqui, ``action``) +- parâmetros da função (aqui, ``(enum magic value, size_t size, u8 count, + char *fmt, ...)``, observando que os nomes dos parâmetros devem sempre ser + incluídos) +- atributos dos parâmetros da função (aqui, ``__printf(4, 5)``) +- atributos de comportamento da função (aqui, ``__malloc``) + +Observe que, para uma **definição** de função (ou seja, o corpo real da +função), o compilador não permite atributos de parâmetro da função depois dos +parâmetros da função. Nesses casos, eles devem vir depois dos atributos da +classe de armazenamento (por exemplo, observe a posição alterada de +``__printf(4, 5)`` abaixo, em comparação com o exemplo de **declaração** +acima):: + + static __always_inline __init __printf(4, 5) void * __must_check action(enum magic value, + size_t size, u8 count, char *fmt, ...) __malloc + { + ... + } + +7) Saída centralizada de funções +-------------------------------- + +Embora seja depreciado por algumas pessoas, o equivalente da instrução +``goto`` é usado com frequência pelos compiladores na forma da instrução de +salto incondicional. + +A instrução ``goto`` é útil quando uma função sai de vários pontos e é +necessária alguma tarefa comum, como limpeza. Se não for necessária nenhuma +limpeza, basta retornar diretamente. + +Escolha nomes de rótulos que indiquem o que o ``goto`` faz ou por que ele +existe. Um exemplo de nome bom poderia ser ``out_free_buffer:`` se o goto +liberar ``buffer``. Evite usar nomes do GW-BASIC como ``err1:`` e ``err2:``, +porque você teria que renumerá-los se adicionasse ou removesse caminhos de +saída, e isso também torna a correção mais difícil de verificar. + +A justificativa para usar gotos é: + +- instruções incondicionais são mais fáceis de entender e seguir +- o aninhamento é reduzido +- erros por não atualizar pontos de saída individuais ao fazer + modificações são evitados +- economiza o trabalho do compilador de otimizar e remover código redundante ;) + +.. code-block:: c + + int fun(int a) + { + int result = 0; + char *buffer; + + buffer = kmalloc(SIZE, GFP_KERNEL); + if (!buffer) + return -ENOMEM; + + if (condition1) { + while (loop1) { + ... + } + result = 1; + goto out_free_buffer; + } + ... + out_free_buffer: + kfree(buffer); + return result; + } + +Um tipo comum de bug do qual você deve estar ciente é o ``one err bugs`` +(o "bug de um erro"), que se parece com isto: + +.. code-block:: c + + err: + kfree(foo->bar); + kfree(foo); + return ret; + +O problema neste código é que, em alguns caminhos de saída, ``foo`` é NULL. +Normalmente, a correção é dividir em dois rótulos de erro +``err_free_bar:`` e ``err_free_foo:``: + +.. code-block:: c + + err_free_bar: + kfree(foo->bar); + err_free_foo: + kfree(foo); + return ret; + +Idealmente, você deve simular erros para testar todos os caminhos de saída. + + +8) Comentários +-------------- + +Comentários são bons, mas também há o perigo de comentar demais. NUNCA tente +explicar COMO o seu código funciona em um comentário: é muito melhor escrever +o código de forma que o **funcionamento** seja óbvio, e é um desperdício de +tempo explicar código mal escrito. + +Em geral, você quer que seus comentários digam O QUE o seu código faz, não +COMO. Também tente evitar colocar comentários dentro do corpo de uma função: +se a função for tão complexa que você precisa comentar partes separadas dela, +provavelmente você deveria voltar ao capítulo 6 por um tempo. Você pode fazer +pequenos comentários para notar ou avisar sobre algo particularmente esperto +(ou feio), mas tente evitar excesso. Em vez disso, coloque os comentários no +início da função, dizendo às pessoas o que ela faz e, possivelmente, POR QUE +ela faz isso. + +Ao comentar as funções da API do kernel, por favor use o formato kernel-doc. +Veja os arquivos em :ref:`Documentation/doc-guide/ <doc_guide>` e +``tools/docs/kernel-doc`` para detalhes. Observe que o perigo de comentar em +excesso se aplica aos comentários kernel-doc da mesma forma. Não adicione +kernel-doc genérico que apenas repete o que já é óbvio pela assinatura da +função. + +O estilo preferido para comentários longos (em várias linhas) é: + +.. code-block:: c + + /* + * Este é o estilo preferido para comentários em várias linhas + * no código-fonte do kernel Linux. + * Por favor, use-o de forma consistente. + * + * Descrição: uma coluna de asteriscos à esquerda, + * com linhas de início e fim quase vazias. + */ + +Também é importante comentar dados, sejam tipos básicos ou tipos derivados. +Para isso, use apenas uma declaração de dado por linha (sem vírgulas para +múltiplas declarações de dados). Isso deixa espaço para um pequeno comentário +em cada item explicando seu uso. + + +9) Você fez uma bagunça +----------------------- + +Tudo bem, todos fazemos isso. Você provavelmente foi informado por seu +auxiliar de longa data em Unix que o ``GNU emacs`` formata automaticamente os +arquivos-fonte em C para você, e você percebeu que ele realmente faz isso, mas as +configurações padrão que ele usa são menos do que desejáveis (na verdade, +elas são piores do que digitação aleatória - um número infinito de macacos +digitando no GNU emacs nunca faria um bom programa). + +Então, você pode ou se livrar do GNU emacs, ou mudar para usar valores mais +sãos. Para fazer isso, você pode colocar o seguinte no seu arquivo .emacs: + +.. code-block:: elisp + + (defun c-lineup-arglist-tabs-only (ignored) + "Line up argument lists by tabs, not spaces" + (let* ((anchor (c-langelem-pos c-syntactic-element)) + (column (c-langelem-2nd-pos c-syntactic-element)) + (offset (- (1+ column) anchor)) + (steps (floor offset c-basic-offset))) + (* (max steps 1) + c-basic-offset))) + + (dir-locals-set-class-variables + 'linux-kernel + '((c-mode . ( + (c-basic-offset . 8) + (c-label-minimum-indentation . 0) + (c-offsets-alist . ( + (arglist-close . c-lineup-arglist-tabs-only) + (arglist-cont-nonempty . + (c-lineup-gcc-asm-reg c-lineup-arglist-tabs-only)) + (arglist-intro . +) + (brace-list-intro . +) + (c . c-lineup-C-comments) + (case-label . 0) + (comment-intro . c-lineup-comment) + (cpp-define-intro . +) + (cpp-macro . -1000) + (cpp-macro-cont . +) + (defun-block-intro . +) + (else-clause . 0) + (func-decl-cont . +) + (inclass . +) + (inher-cont . c-lineup-multi-inher) + (knr-argdecl-intro . 0) + (label . -1000) + (statement . 0) + (statement-block-intro . +) + (statement-case-intro . +) + (statement-cont . +) + (substatement . +) + )) + (indent-tabs-mode . t) + (show-trailing-whitespace . t) + )))) + + (dir-locals-set-directory-class + (expand-file-name "~/src/linux-trees") + 'linux-kernel) + +Isso fará o emacs funcionar melhor com o estilo de codificação do kernel para +arquivos C abaixo de ``~/src/linux-trees``. + +Mas, mesmo que você falhe em fazer o emacs formatar de maneira sensata, nem +tudo está perdido: use ``indent``. + +Agora, novamente, o GNU indent tem as mesmas configurações sem cérebro do GNU +emacs, e é por isso que você precisa dar a ele algumas opções de linha de +comando. No entanto, isso não é tão ruim, porque até os criadores do GNU +indent reconhecem a autoridade do K&R (as pessoas do GNU não são más, apenas +estão gravemente equivocadas nessa questão), então você apenas dá ao indent as +opções ``-kr -i8`` (que significa ``K&R, indentações de 8 caracteres``), ou +usa ``scripts/Lindent``, que indenta no estilo mais recente. + +``indent`` tem muitas opções, e especialmente quando se trata de reformatação +de comentários, você pode querer dar uma olhada na página de manual. Mas +lembre-se: ``indent`` não é uma solução para programação ruim. + +Observe que você também pode usar a ferramenta ``clang-format`` para ajudá-lo +com essas regras, para reformatar rapidamente partes do seu código +automaticamente e revisar arquivos completos para detectar erros de estilo de +codificação, erros de digitação e possíveis melhorias. Também é útil para +ordenar ``#includes``, alinhar variáveis/macros, reorganizar texto e outras +tarefas semelhantes. Consulte o arquivo +:ref:`Documentation/dev-tools/clang-format.rst <clangformat>` +para obter mais detalhes. + +Algumas configurações básicas do editor, como indentação e finais de linha, +serão definidas automaticamente se você estiver usando um editor compatível com +o EditorConfig. Consulte o site oficial do EditorConfig para obter mais +informação: https://editorconfig.org/ + +10) Arquivos de configuração Kconfig +------------------------------------ + +Para todos os arquivos de configuração Kconfig* em toda a árvore de origem, +a indentação é um pouco diferente. Linhas sob uma definição ``config`` são +indentadas com uma tabulação, enquanto o texto de ajuda é indentado com mais +dois espaços. Exemplo:: + + config AUDIT + bool "Auditing support" + depends on NET + help + Enable auditing infrastructure that can be used with another + kernel subsystem, such as SELinux (which requires this for + logging of avc messages output). Does not do system-call + auditing without CONFIG_AUDITSYSCALL. + +Recursos seriamente perigosos (como suporte de gravação para certos sistemas +de arquivos) devem anunciar isso de forma proeminente na string do prompt:: + + config ADFS_FS_RW + bool "ADFS write support (DANGEROUS)" + depends on ADFS_FS + ... + +Para documentação completa sobre os arquivos de configuração, consulte o +arquivo Documentation/kbuild/kconfig-language.rst. + + +11) Estruturas de dados +----------------------- + +Estruturas de dados que tenham visibilidade fora do ambiente monothread em que +são criadas e destruídas devem ter contadores de referência. No kernel, coleta +de lixo não existe (e fora do kernel, a coleta de lixo é lenta e +ineficiente), o que significa que você absolutamente **precisa** contar todas +as referências de uso. + +Contagem de referência significa que você pode evitar bloqueios e permite que +múltiplos usuários tenham acesso à estrutura de dados em paralelo - sem se +preocupar com a estrutura desaparecendo debaixo deles do nada apenas porque +eles dormiram ou fizeram outra coisa por um tempo. + +Observe que bloqueio **não** substitui contagem de referência. O bloqueio é +usado para manter estruturas de dados coerentes, enquanto a contagem de +referência é uma técnica de gerenciamento de memória. Normalmente, ambos são +necessários, e não devem ser confundidos entre si. + +Muitas estruturas de dados podem, de fato, ter dois níveis de contagem de +referência, quando existem usuários de diferentes ``classes``. A contagem da +subclasse conta o número de usuários da subclasse e decrementa a contagem +global apenas uma vez quando a contagem da subclasse chega a zero. + +Exemplos desse tipo de ``multi-level-reference-counting`` podem ser encontrados +em gerenciamento de memória (``struct mm_struct``: mm_users e mm_count) e em +código de sistema de arquivos (``struct super_block``: s_count e s_active). + +Lembre-se: se outra thread puder encontrar sua estrutura de dados, e você não +tiver contagem de referência nela, quase certamente há um bug. + + +12) Macros, enums e RTL +----------------------- + +Nomes de macros que definem constantes e rótulos em enums são maiúsculos. + +.. code-block:: c + + #define CONSTANT 0x12345 + +Enums são preferidos quando várias constantes relacionadas são definidas. + +Nomes de macro em maiúsculas são apreciados, mas macros que se parecem com +funções podem ser nomeadas em minúsculas. + +Em geral, funções inline são preferíveis a macros que se parecem com funções. + +Macros com múltiplas instruções devem ser envoltas em um bloco do-while: + +.. code-block:: c + + #define macrofun(a, b, c) \ + do { \ + if (a == 5) \ + do_this(b, c); \ + } while (0) + +Macros do tipo função com parâmetros não usados devem ser substituídas por +funções estáticas inline para evitar o problema de variáveis não usadas: + +.. code-block:: c + + static inline void fun(struct foo *foo) + { + } + +Devido a práticas históricas, muitos arquivos ainda empregam a abordagem +"cast para (void)" para avaliar parâmetros. No entanto, esse método não é +aconselhável. +Funções inline resolvem o problema de "expressão com efeitos colaterais +avaliada mais de uma vez", contornam problemas de variáveis não usadas e, por +algum motivo, geralmente são mais bem documentadas do que macros. + +.. code-block:: c + + /* + * Evite fazer isto sempre que possível e prefira funções estáticas + * inline + */ + #define macrofun(foo) do { (void) (foo); } while (0) + +Coisas a evitar ao usar macros: + +1) macros que afetam o fluxo de controle: + +.. code-block:: c + + #define FOO(x) \ + do { \ + if (blah(x) < 0) \ + return -EBUGGERED; \ + } while (0) + +é uma ideia **muito** ruim. Ela parece uma chamada de função, mas sai da +função ``calling``; não quebre os parsers internos de quem lerá o código. + +2) macros que dependem de ter uma variável local com um nome mágico: + +.. code-block:: c + + #define FOO(val) bar(index, val) + +pode parecer uma boa coisa, mas é confuso pra caramba para quem lê o código e +é propenso a quebrar com mudanças aparentemente inocentes. + +3) macros com argumentos usados como l-values: FOO(x) = y; vai te morder se +alguém, por exemplo, transformar FOO em uma função inline. + +4) esquecer da precedência: macros que definem constantes usando expressões +devem colocar a expressão entre parênteses. Cuidado com problemas semelhantes +com macros que usam parâmetros. + +.. code-block:: c + + #define CONSTANT 0x4000 + #define CONSTEXP (CONSTANT | 3) + +5) colisões de namespace ao definir variáveis locais em macros que se +parecem com funções: + +.. code-block:: c + + #define FOO(x) \ + ({ \ + typeof(x) ret; \ + ret = calc_ret(x); \ + (ret); \ + }) + +``ret`` é um nome comum para uma variável local - ``__foo_ret`` tem menos +chance de colidir com uma variável existente. + +O manual do cpp trata de macros de forma exaustiva. O manual interno do gcc +também cobre o RTL, que é usado frequentemente com linguagem de montagem no +kernel. + + +13) Imprimindo mensagens do kernel +---------------------------------- + +Desenvolvedores do kernel gostam de ser vistos como letrados. Preste atenção à +ortografia das mensagens do kernel para causar uma boa impressão. Não use +contrações incorretas como ``dont``; use ``do not`` ou ``don't`` em vez +disso. Faça as mensagens concisas, claras e inequívocas. + +Mensagens do kernel não precisam terminar com ponto. + +Imprimir números entre parênteses (%d) não agrega valor e deve ser evitado. + +Há vários macros de diagnóstico do modelo de driver em <linux/dev_printk.h> +que você deve usar para garantir que as mensagens sejam correspondidas ao +dispositivo e driver corretos e sejam marcadas com o nível certo: ``dev_err()``, +``dev_warn()``, ``dev_info()`` e assim por diante. Para mensagens que não +estão associadas a um device específico, <linux/printk.h> define +``pr_notice()``, ``pr_info()``, ``pr_warn()``, ``pr_err()`` etc. Quando os +drivers funcionam corretamente, eles ficam silenciosos, então prefira usar +``dev_dbg``/``pr_debug`` a menos que algo esteja errado. + +Encontrar boas mensagens de depuração pode ser um desafio; e, uma vez que +você tenha essas mensagens, elas podem ajudar bastante para solução de +problemas remota. No entanto, a impressão de mensagens de depuração é tratada +diferentemente da impressão de outras mensagens não de depuração. Enquanto as +outras funções ``pr_XXX()`` imprimem incondicionalmente, ``pr_debug()`` não; +ela é compilada fora por padrão, a menos que ``DEBUG`` seja definido ou +``CONFIG_DYNAMIC_DEBUG`` esteja configurado. Isso também vale para +``dev_dbg()``, e uma convenção relacionada usa ``VERBOSE_DEBUG`` para adicionar +mensagens ``dev_vdbg()`` às já habilitadas por ``DEBUG``. + +Muitos subsistemas têm opções de depuração do Kconfig para ativar ``-DDEBUG`` +no Makefile correspondente; em outros casos, arquivos específicos fazem +``#define DEBUG``. E quando uma mensagem de depuração deve ser impressa +incondicionalmente, por exemplo, se ela já estiver dentro de uma seção +``#ifdef`` relacionada à depuração, pode-se usar ``printk(KERN_DEBUG ...)``. + + +14) Alocando memória +-------------------- + +O kernel fornece os seguintes alocadores de memória de uso geral: +``kmalloc()``, ``kzalloc()``, ``kmalloc_objs()``, ``kzalloc_objs()``, +``vmalloc()`` e ``vzalloc()``. Consulte a documentação da API para obter mais +informações sobre eles. :ref:`Documentation/core-api/memory-allocation.rst +<memory_allocation>` + +A forma preferida de passar o tamanho de uma estrutura é a seguinte: + +.. code-block:: c + + p = kmalloc_obj(*p, ...); + +A forma alternativa em que o nome da estrutura é escrito explicitamente piora a +legibilidade e cria oportunidade para um bug quando o tipo da variável ponteiro +é alterado, mas o ``sizeof`` correspondente passado para um alocador de memória +não é. + +Casting do valor de retorno, que é um ponteiro ``void``, é redundante. A +conversão de ponteiro ``void`` para qualquer outro tipo de ponteiro é garantida +pela linguagem de programação C. + +A forma preferida para alocar um array é a seguinte: + +.. code-block:: c + + p = kmalloc_objs(*p, n, ...); + +A forma preferida para alocar um array zerado é a seguinte: + +.. code-block:: c + + p = kzalloc_objs(*p, n, ...); + +As duas formas verificam estouro no tamanho de alocação ``n * sizeof(...)`` e +retornam ``NULL`` se isso ocorrer. + +Essas funções genéricas de alocação emitem um dump de pilha em caso de falha +quando usadas sem ``__GFP_NOWARN``, então não há utilidade em emitir uma +mensagem de falha adicional quando ``NULL`` é retornado. + +15) A doença do inline +---------------------- + +Parece haver uma percepção errônea comum de que o gcc tem uma opção mágica de +aceleração chamada ``inline``. Embora o uso de ``inline`` possa ser apropriado +(por exemplo, como uma forma de substituir macros; veja o Capítulo 12), muitas +vezes não é. O uso abundante da palavra-chave ``inline`` leva a um kernel +muito maior, o que, por sua vez, torna o sistema mais lento como um todo, por +causa de uma maior ocupação de i-cache para a CPU e simplesmente porque há menos +memória disponível para o ``pagecache``. Pense nisso: uma falha no pagecache +causa um seek no disco, que facilmente leva 5 milissegundos. Há MUITOS ciclos +de CPU que podem entrar nesses 5 milissegundos. + +Uma regra prática razoável é não colocar ``inline`` em funções com mais de 3 +linhas de código. Uma exceção a essa regra são os casos em que um parâmetro é +conhecido como uma constante em tempo de compilação, e como resultado dessa +constância você *sabe* que o compilador será capaz de otimizar grande parte da +sua função em tempo de compilação. Para um bom exemplo desse caso posterior, +veja a função inline ``kmalloc()``. + +Muitas pessoas argumentam que adicionar ``inline`` a funções ``static`` usadas +apenas uma vez é sempre uma vantagem, porque não há custo de espaço. Embora +isso seja tecnicamente correto, o gcc é capaz de fazer esse inline +automaticamente sem ajuda, e a questão de manutenção de remover o ``inline`` +quando um segundo usuário aparece supera o valor potencial da dica que diz ao +gcc para fazer algo que ele faria de qualquer forma. + + +16) Valores e nomes de retorno de função +---------------------------------------- + +Funções podem retornar valores de vários tipos, e um dos mais comuns é um valor +que indica se a função teve sucesso ou falhou. Esse valor pode ser representado +como um inteiro de código de erro (-Exxx = falha, 0 = sucesso) ou como um +booleano ``succeeded`` (0 = falha, diferente de zero = sucesso). + +Misturar esses dois tipos de representação é uma fonte fértil de bugs difíceis +de encontrar. Se a linguagem C incluísse uma distinção forte entre inteiros e +booleanos, o compilador encontraria esses erros para nós... mas não inclui. Para +ajudar a evitar esses bugs, siga sempre esta convenção:: + + Se o nome de uma função for uma ação ou um comando imperativo, + a função deve retornar um inteiro de código de erro. Se o nome + for um predicado, a função deve retornar um booleano de "sucesso". + +Por exemplo, ``add work`` é um comando, e a função ``add_work()`` retorna 0 +para sucesso ou -EBUSY para falha. Da mesma forma, ``PCI device present`` é um +predicado, e a função ``pci_dev_present()`` retorna 1 se encontrar um device +correspondente ou 0 se não encontrar. + +Todas as funções ``EXPORT`` devem respeitar esta convenção, e assim também +devem todas as funções públicas. Funções privadas (``static``) não precisam, +mas é recomendável que o façam. + +Funções cujo valor de retorno é o resultado real de um cálculo, em vez de uma +indicação de se o cálculo teve sucesso, não estão sujeitas a essa regra. +Normalmente, elas indicam falha retornando algum resultado fora do intervalo. +Exemplos típicos seriam funções que retornam ponteiros; elas usam ``NULL`` ou o +mecanismo ``ERR_PTR`` para informar falha. + + +17) Usando bool +--------------- + +O tipo ``bool`` do kernel Linux é um alias do tipo C99 ``_Bool``. Valores +``bool`` só podem avaliar para 0 ou 1, e conversão implícita ou explícita para +``bool`` converte automaticamente o valor para verdadeiro ou falso. Ao usar +tipos ``bool``, a construção ``!!`` não é necessária, o que elimina uma classe +de bugs. + +Ao trabalhar com valores ``bool``, as definições ``true`` e ``false`` devem ser +usadas em vez de 1 e 0. + +Tipos de retorno de função ``bool`` e variáveis locais na pilha são sempre +válidos quando apropriados. O uso de ``bool`` é encorajado para melhorar a +legibilidade e muitas vezes é uma opção melhor do que ``int`` para armazenar +valores booleanos. + +Não use ``bool`` se o layout da linha de cache ou o tamanho do valor importar, +porque seu tamanho e alinhamento variam conforme a arquitetura compilada. +Estruturas otimizadas para alinhamento e tamanho não devem usar ``bool``. + +Se uma estrutura tiver muitos valores verdadeiro/falso, considere consolidá-los +em um ``bitfield`` com membros de 1 bit, ou usar um tipo de largura fixa +apropriado, como ``u8``. + +Da mesma forma, para argumentos de função, muitos valores verdadeiro/falso podem +ser consolidados em um único argumento de sinalizadores bit a bit, e +``flags`` muitas vezes pode ser uma alternativa mais legível se os pontos de +chamada tiverem constantes verdadeiras/falsas "nuas". + +Caso contrário, o uso limitado de ``bool`` em estruturas e argumentos pode +melhorar a legibilidade. + +18) Não reinventando as macros do kernel +---------------------------------------- + +Existem muitos arquivos de cabeçalho em ``include/linux/`` que contêm várias +macros que você deve usar em vez de escrever explicitamente alguma variante +delas. Por exemplo, se você precisa calcular o comprimento de um array, aproveite +a macro + +.. code-block:: c + + #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0])) + +que é definida em ``array_size.h``. + +Da mesma forma, se você precisar calcular o tamanho de um membro de alguma +estrutura, use + +.. code-block:: c + + #define sizeof_field(t, f) (sizeof(((t*)0)->f)) + +que é definida em ``stddef.h``. + +Também existem macros ``min()`` e ``max()`` definidas em ``minmax.h`` que fazem +verificação estrita de tipos se você precisar delas. Sinta-se à vontade para +explorar os arquivos de cabeçalho para ver o que já está definido e não deve +ser reproduzido no seu código. + + +19) Modelines do editor e outros restos +--------------------------------------- + +Alguns editores podem interpretar informações de configuração embutidas em +arquivos de origem, indicadas por marcadores especiais. Por exemplo, o emacs +interpreta linhas marcadas assim: + +.. code-block:: c + + -*- mode: c -*- + +Ou assim: + +.. code-block:: c + + /* + Local Variables: + compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c" + End: + */ + +O Vim interpreta marcadores que parecem com isto: + +.. code-block:: c + + /* vim:set sw=8 noet */ + +Não inclua nenhum desses em arquivos de origem. As pessoas têm suas próprias +configurações pessoais de editor, e seus arquivos de origem não devem +substituí-las. Isso inclui marcadores para indentação e configuração de modo. +As pessoas podem usar seu próprio modo personalizado, ou podem ter algum outro +método mágico para fazer a indentação funcionar corretamente. + + +20) Montagem inline +------------------- + +Em código específico de arquitetura, pode ser necessário usar montagem inline +para interagir com a funcionalidade da CPU ou da plataforma. Não hesite em +fazê-lo quando necessário. No entanto, não use montagem inline de forma +gratuita quando o C puder fazer o trabalho. Você pode e deve mexer em hardware +em C quando possível. + +Considere escrever funções auxiliares simples que encapsulem partes comuns de +montagem inline, em vez de escrevê-las repetidamente com pequenas variações. +Lembre-se de que a montagem inline pode usar parâmetros C. + +Funções grandes e não triviais de montagem devem ir para arquivos ``.S``, com +protótipos C correspondentes definidos em arquivos de cabeçalho C. Os +protótipos C para funções de montagem devem usar ``asmlinkage``. + +Você pode precisar marcar sua instrução ``asm`` como ``volatile`` para impedir +que o GCC a remova se o GCC não perceber efeitos colaterais. No entanto, você +nem sempre precisa fazer isso, e fazê-lo desnecessariamente pode limitar a +otimização. + +Ao escrever uma única instrução de montagem inline contendo várias instruções, +coloque cada instrução em uma linha separada em uma string separada e termine +cada string, exceto a última, com ``\n\t`` para indentar corretamente a +próxima instrução na saída de montagem: + +.. code-block:: c + + asm ("magic %reg1, #42\n\t" + "more_magic %reg2, %reg3" + : /* outputs */ : /* inputs */ : /* clobbers */); + + +21) Compilação condicional +-------------------------- + +Sempre que possível, não use condicionais do pré-processador (#if, #ifdef) em +arquivos ``.c``; isso torna o código mais difícil de ler e a lógica mais difícil +de seguir. Em vez disso, use esses condicionais em um arquivo de cabeçalho que +defina funções para uso nesses arquivos ``.c``, fornecendo versões de stub sem +efeito no caso ``#else``, e então chame essas funções incondicionalmente nos +arquivos ``.c``. O compilador evitará gerar qualquer código para as chamadas de +stub, produzindo resultados idênticos, mas a lógica permanecerá fácil de +seguir. + +Prefira compilar funções inteiras fora do código, em vez de partes de funções +ou partes de expressões. Em vez de colocar um ``ifdef`` em uma expressão, +extraia parte ou toda a expressão para uma função auxiliar separada e aplique a +condicional a essa função. + +Se você tiver uma função ou variável que pode potencialmente ficar sem uso em +uma configuração específica, e o compilador avisaria sobre a definição ficar sem +uso, marque a definição como ``__maybe_unused`` em vez de envolvê-la em uma +condicional do pré-processador. (No entanto, se uma função ou variável +*sempre* ficar sem uso, elimine-a.) + +Dentro do código, quando possível, use a macro ``IS_ENABLED`` para converter um +símbolo Kconfig em uma expressão booleana C e usá-la em uma condicional C +normal: + +.. code-block:: c + + if (IS_ENABLED(CONFIG_SOMETHING)) { + ... + } + +O compilador reduzirá a condicional a um valor constante e incluirá ou +excluirá o bloco de código assim como com um ``#ifdef``, então isso não +adicionará nenhum custo de runtime. No entanto, essa abordagem ainda permite +que o compilador C veja o código dentro do bloco e verifique sua correção +(sintaxe, tipos, referências de símbolo etc.). Portanto, você ainda precisa usar +um ``#ifdef`` se o código dentro do bloco referenciar símbolos que não existirão +se a condição não for atendida. + +No final de qualquer bloco ``#if`` ou ``#ifdef`` não trivial (mais de algumas +linhas), coloque um comentário após o ``#endif`` na mesma linha, indicando a +expressão condicional usada. Por exemplo: + +.. code-block:: c + + #ifdef CONFIG_SOMETHING + ... + #endif /* CONFIG_SOMETHING */ + + +22) Não derrube o kernel +------------------------ + +Em geral, a decisão de derrubar o kernel pertence ao usuário, e não ao +desenvolvedor do kernel. + +Evite ``panic()`` +***************** + +``panic()`` deve ser usado com cuidado e principalmente apenas durante a inicialização +do sistema. ``panic()`` é, por exemplo, aceitável ao ficar sem memória durante +a inicialização e não ser possível continuar. + +Use ``WARN()`` em vez de ``BUG()`` +********************************** + +Não adicione novo código que use nenhuma das variantes de ``BUG()``, como +``BUG()``, ``BUG_ON()`` ou ``VM_BUG_ON()``. Em vez disso, use uma variante de +``WARN*()``, preferencialmente ``WARN_ON_ONCE()``, e possivelmente com código de +recuperação. O código de recuperação não é obrigatório se não houver uma +maneira razoável de pelo menos recuperar parcialmente. + +"Sou preguiçoso para tratar erros" não é uma desculpa para usar ``BUG()``. +Corrupções internas graves sem como continuar ainda podem usar ``BUG()``, mas +precisam de uma boa justificativa. + +Use ``WARN_ON_ONCE()`` em vez de ``WARN()`` ou ``WARN_ON()`` +************************************************************ + +``WARN_ON_ONCE()`` geralmente é preferido em relação a ``WARN()`` ou +``WARN_ON()``, porque é comum que uma dada condição de aviso, se ocorrer, +ocorra várias vezes. Isso pode encher e sobrescrever o log do kernel e até +diminuir o sistema o suficiente para que o registro excessivo vire um problema +adicional. + +Não emita ``WARN`` levianamente +******************************* + +``WARN*()`` foi concebido para situações inesperadas, em que "isso nunca devia +acontecer". Macros ``WARN*()`` não devem ser usadas para nada que se espere que +aconteça durante a operação normal. Esses não são asserts de pré- ou pós- +condição, por exemplo. Novamente: ``WARN*()`` não deve ser usado para uma +condição que se espera que seja acionada facilmente, por exemplo, por ações do +espaço do usuário. ``pr_warn_once()`` é uma alternativa possível, se você +precisar notificar o usuário sobre um problema. + +Não se preocupe com usuários de ``panic_on_warn`` +************************************************* + +Mais algumas palavras sobre ``panic_on_warn``: lembre-se de que +``panic_on_warn`` é uma opção disponível do kernel, e muitos usuários a +habilitam. É por isso que existe um texto "Não emita WARN levianamente" acima. +Entretanto, a existência de usuários de ``panic_on_warn`` não é uma razão válida +para evitar o uso judicioso de ``WARN*()``. Isso ocorre porque quem habilita +``panic_on_warn`` explicitamente pediu ao kernel para travar se um ``WARN*()`` +for disparado, e esses usuários devem estar preparados para lidar com as +consequências de um sistema que tem uma chance um pouco maior de travar. + +Use ``BUILD_BUG_ON()`` para assertivas em tempo de compilação +************************************************************* + +O uso de ``BUILD_BUG_ON()`` é aceitável e encorajado, porque é uma assertiva +em tempo de compilação que não tem efeito em tempo de execução. + +Apêndice I) Referências +----------------------- + +The C Programming Language, Second Edition +by Brian W. Kernighan and Dennis M. Ritchie. +Prentice Hall, Inc., 1988. +ISBN 0-13-110362-8 (paperback), 0-13-110370-9 (hardback). + +The Practice of Programming +by Brian W. Kernighan and Rob Pike. +Addison-Wesley, Inc., 1999. +ISBN 0-201-61586-X. + +Manuais GNU - onde em conformidade com K&R e este texto - para cpp, gcc, +gcc internals e indent, todos disponíveis em https://www.gnu.org/manual/ + +WG14 é o grupo de trabalho de padronização internacional para a linguagem de +programação C, URL: http://www.open-std.org/JTC1/SC22/WG14/ + +Kernel CodingStyle, by greg@kroah.com at OLS 2002: +http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/ diff --git a/Documentation/translations/pt_BR/process/cve.rst b/Documentation/translations/pt_BR/process/cve.rst index 18f4b11be369..83977eda34c4 100644 --- a/Documentation/translations/pt_BR/process/cve.rst +++ b/Documentation/translations/pt_BR/process/cve.rst @@ -18,7 +18,7 @@ essas atribuições. A equipe de desenvolvedores do kernel Linux tem a capacidade de atribuir CVEs para possíveis problemas de segurança do kernel Linux. Essa atribuição é independente do processo normal de relato de bugs de segurança do kernel -Linux, descrito em :ref:`securitybugs`. +Linux, descrito em :ref:`pt_BR_securitybugs`. Uma lista de todos os CVEs atribuídos ao kernel Linux pode ser encontrada nos arquivos da lista de discussão linux-cve, como visto em @@ -51,7 +51,7 @@ ele é SOMENTE para atribuição de CVEs a correções que já estejam em árvor kernel lançadas. Se você acredita ter encontrado um problema de segurança ainda não corrigido, por favor siga o processo normal de relato de bugs de segurança do kernel -Linux, descrito em :ref:`securitybugs`. +Linux, descrito em :ref:`pt_BR_securitybugs`. Nenhum CVE será atribuído automaticamente para problemas de segurança ainda não corrigidos no kernel Linux; a atribuição só acontecerá automaticamente diff --git a/Documentation/translations/pt_BR/process/debugging/index.rst b/Documentation/translations/pt_BR/process/debugging/index.rst new file mode 100644 index 000000000000..b223fae34622 --- /dev/null +++ b/Documentation/translations/pt_BR/process/debugging/index.rst @@ -0,0 +1,73 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======================================================= +Dicas de depuração para desenvolvedores do Kernel Linux +======================================================= + +Guias gerais +------------ + +Todolist: + +* driver_development_debugging_guide +* gdb-kernel-debugging +* kgdb +* userspace_debugging_guide + +Guias específicos de subsistemas +-------------------------------- + +Todolist: + +* media_specific_debugging_guide + +Dicas gerais de depuração +------------------------- + +Dependendo do problema, um conjunto diferente de ferramentas está disponível +para rastrear o problema ou até mesmo para perceber se há algum problema em +primeiro lugar. + +Como primeiro passo, você precisa descobrir que tipo de problema você deseja +depurar. Dependendo da resposta, sua metodologia e escolha de ferramentas podem +variar. + +Preciso depurar com acesso limitado? +------------------------------------ + +Você possui acesso limitado à máquina ou não consegue parar a execução em +andamento? + +Nesse caso, sua capacidade de depuração depende do suporte de depuração +embutido no kernel fornecido pela distribuição. +O :doc:`/process/debugging/userspace_debugging_guide` fornece uma breve visão +geral sobre uma variedade de ferramentas de depuração possíveis nessa situação. +Você pode verificar a capacidade do seu kernel, na maioria dos casos, olhando o +arquivo de configuração dentro do diretório /boot. + +Eu tenho acesso root ao sistema? +-------------------------------- + +Você consegue facilmente substituir o módulo em questão ou instalar um novo +kernel? + +Nesse caso, sua gama de ferramentas disponíveis é muito maior. Você +pode encontrar as ferramentas +no :doc:`/process/debugging/driver_development_debugging_guide`. + +A temporização é um fator? +-------------------------- + +É importante entender se o problema que você deseja depurar se manifesta +de forma consistente (ou seja, para um determinado conjunto de entradas, você +sempre obtém a mesma saída incorreta) ou de forma inconsistente. Se ele se +manifestar de forma inconsistente, algum fator de temporização pode estar em +jogo. Se a inserção de atrasos no código alterar o comportamento, é bastante +provável que a temporização seja um fator determinante. + +Quando a temporização altera o resultado da execução do código, o uso de um +simples printk() para fins de depuração pode não funcionar; uma alternativa +semelhante é usar trace_printk(), que registra as mensagens de depuração no +arquivo de rastreamento, em vez de no log do kernel. + +**Copyright** ©2024 : Collabora diff --git a/Documentation/translations/pt_BR/process/development-process.rst b/Documentation/translations/pt_BR/process/development-process.rst index d303ab92b2d3..e1441cec8b1a 100644 --- a/Documentation/translations/pt_BR/process/development-process.rst +++ b/Documentation/translations/pt_BR/process/development-process.rst @@ -1,5 +1,7 @@ .. SPDX-License-Identifier: GPL-2.0 +.. _pt_BR_development_process_main: + Guia para o Processo de Desenvolvimento do Kernel ================================================= diff --git a/Documentation/translations/pt_BR/process/embargoed-hardware-issues.rst b/Documentation/translations/pt_BR/process/embargoed-hardware-issues.rst new file mode 100644 index 000000000000..ae1fda0880cc --- /dev/null +++ b/Documentation/translations/pt_BR/process/embargoed-hardware-issues.rst @@ -0,0 +1,362 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Problemas de hardware sob embargo +================================= + +Escopo +------ + +Problemas de hardware que resultam em problemas de segurança formam uma categoria +de bugs de segurança diferente dos bugs de software puros que afetam apenas o +kernel do Linux. + +Problemas de hardware como Meltdown, Spectre, L1TF, etc., devem ser tratados +de maneira diferente porque geralmente afetam todos os Sistemas Operacionais ("OS") +e, portanto, exigem coordenação entre diferentes fornecedores de SO, distribuições, +fabricantes de silício, integradores de hardware e outras partes. Para alguns +dos problemas, as mitigações de software podem depender de atualizações de +microcódigo ou firmware, o que requer ainda mais coordenação. + +.. _pt_BR_Contact: + +Contato +------- + +A equipe de segurança de hardware do kernel Linux é separada da equipe regular +de segurança do kernel Linux. + +A equipe lida apenas com o desenvolvimento de correções para problemas de +segurança de hardware sob embargo. Relatos de bugs de segurança de software puro +no kernel Linux não são tratados por esta equipe, e o autor do relato será +orientado a contatar a equipe regular de segurança do kernel Linux +(:ref:`Documentation/admin-guide/ <securitybugs>`) em vez disso. + +A equipe pode ser contatada por e-mail em <hardware-security@kernel.org>. Esta +é uma lista privada de oficiais de segurança que ajudarão você a coordenar uma +correção de acordo com o nosso processo documentado. + +A lista é criptografada e o e-mail para a lista pode ser enviado criptografado +por PGP ou S/MIME, e deve ser assinado com a chave PGP ou certificado S/MIME do +autor do relato. A chave PGP e o certificado S/MIME da equipe estão disponíveis +nas seguintes URLs: + + - PGP: https://www.kernel.org/static/files/hardware-security.asc + - S/MIME: https://www.kernel.org/static/files/hardware-security.crt + +Embora os problemas de segurança de hardware sejam frequentemente tratados pelo +fabricante de silício afetado, nós acolhemos o contato de pesquisadores ou +indivíduos que tenham identificado uma falha potencial de hardware. + +Oficiais de segurança de hardware +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A equipe atual de oficiais de segurança de hardware: + + - Linus Torvalds (Fellow da Linux Foundation) + - Greg Kroah-Hartman (Fellow da Linux Foundation) + - Thomas Gleixner (Fellow da Linux Foundation) + +Operação das listas de e-mail +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +As listas de e-mail criptografadas que são usadas em nosso processo são +hospedadas na infraestrutura de TI da Linux Foundation. Ao fornecer este +serviço, os membros da equipe de operações de TI da Linux Foundation têm, +tecnicamente, a capacidade de acessar as informações sob embargo, mas são +obrigados à confidencialidade por seu contrato de trabalho. O pessoal de TI +da Linux Foundation também é responsável por operar e gerenciar o restante da +infraestrutura do kernel.org. + +O atual diretor de infraestrutura de projetos de TI da Linux Foundation é +Konstantin Ryabitsev. + + +Acordos de não divulgação +------------------------- + +A equipe de segurança de hardware do kernel Linux não é um órgão formal e, +portanto, é incapaz de celebrar quaisquer acordos de não divulgação. A +comunidade do kernel está ciente da natureza sensível de tais problemas e +oferece um Memorando de Entendimento em vez disso. + + +Memorando de Entendimento +------------------------- + +A comunidade do kernel Linux compreende profundamente a necessidade de manter +os problemas de segurança de hardware sob embargo para a coordenação entre +diferentes fornecedores de SO, distribuidores, fabricantes de silício e outras +partes. + +A comunidade do kernel Linux lidou com sucesso com problemas de segurança de +hardware no passado e possui os mecanismos necessários para permitir o +desenvolvimento compatível com a comunidade sob restrições de embargo. + +A comunidade do kernel Linux possui uma equipe dedicada de segurança de hardware +para o contato inicial, que supervisiona o processo de tratamento de tais +problemas sob as regras de embargo. + +A equipe de segurança de hardware identifica os desenvolvedores (especialistas no +domínio) que formarão a equipe de resposta inicial para um problema específico. +A equipe de resposta inicial pode trazer outros desenvolvedores (especialistas no +domínio) para resolver o problema da melhor maneira técnica. + +Todos os desenvolvedores envolvidos comprometem-se a aderir às regras de embargo +e a manter as informações recebidas em sigilo. A violação do compromisso levará à +exclusão imediata do problema atual e à remoção de todas as listas de e-mail +relacionadas. Além disso, a equipe de segurança de hardware também excluirá o +infrator de futuros problemas. O impacto dessa consequência é um impedimento +altamente eficaz em nossa comunidade. Caso ocorra uma violação, a equipe de +segurança de hardware informará as partes envolvidas imediatamente. Se você ou +qualquer outra pessoa tomar conhecimento de uma potencial violação, por favor, +relate-a imediatamente aos oficiais de segurança de hardware. + + +Processo +^^^^^^^^ + +Devido à natureza globalmente distribuída do desenvolvimento do kernel Linux, +reuniões presenciais são quase impossíveis para lidar com problemas de +segurança de hardware. Conferências telefônicas são difíceis de coordenar devido +a fusos horários e outros fatores, devendo ser usadas apenas quando estritamente +necessário. O e-mail criptografado tem se mostrado o método de comunicação mais +eficiente e seguro para esses tipos de problema. + +Início da divulgação +""""""""""""""""""""" + +A divulgação começa enviando um e-mail para a equipe de segurança de hardware +do kernel Linux, conforme a seção Contato acima. Este contato inicial deve +conter uma descrição do problema e uma lista de qualquer silício afetado +conhecido. Se a sua organização constrói ou distribui o hardware afetado, +incentivamos você a considerar também quais outros hardwares podem ser +afetados. A parte que faz a divulgação é responsável por contatar os +fabricantes de silício afetados em tempo hábil. + +A equipe de segurança de hardware fornecerá uma lista de e-mail criptografada +específica para o incidente, que será usada para a discussão inicial com o +relator, divulgação posterior e coordenação de correções. + +A equipe de segurança de hardware fornecerá à parte divulgadora uma lista de +desenvolvedores (especialistas no domínio) que devem ser informados inicialmente +sobre o problema após confirmar com os desenvolvedores que eles aderirão a +este Memorando de Entendimento e ao processo documentado. Esses desenvolvedores +formam a equipe de resposta inicial e serão responsáveis por lidar com o +problema após o contato inicial. A equipe de segurança de hardware apoia a +equipe de resposta, mas não está necessariamente envolvida no processo de +desenvolvimento de mitigações. + +Embora desenvolvedores individuais possam estar cobertos por um acordo de não +divulgação por meio de seu empregador, eles não podem celebrar acordos +individuais de não divulgação em seu papel como desenvolvedores do kernel +Linux. No entanto, eles concordarão em aderir a este processo documentado e ao +Memorando de Entendimento. + +A parte divulgadora deve fornecer uma lista de contatos para todas as outras +entidades que já foram, ou devem ser, informadas sobre o problema. Isso serve +a vários propósitos: + + - A lista de entidades informadas permite a comunicação em toda a + indústria, por exemplo, outros fornecedores de SO, fornecedores de HW, etc. + + - As entidades informadas podem ser contatadas para indicar especialistas + que devem participar do desenvolvimento da mitigação. + + - Se um especialista necessário para lidar com um problema for funcionário + de uma entidade listada ou membro de uma entidade listada, as equipes de + resposta podem solicitar a inclusão desse especialista por parte daquela + entidade. Isso garante que o especialista também faça parte da equipe de + resposta da entidade. + +Divulgação +"""""""""" + +A parte divulgadora fornece informações detalhadas à equipe de resposta inicial +por meio da lista de e-mail criptografada específica. + +A partir de nossa experiência, a documentação técnica desses problemas costuma +ser um ponto de partida suficiente, e esclarecimentos técnicos adicionais são +melhor feitos por e-mail. + +Desenvolvimento de mitigações +"""""""""""""""""""""""""""""" + +A equipe de resposta inicial configura uma lista de e-mail criptografada ou +reaproveita uma já existente, se apropriado. + +O uso de uma lista de e-mail é próximo ao processo normal de desenvolvimento +do Linux e tem sido usado com sucesso para desenvolver mitigações para vários +problemas de segurança de hardware no passado. + +A lista de e-mail opera da mesma forma que o desenvolvimento normal do Linux. +Os patches são publicados, discutidos, revisados e, se aprovados, aplicados a +um repositório git não público que é acessível apenas aos desenvolvedores +participantes por meio de uma conexão segura. O repositório contém o ramo +(branch) principal de desenvolvimento contra o kernel mainline e ramos de +retroporte (backport) para versões estáveis do kernel conforme necessário. + +A equipe de resposta inicial identificará outros especialistas da comunidade +de desenvolvedores do kernel Linux conforme necessário. Qualquer parte +envolvida pode sugerir a inclusão de outros especialistas, cada um dos quais +estará sujeito aos mesmos requisitos descritos acima. + +A inclusão de especialistas pode ocorrer a qualquer momento no processo de +desenvolvimento e precisa ser tratada em tempo hábil. + +Se um especialista for funcionário ou membro de uma entidade na lista de +divulgação fornecida pela parte divulgadora, a participação será solicitada +à entidade relevante. + +Caso contrário, a parte divulgadora será informada sobre a participação +dos especialistas. Os especialistas são cobertos pelo Memorando de Entendimento +e a parte divulgadora é solicitada a reconhecer a participação deles. No caso +de a parte divulgadora ter um motivo convincente para se opor, qualquer +objeção deve ser levantada no prazo de cinco dias úteis e resolvida com a +equipe do incidente imediatamente. Se a parte divulgadora não reagir dentro +de cinco dias úteis, isso é considerado como reconhecimento tácito. + +Após a equipe do incidente reconhecer ou resolver uma objeção, o especialista +é informado e integrado ao processo de desenvolvimento. + +Os participantes da lista não podem se comunicar sobre o problema fora da +lista de e-mail privada. Os participantes da lista não podem usar nenhum +recurso compartilhado (por exemplo, fazendas de compilação do empregador, +sistemas de IC, etc.) ao trabalhar em patches. + +Acesso antecipado +""""""""""""""""" + +Os patches discutidos e desenvolvidos na lista não podem ser distribuídos a +nenhum indivíduo que não seja membro da equipe de resposta, nem a nenhuma outra +organização. + +Para permitir que os fornecedores de silício afetados trabalhem com suas equipes +internas e parceiros da indústria em testes, validação e logística, a seguinte +exceção é fornecida: + + Representantes designados dos fornecedores de silício afetados têm permissão + para repassar os patches a qualquer momento para a equipe de resposta do + fornecedor de silício. O representante deve notificar a equipe de resposta + do kernel sobre o repasse. O fornecedor de silício afetado deve possuir e + manter seu próprio processo de segurança documentado para quaisquer patches + compartilhados com sua equipe de resposta que seja consistente com esta + política. + + A equipe de resposta do fornecedor de silício pode distribuir esses patches + aos seus parceiros da indústria e às suas equipes internas sob o processo + de segurança documentado do fornecedor de silício. O feedback dos parceiros + da indústria retorna ao fornecedor de silício e é comunicado por ele à + equipe de resposta do kernel. + + O repasse para a equipe de resposta do fornecedor de silício remove + qualquer responsabilidade civil ou legal da equipe de resposta do kernel + em relação à divulgação prematura que ocorra devido ao envolvimento das + equipes internas ou parceiros da indústria do fornecedor de silício. O + fornecedor de silício garante esta liberação de responsabilidade ao + concordar com este processo. + +Lançamento coordenado +""""""""""""""""""""" + +As partes envolvidas negociarão a data e a hora em que o embargo termina. Nesse +ponto, as mitigações preparadas são publicadas nas árvores de kernel relevantes. +Não há processo de pré-notificação: as mitigações são publicadas publicamente e +disponibilizadas para todos ao mesmo tempo. + +Embora entendamos que problemas de segurança de hardware exijam tempo de embargo +coordenado, o tempo de embargo deve ser restrito ao mínimo necessário para que +todas as partes envolvidas desenvolvam, testem e preparem suas mitigações. +Estender o tempo de embargo artificialmente para cumprir datas de palestras em +conferências ou outros motivos não técnicos cria mais trabalho e ônus para os +desenvolvedores e equipes de resposta envolvidos, pois os patches precisam ser +mantidos atualizados para acompanhar o desenvolvimento contínuo do kernel +upstream, o que pode criar alterações conflitantes. + +Atribuição de CVE +"""""""""""""""""" + +Nem a equipe de segurança de hardware nem a equipe de resposta inicial atribuem +CVEs, nem os CVEs são necessários para o processo de desenvolvimento. Se os CVEs +forem fornecidos pela parte divulgadora, eles poderão ser usados para fins de +documentação. + +Embaixadores do processo +------------------------ + +Para obter assistência com este processo, estabelecemos embaixadores em várias +organizações, que podem responder a perguntas sobre ou fornecer orientações +acerca do processo de relatórios e tratamento posterior. Os embaixadores não +estão envolvidos na divulgação de um problema específico, a menos que seja +solicitado por uma equipe de resposta ou por uma parte divulgada envolvida. +A lista atual de embaixadores: + + ============= ======================================================== + AMD Tom Lendacky <thomas.lendacky@amd.com> + Ampere Darren Hart <darren@os.amperecomputing.com> + ARM Catalin Marinas <catalin.marinas@arm.com> + IBM Power Madhavan Srinivasan <maddy@linux.ibm.com> + IBM Z Christian Borntraeger <borntraeger@de.ibm.com> + Intel Tony Luck <tony.luck@intel.com> + Qualcomm Trilok Soni <quic_tsoni@quicinc.com> + RISC-V Palmer Dabbelt <palmer@dabbelt.com> + Samsung Javier González <javier.gonz@samsung.com> + + Microsoft James Morris <jamorris@linux.microsoft.com> + Xen Andrew Cooper <andrew.cooper3@citrix.com> + + Canonical John Johansen <john.johansen@canonical.com> + Debian Ben Hutchings <ben@decadent.org.uk> + Oracle Konrad Rzeszutek Wilk <konrad.wilk@oracle.com> + Red Hat Josh Poimboeuf <jpoimboe@redhat.com> + SUSE Jiri Kosina <jkosina@suse.cz> + + Google Kees Cook <keescook@chromium.org> + + LLVM Nick Desaulniers <ndesaulniers@google.com> + ============= ======================================================== + +Se você quiser que sua organização seja adicionada à lista de embaixadores, +entre em contato com a equipe de segurança de hardware. O embaixador indicado +deve compreender e apoiar totalmente o nosso processo e, idealmente, estar bem +conectado na comunidade do kernel Linux. + +Listas de e-mail criptografadas +------------------------------- + +Usamos listas de e-mail criptografadas para comunicação. O princípio de +operação dessas listas é que o e-mail enviado para a lista é criptografado +com a chave PGP da lista ou com o certificado S/MIME da lista. O software +da lista de e-mail descriptografa o e-mail e o recriptografa individualmente +para cada assinante com a chave PGP ou certificado S/MIME do assinante. +Detalhes sobre o software da lista de e-mail e a configuração usada para +garantir a segurança das listas e a proteção dos dados podem ser encontrados +aqui: https://korg.wiki.kernel.org/userdoc/remail. + +Listas de chaves +^^^^^^^^^^^^^^^^ + +Para o contato inicial, consulte a seção :ref:`pt_BR_Contact` acima. Para listas de +e-mail específicas de incidentes, a chave e o certificado S/MIME são transmitidos +aos assinantes por e-mail enviado a partir da lista específica. + +Inscrição em listas específicas de incidentes +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A inscrição em listas específicas de incidentes é gerenciada pelas equipes de +resposta. As partes informadas que desejam participar da comunicação enviam +uma lista de potenciais especialistas para a equipe de resposta, para que esta +possa validar as solicitações de inscrição. + +Cada assinante precisa enviar uma solicitação de inscrição para a equipe de +resposta por e-mail. O e-mail deve estar assinado com a chave PGP ou o certificado +S/MIME do assinante. Se uma chave PGP for utilizada, ela deve estar disponível +em um servidor de chaves público e, idealmente, conectada à teia de confiança +(web of trust) PGP do kernel Linux. Veja também: +https://www.kernel.org/signature.html. + +A equipe de resposta verifica se a solicitação do assinante é válida e o +adiciona à lista. Após a inscrição, o assinante receberá e-mails da lista de +e-mail que são assinados com a chave PGP da lista ou com o certificado S/MIME +da lista. O cliente de e-mail do assinante pode extrair a chave PGP ou o +certificado S/MIME da assinatura para que o assinante possa enviar e-mails +criptografados para a lista.
\ No newline at end of file diff --git a/Documentation/translations/pt_BR/process/howto.rst b/Documentation/translations/pt_BR/process/howto.rst index bcedee7273fd..54ea7fad8d75 100644 --- a/Documentation/translations/pt_BR/process/howto.rst +++ b/Documentation/translations/pt_BR/process/howto.rst @@ -67,7 +67,8 @@ Questões Legais O código-fonte do kernel Linux é lançado sob a GPL. Por favor, veja o arquivo COPYING no diretório principal da árvore de fontes. As regras de licenciamento do kernel Linux e como usar os identificadores `SPDX <https://spdx.org/>`_ no -código-fonte estão descritas em :ref:`Documentation/process/license-rules.rst <kernel_licensing>`. +código-fonte estão descritas em +:ref:`Documentation/translations/pt_BR/process/license-rules.rst <pt_BR_kernel_licensing>`. Se você tiver mais perguntas sobre a licença, por favor, entre em contato com um advogado e não pergunte na lista de discussão do kernel Linux. As pessoas nas listas de discussão não são advogados e você não deve confiar em suas @@ -94,7 +95,7 @@ a lista linux-api@vger.kernel.org. Aqui está uma lista de arquivos que estão na árvore de fontes do kernel e que são de leitura obrigatória: - :ref:`Documentation/admin-guide/README.rst <readme>` + :ref:`Documentation/translations/pt_BR/admin-guide/README.rst <pt_BR_readme>` Este arquivo fornece um breve histórico sobre o kernel Linux e descreve o que é necessário fazer para configurar e compilar o kernel. Pessoas que são novas no kernel devem começar por aqui. @@ -104,14 +105,14 @@ que são de leitura obrigatória: software que são necessários para compilar e executar o kernel com sucesso. - :ref:`Documentation/process/coding-style.rst <codingstyle>` + :ref:`Documentation/translations/pt_BR/process/coding-style.rst <pt_BR_codingstyle>` Este documento descreve o estilo de codificação do kernel Linux e parte da fundamentação por trás dele. Espera-se que todo código novo siga as diretrizes deste documento. A maioria dos mantenedores apenas aceitará patches se essas regras forem seguidas, e muitas pessoas apenas revisarão o código se ele estiver no estilo adequado. - :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` + :ref:`Documentation/translations/pt_BR/process/submitting-patches.rst <pt_BR_submittingpatches>` Este arquivo descreve em detalhes explícitos como criar e enviar um patch com sucesso, incluindo (mas não limitado a): @@ -144,12 +145,12 @@ Outras excelentes descrições de como criar patches adequadamente são: do Linux e é muito importante para pessoas que estão migrando para o Linux vindas do desenvolvimento em outros Sistemas Operacionais. - :ref:`Documentation/process/security-bugs.rst <securitybugs>` + :ref:`Documentation/translations/pt_BR/process/security-bugs.rst <pt_BR_securitybugs>` Se você acredita ter encontrado um problema de segurança no kernel Linux, por favor, siga os passos descritos neste documento para ajudar a notificar os desenvolvedores do kernel e auxiliar na resolução do problema. - :ref:`Documentation/process/management-style.rst <managementstyle>` + :ref:`Documentation/translations/pt_BR/process/management-style.rst <pt_BR_managementstyle>` Este documento descreve como os mantenedores do kernel Linux operam e o ethos compartilhado por trás de suas metodologias. Esta é uma leitura importante para qualquer pessoa nova no desenvolvimento do kernel (ou @@ -162,12 +163,12 @@ Outras excelentes descrições de como criar patches adequadamente são: versões estáveis (stable) do kernel e o que fazer se você desejar que uma alteração seja incluída em um desses lançamentos. - :ref:`Documentation/process/kernel-docs.rst <kernel_docs>` + :ref:`Documentation/translations/pt_BR/process/kernel-docs.rst <pt_BR_kernel_docs>` Uma lista de documentação externa que pertence ao desenvolvimento do kernel. Por favor, consulte esta lista caso não encontre o que está procurando dentro da documentação interna do kernel. - :ref:`Documentation/process/applying-patches.rst <applying_patches>` + :ref:`Documentation/translations/pt_BR/process/applying-patches.rst <pt_BR_applying_patches>` Uma boa introdução descrevendo exatamente o que é um patch e como aplicá-lo aos diferentes ramos (branches) de desenvolvimento do kernel. @@ -435,7 +436,7 @@ individualmente, em vez de escrever tudo no topo do e-mail. Se você adicionar patches ao seu e-mail, certifique-se de que sejam texto puro legível, conforme declarado em -:ref:`Documentation/process/submitting-patches.rst <submittingpatches>`. +:ref:`Documentation/translations/pt_BR/process/submitting-patches.rst <pt_BR_submittingpatches>`. Os desenvolvedores do kernel não querem lidar com anexos ou patches compactados; eles podem querer comentar linhas individuais do seu patch, o que só funciona dessa forma. Certifique-se de usar um programa de diff --git a/Documentation/translations/pt_BR/process/index.rst b/Documentation/translations/pt_BR/process/index.rst index eda2a3fc5166..d072f7e46767 100644 --- a/Documentation/translations/pt_BR/process/index.rst +++ b/Documentation/translations/pt_BR/process/index.rst @@ -26,6 +26,7 @@ sua entrada na comunidade do kernel. Como começar <howto> Guia do Processo de Desenvolvimento <development-process> + Enviando patches: o guia essencial para colocar o seu código no kernel <submitting-patches> Lista de verificação para submissão de patches do kernel Linux <submit-checklist> Ferramentas e guias técnicos para desenvolvedores do kernel @@ -38,10 +39,12 @@ devem estar familiarizados. :maxdepth: 1 Requisitos mínimos <changes> + Estilo de codificação do kernel Linux <coding-style> Informações sobre clientes de email para Linux <email-clients> Como aplicar patches <applying-patches> Backporting e resolução de conflitos <backporting> Adicionando uma nova chamada de Sistema <adding-syscalls> + Por que a classe de tipo "volatile" não deve ser usada <volatile-considered-harmful> Como não Deixar as ioctls malfeitas <botching-up-ioctls> Guias de políticas e declarações de desenvolvedores @@ -57,8 +60,12 @@ Estas são as regras pelas quais tentamos viver na comunidade do kernel Código de Conduta de Compromisso do Colaborador <code-of-conduct> Interpretação do Código de Conduta do Kernel Linux <code-of-conduct-interpretation> Modelos de Maturidade para Contribuição no Kernel Linux <contribution-maturity-model.rst> + Declaração de Aplicação do Kernel Linux <kernel-enforcement-statement> Declaração sobre Drivers do Kernel <kernel-driver-statement> + A interface de drivers do kernel Linux <stable-api-nonsense> Estilo de gerenciamento do kernel Linux <management-style> + Assistentes de código <coding-assistants> + O manual da árvore tip <maintainer-tip> Conclave (Continuidade do projeto) <conclave> Lidando com bugs @@ -71,7 +78,9 @@ gerenciamento de bugs e vulnerabilidades. .. toctree:: :maxdepth: 1 + Dicas de depuração para desenvolvedores do Kernel Linux <debugging/index> Falhas de segurança <security-bugs> + Problemas de hardware sob embargo <embargoed-hardware-issues> CVEs <cve> Informações para mantenedores @@ -88,6 +97,7 @@ mantenedores de subsistemas. Processo do subsistema SoC <maintainer-soc> Conformidade de DTS para SoC <maintainer-soc-clean-dts> Processo do subsistema KVM x86 <maintainer-kvm-x86> + Subsistema de Devicetree e Open Firmware <maintainer-devicetree> Outros materiais ---------------- diff --git a/Documentation/translations/pt_BR/process/kernel-docs.rst b/Documentation/translations/pt_BR/process/kernel-docs.rst index 3c8d80ffa567..6235b1e7bde0 100644 --- a/Documentation/translations/pt_BR/process/kernel-docs.rst +++ b/Documentation/translations/pt_BR/process/kernel-docs.rst @@ -1,5 +1,7 @@ .. SPDX-License-Identifier: GPL-2.0 +.. _pt_BR_kernel_docs: + Índice de Documentação Adicional do Kernel ========================================== diff --git a/Documentation/translations/pt_BR/process/kernel-enforcement-statement.rst b/Documentation/translations/pt_BR/process/kernel-enforcement-statement.rst new file mode 100644 index 000000000000..3833c433c36b --- /dev/null +++ b/Documentation/translations/pt_BR/process/kernel-enforcement-statement.rst @@ -0,0 +1,163 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Declaração de Aplicação do Kernel Linux +--------------------------------------- + +Como desenvolvedores do kernel Linux, temos um grande interesse em como nosso +software é usado e como a licença do nosso software é aplicada. A conformidade +com as obrigações de compartilhamento recíproco da GPL-2.0 é crítica para a +sustentabilidade a longo prazo do nosso software e da nossa comunidade. + +Embora exista o direito de aplicar os interesses de direitos autorais separados nas +contribuições feitas à nossa comunidade, compartilhamos o interesse em garantir +que ações de aplicação individuais sejam conduzidas de uma maneira que beneficie +nossa comunidade e não tenham um impacto negativo não intencional na saúde e no +crescimento do nosso ecossistema de software. A fim de deter ações de aplicação +inúteis, concordamos que é do melhor interesse da nossa comunidade de +desenvolvimento assumir o seguinte compromisso com os usuários do kernel Linux, +em nosso nome e em nome de quaisquer sucessores dos nossos interesses de +direitos autorais: + + Não obstante as disposições de rescisão da GPL-2.0, concordamos que + é do melhor interesse da nossa comunidade de desenvolvimento adotar as + seguintes disposições da GPL-3.0 como permissões adicionais sob nossa + licença com relação a qualquer reivindicação não defensiva de direitos sob a + licença. + + No entanto, se você cessar toda violação desta Licença, sua licença + de um detentor de direitos autorais específico será restabelecida (a) + provisoriamente, a menos e até que o detentor de direitos autorais encerre + explícita e definitivamente sua licença, e (b) permanentemente, se o + detentor de direitos autorais não notificar você sobre a violação por + algum meio razoável antes de 60 dias após a cessação. + + Além disso, sua licença de um detentor de direitos autorais específico é + restabelecida permanentemente se o detentor de direitos autorais + notificá-lo da violação por algum meio razoável, se esta for a primeira + vez que você recebe um aviso de violação desta Licença (para qualquer + trabalho) daquele detentor de direitos autorais, e você sanar a violação + antes de 30 dias após o recebimento do aviso. + +Nossa intenção ao fornecer essas garantias é incentivar um maior uso do +software. Queremos que empresas e indivíduos usem, modifiquem e distribuam +este software. Queremos trabalhar com os usuários de forma aberta e transparente +para eliminar qualquer incerteza sobre nossas expectativas em relação à +conformidade ou aplicação que possa limitar a adoção do nosso software. Vemos +a ação judicial como um último recurso, a ser iniciada apenas quando outros +esforços da comunidade falharem em resolver o problema. + +Por fim, uma vez que um problema de não conformidade seja resolvido, esperamos +que o usuário se sinta bem-vindo para se juntar a nós em nossos esforços neste +projeto. Trabalhando juntos, seremos mais fortes. + +Exceto onde indicado abaixo, falamos apenas por nós mesmos, e não por qualquer +empresa para a qual possamos trabalhar hoje, no passado ou no futuro. + + - Bjorn Andersson (Linaro) + - Andrea Arcangeli + - Neil Armstrong + - Jens Axboe + - Pablo Neira Ayuso + - Khalid Aziz + - Ralf Baechle + - Felipe Balbi + - Arnd Bergmann + - Ard Biesheuvel + - Tim Bird + - Paolo Bonzini + - Christian Borntraeger + - Mark Brown (Linaro) + - Paul Burton + - Javier Martinez Canillas + - Rob Clark + - Kees Cook (Google) + - Jonathan Corbet + - Dennis Dalessandro + - Vivien Didelot (Savoir-faire Linux) + - Hans de Goede + - Mel Gorman (SUSE) + - Sven Eckelmann + - Alex Elder (Linaro) + - Fabio Estevam + - Larry Finger + - Bhumika Goyal + - Andy Gross + - Juergen Gross + - Shawn Guo + - Ulf Hansson + - Stephen Hemminger (Microsoft) + - Tejun Heo + - Rob Herring + - Masami Hiramatsu + - Michal Hocko + - Simon Horman + - Johan Hovold (Hovold Consulting AB) + - Christophe JAILLET + - Olof Johansson + - Lee Jones (Linaro) + - Heiner Kallweit + - Srinivas Kandagatla + - Jan Kara + - Shuah Khan (Samsung) + - David Kershner + - Jaegeuk Kim + - Namhyung Kim + - Colin Ian King + - Jeff Kirsher + - Greg Kroah-Hartman (Linux Foundation) + - Christian König + - Vinod Koul + - Krzysztof Kozlowski + - Viresh Kumar + - Aneesh Kumar K.V + - Julia Lawall + - Doug Ledford + - Chuck Lever (Oracle) + - Daniel Lezcano + - Shaohua Li + - Xin Long + - Tony Luck + - Catalin Marinas (Arm Ltd) + - Mike Marshall + - Chris Mason + - Paul E. McKenney + - Arnaldo Carvalho de Melo + - David S. Miller + - Ingo Molnar + - Kuninori Morimoto + - Trond Myklebust + - Martin K. Petersen (Oracle) + - Borislav Petkov + - Jiri Pirko + - Josh Poimboeuf + - Sebastian Reichel (Collabora) + - Guenter Roeck + - Joerg Roedel + - Leon Romanovsky + - Steven Rostedt (VMware) + - Frank Rowand + - Ivan Safonov + - Anna Schumaker + - Jes Sorensen + - K.Y. Srinivasan + - David Sterba (SUSE) + - Heiko Stuebner + - Jiri Kosina (SUSE) + - Willy Tarreau + - Dmitry Torokhov + - Linus Torvalds + - Thierry Reding + - Rik van Riel + - Luis R. Rodriguez + - Geert Uytterhoeven (Glider bvba) + - Eduardo Valentin (Amazon.com) + - Daniel Vetter + - Linus Walleij + - Richard Weinberger + - Dan Williams + - Rafael J. Wysocki + - Arvind Yadav + - Masahiro Yamada + - Wei Yongjun + - Lv Zheng + - Marc Zyngier (Arm Ltd) diff --git a/Documentation/translations/pt_BR/process/license-rules.rst b/Documentation/translations/pt_BR/process/license-rules.rst index 1e395dfea875..7a801b2a4f4e 100644 --- a/Documentation/translations/pt_BR/process/license-rules.rst +++ b/Documentation/translations/pt_BR/process/license-rules.rst @@ -1,5 +1,7 @@ .. SPDX-License-Identifier: GPL-2.0 +.. _pt_BR_kernel_licensing: + Regras de licenciamento do kernel Linux ======================================= diff --git a/Documentation/translations/pt_BR/process/maintainer-devicetree.rst b/Documentation/translations/pt_BR/process/maintainer-devicetree.rst new file mode 100644 index 000000000000..be26d89defdf --- /dev/null +++ b/Documentation/translations/pt_BR/process/maintainer-devicetree.rst @@ -0,0 +1,76 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================================= +Subsistema de Devicetree e Open Firmware +========================================= + +Outros documentos sobre o processo +---------------------------------- + +Consulte os documentos em Documentation/devicetree/bindings/ para saber como +escrever bindings de Devicetree corretamente e como enviar patches. + +Revisão e tratamento de patches +------------------------------- + +Os patches sob responsabilidade dos mantenedores de Devicetree são processados +de formas distintas, conforme o tipo de patch: + +1. Código central de drivers OF, por exemplo, drivers/of/: + os patches são revisados e aplicados pelos mantenedores de DT. + +2. Bindings de Devicetree: + os patches são revisados pelos mantenedores de DT, mas devem ser aplicados + pelos mantenedores do subsistema, exceto em alguns casos. Consulte também + *Para mantenedores do kernel* em + Documentation/devicetree/bindings/submitting-patches.rst. + +3. DTS e drivers: + os mantenedores de DT podem fazer comentários, mas, em geral, não se espera + uma revisão. Os DTS devem passar nas verificações de esquema + (dtbs_check) ou, ao menos, não gerar novos avisos. + +Patchwork +~~~~~~~~~ + +Os mantenedores de Devicetree revisam patches usando o Patchwork; portanto, o +status atual de um patch pode ser consultado por lá. Em submissões típicas de +drivers, o Patchwork recebe toda a série de patches, mas normalmente apenas +alguns patches são bindings de Devicetree e, assim, revisados pelos +mantenedores de DT. + +Explicação dos status do Patchwork: + + - **New**: ainda não processado pelo conjunto de ferramentas de automação. + - **Needs ACK**: aguardando revisão dos mantenedores de DT. + - **Handled Elsewhere**: patch não relacionado a DT; não será revisado aqui. + - **RFC**: o patch provavelmente foi ignorado por ser um RFC incompleto. + - **Changes Requested**: o patch foi revisado e os mantenedores de DT esperam + alterações. + - **Accepted**: o patch foi revisado e aplicado pelos mantenedores de DT em + sua árvore. + - **Not Applicable**: o patch foi revisado e provavelmente está em boas + condições, com uma tag *Reviewed-by* ou *Acked-by* fornecida, mas os + mantenedores de DT esperam que outra pessoa o aplique. + +Nova revisão e pings de patches +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Devido ao alto volume de e-mails, os mantenedores de Devicetree não leem todas +as mensagens que recebem; em vez disso, eles dependem do Patchwork durante o +processo de revisão. Além disso, muitas vezes deixam de lado patches que já +foram revisados. + +Como resultado, os mantenedores podem não perceber: + +1. Perguntas sobre patches já revisados. +2. Pings, por exemplo, quando um patch foi revisado pelos mantenedores de DT, + mas ainda não foi aplicado pelos mantenedores do subsistema. + +Esses casos podem ser tratados das seguintes formas: + +1. Enviando um ping aos mantenedores de DT no canal de IRC. +2. Removendo a tag *Acked-by* ou *Reviewed-by* do mantenedor de DT ao enviar + uma nova versão da série de patches, junto com uma explicação no changelog + do patch sobre o motivo da remoção da tag e o que se espera dos mantenedores + de DT. diff --git a/Documentation/translations/pt_BR/process/maintainer-handbooks.rst b/Documentation/translations/pt_BR/process/maintainer-handbooks.rst index b7aab788ffdb..1307306501ab 100644 --- a/Documentation/translations/pt_BR/process/maintainer-handbooks.rst +++ b/Documentation/translations/pt_BR/process/maintainer-handbooks.rst @@ -5,8 +5,8 @@ Notas sobre o processo de desenvolvimento de subsistemas e mantenedores O propósito deste documento é fornecer informações específicas de subsistemas que são suplementares ao manual geral do processo de -desenvolvimento. -:ref:`Documentation/process <development_process_main>`. +desenvolvimento +:ref:`Documentation/translations/pt_BR/process <pt_BR_development_process_main>`. Para desenvolvedores, veja abaixo todos os guias específicos de subsistemas conhecidos. Se o subsistema para o qual você está diff --git a/Documentation/translations/pt_BR/process/maintainer-kvm-x86.rst b/Documentation/translations/pt_BR/process/maintainer-kvm-x86.rst index 6480ff08b9d8..ef133d32c517 100644 --- a/Documentation/translations/pt_BR/process/maintainer-kvm-x86.rst +++ b/Documentation/translations/pt_BR/process/maintainer-kvm-x86.rst @@ -122,7 +122,7 @@ Quando se trata de estilo, nomenclatura, padrões, etc., a consistência é a prioridade número um no KVM x86. Se tudo mais falhar, siga o que já existe. Com algumas ressalvas listadas abaixo, siga o estilo de codificação preferido -dos mantenedores da árvore "tip" (:ref:`maintainer-tip-coding-style`), já que +dos mantenedores da árvore "tip" (:ref:`pt_BR_maintainer-tip-coding-style`), já que patches/séries frequentemente tocam tanto arquivos do KVM quanto arquivos x86 não-KVM, ou seja, atraem a atenção de mantenedores do KVM *e* da árvore "tip". @@ -206,7 +206,7 @@ Novos tópicos surgem ocasionalmente, mas, por favor, inicie uma discussão na lista se desejar propor a introdução de um novo tópico; ou seja, não aja por conta própria. -Veja :ref:`the_canonical_patch_format` para mais informações, com uma ressalva: +Veja :ref:`pt_BR_the_canonical_patch_format` para mais informações, com uma ressalva: não trate o limite de 70-75 caracteres como um limite absoluto e rígido. Em vez disso, use 75 caracteres como um limite firme, mas não rígido, e use 80 caracteres como um limite intransponível. Ou seja, permita que o shortlog @@ -218,7 +218,7 @@ Changelog O mais importante: escreva os changelogs usando o modo imperativo e evite o uso de pronomes. -Veja :ref:`describe_changes` para mais informações, com uma ressalva: comece com +Veja :ref:`pt_BR_describe_changes` para mais informações, com uma ressalva: comece com uma breve descrição das mudanças reais e, em seguida, apresente o contexto e o histórico. Note! Esta ordem entra em conflito direto com a abordagem preferida da árvore "tip"! Por favor, siga o estilo preferido da árvore "tip" ao enviar @@ -431,5 +431,5 @@ Bugs que podem ser explorados pelo convidado (guest) para atacar o hospedeiro (host) (kernel ou espaço do usuário), ou que podem ser explorados por uma VM aninhada (nested) contra o *seu* próprio hospedeiro (L2 atacando L1), são de interesse particular para o KVM. Por favor, siga o protocolo em -:ref:`securitybugs` se você suspeitar que um bug possa levar a um escape, -vazamento de dados, etc. +:ref:`pt_BR_securitybugs` se você suspeitar que um bug possa levar a um +escape, vazamento de dados, etc. diff --git a/Documentation/translations/pt_BR/process/maintainer-soc-clean-dts.rst b/Documentation/translations/pt_BR/process/maintainer-soc-clean-dts.rst index a7e7bf0f106f..7256c71534a7 100644 --- a/Documentation/translations/pt_BR/process/maintainer-soc-clean-dts.rst +++ b/Documentation/translations/pt_BR/process/maintainer-soc-clean-dts.rst @@ -8,8 +8,9 @@ Visão Geral ----------- As plataformas SoC ou subarquiteturas devem seguir todas as regras de -Documentation/process/maintainer-soc.rst. Este documento, referenciado em -MAINTAINERS, impõe requisitos adicionais listados abaixo. +Documentation/translations/pt_BR/process/maintainer-soc.rst. Este +documento, referenciado em MAINTAINERS, impõe requisitos adicionais +listados abaixo. Conformidade Estrita com DT Schema de DTS e dtc ----------------------------------------------- diff --git a/Documentation/translations/pt_BR/process/maintainer-tip.rst b/Documentation/translations/pt_BR/process/maintainer-tip.rst new file mode 100644 index 000000000000..e583bad4282d --- /dev/null +++ b/Documentation/translations/pt_BR/process/maintainer-tip.rst @@ -0,0 +1,847 @@ +.. SPDX-License-Identifier: GPL-2.0 + +O manual da árvore tip +====================== + +O que é a árvore tip? +--------------------- + +A árvore tip é uma coleção de vários subsistemas e áreas de +desenvolvimento. A árvore tip é tanto uma árvore de desenvolvimento direto quanto uma +árvore de agregação para várias árvores de sub-mantenedores. A URL gitweb da árvore tip +é: https://git.kernel.org/pub/scm/linux/kernel/git/tip/tip.git + +A árvore tip contém os seguintes subsistemas: + + - **Arquitetura x86** + + O desenvolvimento da arquitetura x86 ocorre na árvore tip, exceto + pelas partes específicas do KVM e XEN no x86, que são mantidas nos + subsistemas correspondentes e roteadas diretamente para a mainline a partir + dali. Ainda é uma boa prática enviar Cc para os mantenedores x86 nos + patches do KVM e XEN específicos para x86. + + Alguns subsistemas x86 têm seus próprios mantenedores além dos + mantenedores gerais do x86. Por favor, envie Cc para os mantenedores gerais do x86 em + patches que toquem em arquivos em arch/x86, mesmo quando não forem indicados + pelo arquivo MAINTAINER. + + Note que ``x86@kernel.org`` não é uma lista de discussão. É meramente um + alias de e-mail que distribui mensagens para a equipe de mantenedores de nível superior + do x86. Por favor, sempre envie Cc para a lista de discussão do Linux Kernel (LKML) + ``linux-kernel@vger.kernel.org``, caso contrário, seu e-mail acabará apenas nas + caixas de entrada privadas dos mantenedores. + + - **Scheduler** + + O desenvolvimento do scheduler ocorre na árvore -tip, na + branch sched/core - com ocasionais árvores de subtópicos para + conjuntos de patches em progresso. + + - **Locking e atomics** + + O desenvolvimento de locking (incluindo atomics e outras primitivas de + sincronização que estão conectadas ao locking) ocorre na árvore -tip, + na branch locking/core - com ocasionais árvores de subtópicos + para conjuntos de patches em progresso. + + - **Subsistema genérico de interrupções e drivers de chip de interrupção**: + + - o desenvolvimento do núcleo de interrupções ocorre na branch irq/core + + - o desenvolvimento do driver de chip de interrupção também ocorre na branch + irq/core, mas os patches geralmente são aplicados em uma árvore de mantenedor + separada e depois agregados na irq/core + + - **Tempo, timers, timekeeping, NOHZ e drivers de chip relacionados**: + + - o desenvolvimento do timekeeping, núcleo clocksource, NTP e alarmtimer + ocorre na branch timers/core, mas os patches geralmente são aplicados em + uma árvore de mantenedor separada e depois agregados na timers/core + + - o desenvolvimento do driver clocksource/event ocorre na branch + timers/core, mas os patches são em sua maioria aplicados em uma árvore de mantenedor + separada e depois agregados na timers/core + + - **Núcleo de contadores de desempenho, suporte a arquitetura e ferramentas**: + + - o desenvolvimento do núcleo perf e suporte a arquitetura ocorre na + branch perf/core + + - o desenvolvimento de ferramentas perf ocorre na árvore do mantenedor + de ferramentas perf e é agregado à árvore tip. + + - **Núcleo de hotplug de CPU** + + - **Núcleo RAS** + + Em sua maioria, os patches RAS específicos para x86 são coletados na branch + ras/core da árvore tip. + + - **Núcleo EFI** + + Desenvolvimento EFI na árvore git efi. Os patches coletados são + agregados na branch efi/core da árvore tip. + + - **RCU** + + O desenvolvimento do RCU ocorre na árvore linux-rcu. As mudanças resultantes + são agregadas na branch core/rcu da árvore tip. + + - **Vários componentes de código do núcleo**: + + - debugobjects + + - objtool + + - partes e peças aleatórias + + +Notas de submissão de patch +--------------------------- + +Selecionando a árvore/branch +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Em geral, o desenvolvimento contra o head da branch master da árvore tip é +adequado, mas para os subsistemas que são mantidos separadamente, possuem sua +própria árvore git e são apenas agregados na árvore tip, o desenvolvimento deve +ocorrer contra a árvore ou branch do subsistema relevante. + +Correções de bugs que visam a mainline devem sempre ser aplicáveis contra a +árvore do kernel mainline. Potenciais conflitos contra mudanças que já estão +na fila da árvore tip são resolvidos pelos mantenedores. + +Assunto do patch +^^^^^^^^^^^^^^^^ + +O formato preferido da árvore tip para prefixos de assunto do patch é +'subsys/component:', ex. 'x86/apic:', 'x86/mm/fault:', 'sched/fair:', +'genirq/core:'. Por favor, não use nomes de arquivos ou caminhos de arquivos completos como +prefixo. 'git log path/to/file' deve lhe dar uma dica razoável na maioria +dos casos. + +A descrição condensada do patch na linha de assunto deve começar com uma +letra maiúscula e deve ser escrita em tom imperativo. + + +Changelog +^^^^^^^^^ + +As regras gerais sobre changelogs no :ref:`Guia de submissão de patches +<pt_BR_describe_changes>`, se aplicam. + +Os mantenedores da árvore tip valorizam seguir essas regras, especialmente no +pedido para escrever changelogs no modo imperativo e não personificando +o código ou sua execução. Isso não é apenas um capricho dos +mantenedores. Changelogs escritos em palavras abstratas são mais precisos e +tendem a ser menos confusos do que aqueles escritos em forma de romances. + +Também é útil estruturar o changelog em vários parágrafos e não +juntar tudo em um só. Uma boa estrutura é explicar +o contexto, o problema e a solução em parágrafos separados e nesta +ordem. + +Exemplos para ilustração: + + Exemplo 1:: + + x86/intel_rdt/mbm: Corrigir o manipulador de overflow do MBM durante hot cpu + + Quando uma CPU está morrendo, cancelamos o worker e agendamos um novo worker em uma + CPU diferente no mesmo domínio. Mas se o timer já está prestes a + expirar (digamos 0.99s) então essencialmente dobramos o intervalo. + + Modificamos o tratamento de hot cpu para cancelar o trabalho atrasado na cpu + que está morrendo e executar o worker imediatamente em uma cpu diferente no mesmo domínio. Não + fazemos o flush do worker porque o worker de overflow do MBM reagenda o + worker na mesma CPU e escaneia a domain->cpu_mask para obter o ponteiro + do domínio. + + Versão melhorada:: + + x86/intel_rdt/mbm: Corrigir o manipulador de overflow do MBM durante hotplug de CPU + + Quando uma CPU está morrendo, o worker de overflow é cancelado e reagendado em uma + CPU diferente no mesmo domínio. Mas se o timer já estiver prestes a + expirar isso essencialmente dobra o intervalo, o que pode resultar em um overflow + não detectado. + + Cancele o worker de overflow e reagende-o imediatamente em uma CPU diferente + no mesmo domínio. O trabalho também poderia sofrer um flush, mas isso iria + reagendá-lo na mesma CPU. + + Exemplo 2:: + + time: POSIX CPU timers: Garantir que a variável seja inicializada + + Se cpu_timer_sample_group retornar -EINVAL, ela não terá escrito em + *sample. Checar o valor de retorno de cpu_timer_sample_group previne o + uso potencial de um valor não inicializado de now no bloco seguinte. + Dado um clock_idx inválido, o código anterior poderia caso contrário sobrescrever + *oldval de maneira indefinida. Isso agora é prevenido. Também exploramos + o curto-circuito do && para amostrar o timer apenas se o resultado for + realmente usado para atualizar *oldval. + + Versão melhorada:: + + posix-cpu-timers: Tornar set_process_cpu_timer() mais robusto + + Como o valor de retorno de cpu_timer_sample_group() não é checado, + compiladores e checadores estáticos podem legitimamente avisar sobre um uso potencial + da variável não inicializada 'now'. Isso não é um problema de tempo de execução pois todos + os locais de chamada passam ids de clock válidos. + + Além disso, cpu_timer_sample_group() é invocado incondicionalmente mesmo quando o + resultado não é usado porque *oldval é NULL. + + Torne a invocação condicional e cheque o valor de retorno. + + Exemplo 3:: + + A entidade também pode ser usada para outros propósitos. + + Vamos renomeá-la para ser mais genérica. + + Versão melhorada:: + + A entidade também pode ser usada para outros propósitos. + + Renomeie para ser mais genérica. + + +Para cenários complexos, especialmente condições de corrida (race conditions) e problemas +de ordenação de memória, é valioso descrever o cenário com uma tabela que mostra +o paralelismo e a ordem temporal dos eventos. Aqui está um exemplo:: + + CPU0 CPU1 + free_irq(X) interrupt X + spin_lock(desc->lock) + wake irq thread() + spin_unlock(desc->lock) + spin_lock(desc->lock) + remove action() + shutdown_irq() + release_resources() thread_handler() + spin_unlock(desc->lock) access released resources. + ^^^^^^^^^^^^^^^^^^^^^^^^^ + synchronize_irq() + +O Lockdep fornece uma saída útil semelhante para descrever um possível cenário +de deadlock:: + + CPU0 CPU1 + rtmutex_lock(&rcu->rt_mutex) + spin_lock(&rcu->rt_mutex.wait_lock) + local_irq_disable() + spin_lock(&timer->it_lock) + spin_lock(&rcu->mutex.wait_lock) + --> Interrupt + spin_lock(&timer->it_lock) + +Referências a funções em changelogs +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Quando uma função é mencionada no changelog, seja no corpo do texto ou na +linha de assunto, por favor use o formato 'nome_da_funcao()'. Omitir os +parênteses após o nome da função pode ser ambíguo:: + + Subject: subsys/component: Make reservation_count static + + reservation_count is only used in reservation_stats. Make it static. + +A variante com parênteses é mais precisa:: + + Subject: subsys/component: Make reservation_count() static + + reservation_count() is only called from reservation_stats(). Make it + static. + + +Backtraces em changelogs +^^^^^^^^^^^^^^^^^^^^^^^^ + +Veja :ref:`pt_BR_backtraces`. + +Ordenação das tags de commit +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Para ter uma visão uniforme das tags de commit, os mantenedores da tip usam o +seguinte esquema de ordenação de tags: + + - Fixes: 12+char-SHA1 ("sub/sys: Original subject line") + + Uma tag Fixes deve ser adicionada mesmo para alterações que não precisam ser + portadas de volta (backported) para kernels estáveis, ou seja, quando abordar um + problema recém-introduzido que afeta apenas a árvore tip ou o head atual da linha principal (mainline). Estas tags + são úteis para identificar o commit original e são muito mais valiosas + do que mencionar de forma proeminente o commit que introduziu um problema no + próprio texto do changelog, porque elas podem ser automaticamente + extraídas. + + O exemplo a seguir ilustra a diferença:: + + Commit + + abcdef012345678 ("x86/xxx: Replace foo with bar") + + deixou uma instância não utilizada da variável foo. Remova-a. + + Signed-off-by: J.Dev <j.dev@mail> + + Por favor, diga em vez disso:: + + A recente substituição de foo por bar deixou uma instância não utilizada da + variável foo. Remova-a. + + Fixes: abcdef012345678 ("x86/xxx: Replace foo with bar") + Signed-off-by: J.Dev <j.dev@mail> + + O último coloca as informações sobre o patch em foco e + as complementa com a referência ao commit que introduziu o problema, + em vez de colocar o foco no commit original em primeiro lugar. + + - Reported-by: ``Reporter <reporter@mail>`` + + - Closes: ``URL or Message-ID of the bug report this is fixing`` + + - Originally-by: ``Original author <original-author@mail>`` + + - Suggested-by: ``Suggester <suggester@mail>`` + + - Co-developed-by: ``Co-author <co-author@mail>`` + + Signed-off-by: ``Co-author <co-author@mail>`` + + Note que Co-developed-by e Signed-off-by do(s) co-autor(es) devem + vir em pares. + + - Signed-off-by: ``Author <author@mail>`` + + O primeiro Signed-off-by (SOB) após o último par Co-developed-by/SOB é o + SOB do autor, ou seja, a pessoa marcada como autora pelo git. + + - Signed-off-by: ``Patch handler <handler@mail>`` + + SOBs após o SOB do autor são de pessoas que lidam e transportam + o patch, mas não estiveram envolvidas no desenvolvimento. As cadeias de SOB devem + refletir a rota **real** que um patch tomou conforme foi propagado para nós, + com a primeira entrada de SOB sinalizando a autoria principal de um único + autor. Acks devem ser dados como linhas Acked-by e aprovações de revisão + como linhas Reviewed-by. + + Se o manipulador fez modificações no patch ou no changelog, então + isso deve ser mencionado **após** o texto do changelog e **acima** + de todas as tags de commit no seguinte formato:: + + ... o texto do changelog termina. + + [ handler: Substituiu foo por bar e atualizou o changelog ] + + First-tag: ..... + + Observe as duas novas linhas vazias que separam o texto do changelog e as + tags de commit daquele aviso. + + Se um patch for enviado para a lista de discussão por um manipulador, então o autor tem + que ser notado na primeira linha do changelog com:: + + From: Author <author@mail> + + O texto do changelog começa aqui.... + + assim a autoria é preservada. A linha 'From:' tem que ser seguida + por uma nova linha vazia. Se essa linha 'From:' estiver faltando, então o patch + seria atribuído à pessoa que o enviou (transportou, manipulou). + A linha 'From:' é automaticamente removida quando o patch é aplicado + e não aparece no changelog final do git. Ela meramente afeta + a informação de autoria do commit resultante do Git. + + - Tested-by: ``Tester <tester@mail>`` + + - Reviewed-by: ``Reviewer <reviewer@mail>`` + + - Acked-by: ``Acker <acker@mail>`` + + - Cc: ``cc-ed-person <person@mail>`` + + Se o patch deve ser portado para stable, então por favor adicione uma tag '``Cc: + stable@vger.kernel.org``', mas não coloque em Cc o stable ao enviar o seu + e-mail. + + - Link: ``https://link/to/information`` + + Para se referir a um e-mail postado nas listas de discussão do kernel, por favor + use o URL de redirecionamento lore.kernel.org:: + + Link: https://lore.kernel.org/email-message-id@here + + Esta URL deve ser usada ao se referir a tópicos de lista de discussão relevantes, + conjuntos de patches relacionados, ou outras threads de discussão notáveis. + Uma maneira conveniente de associar os trailers ``Link:`` com a mensagem de commit + é usar a notação de colchetes semelhante ao markdown, por exemplo:: + + A similar approach was attempted before as part of a different + effort [1], but the initial implementation caused too many + regressions [2], so it was backed out and reimplemented. + + Link: https://lore.kernel.org/some-msgid@here # [1] + Link: https://bugzilla.example.org/bug/12345 # [2] + + Você também pode usar os trailers ``Link:`` para indicar a origem do + patch ao aplicá-lo em sua árvore git. Neste caso, por favor use o + domínio dedicado ``patch.msgid.link`` em vez de ``lore.kernel.org``. + Esta prática torna possível que as ferramentas automatizadas identifiquem + qual link usar para recuperar o envio do patch original. Por + exemplo:: + + Link: https://patch.msgid.link/patch-source-message-id@here + +Por favor não use tags combinadas, ex. ``Reported-and-tested-by``, pois +elas apenas complicam a extração automatizada de tags. + + +Links para documentação +^^^^^^^^^^^^^^^^^^^^^^^ + +Fornecer links para a documentação no changelog é uma grande ajuda para depuração e +análise posteriores. Infelizmente, os URLs costumam quebrar muito rapidamente +porque as empresas reestruturam seus sites frequentemente. Exceções não 'voláteis' +incluem o Intel SDM e o AMD APM. + +Portanto, para documentos 'voláteis', por favor crie uma entrada no bugzilla do kernel +https://bugzilla.kernel.org e anexe uma cópia desses documentos +à entrada do bugzilla. Finalmente, forneça o URL da entrada do bugzilla no +changelog. + +Reenvio de patch ou lembretes +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Veja :ref:`pt_BR_resend_reminders`. + +Janela de merge +^^^^^^^^^^^^^^^ + +Por favor, não espere que os patches sejam revisados ou mesclados pelos mantenedores da árvore tip +em torno ou durante a janela de merge. As árvores ficam fechadas +para todos, exceto correções urgentes, durante esse tempo. Elas reabrem assim que a janela de merge +fecha e um novo kernel -rc1 é lançado. + +Grandes séries devem ser enviadas em estado mesclável (mergeable state) *pelo* *menos* uma semana +antes da janela de merge abrir. Exceções são feitas para correções de bugs e +*às vezes* para pequenos drivers independentes para novos hardwares ou patches minimamente +invasivos para ativação de hardware. + +Durante a janela de merge, os mantenedores se concentram em seguir as +alterações upstream, corrigir problemas resultantes da janela de merge, coletar correções de bugs, e +se permitir um respiro. Por favor, respeite isso. + +Os chamados branches _urgent_ serão mesclados na linha principal (mainline) durante a +fase de estabilização de cada versão. + + +Git +^^^ + +Os mantenedores da árvore tip aceitam pull requests do git de mantenedores que fornecem +alterações de subsistema para agregação na árvore tip. + +Pull requests para novos envios de patches normalmente não são aceitos e não +substituem o envio adequado de patch para a lista de discussão. O principal motivo para +isso é que o fluxo de trabalho de revisão é baseado em e-mail. + +Se você enviar uma série maior de patches, é útil fornecer um branch git +em um repositório privado que permita que pessoas interessadas façam pull da +série facilmente para testes. A maneira usual de oferecer isso é uma URL do git na carta de apresentação (cover letter) +da série de patches. + +Testes +^^^^^^ + +O código deve ser testado antes de ser enviado para os mantenedores da árvore tip. Qualquer coisa +além de alterações menores deve ser construída, inicializada e testada com +opções abrangentes (e pesadas) de depuração do kernel ativadas. + +Essas opções de depuração podem ser encontradas em kernel/configs/x86_debug.config +e podem ser adicionadas a uma configuração de kernel existente executando: + + make x86_debug.config + +Algumas dessas opções são específicas do x86 e podem ser deixadas de fora ao testar +em outras arquiteturas. + +.. _pt_BR_maintainer-tip-coding-style: + +Notas de estilo de código +------------------------- + +Estilo de comentário +^^^^^^^^^^^^^^^^^^^^ + +Frases em comentários começam com uma letra maiúscula. + +Comentários de linha única:: + + /* Este é um comentário de linha única */ + +Comentários de várias linhas:: + + /* + * This is a properly formatted + * multi-line comment. + * + * Larger multi-line comments should be split into paragraphs. + */ + +Sem comentários no fim da linha (veja abaixo): + + Por favor, abstenha-se de usar comentários no fim da linha. Comentários no fim da linha atrapalham o + fluxo de leitura em quase todos os contextos, mas especialmente em código:: + + if (somecondition_is_true) /* Não coloque um comentário aqui */ + dostuff(); /* Nem aqui */ + + seed = MAGIC_CONSTANT; /* Nem aqui */ + + Use comentários independentes em vez disso:: + + /* Esta condição não é óbvia sem um comentário */ + if (somecondition_is_true) { + /* Isso realmente precisa ser documentado */ + dostuff(); + } + + /* Esta inicialização mágica precisa de um comentário. Talvez não? */ + seed = MAGIC_CONSTANT; + + Use o estilo C++, comentários no fim da linha ao documentar structs em headers para + alcançar um layout mais compacto e melhor legibilidade:: + + // eax + u32 x2apic_shift : 5, // Número de bits para deslocar o ID APIC para a direita + // para o ID de topologia no próximo nível + : 27; // Reservado + // ebx + u32 num_processors : 16, // Número de processadores no nível atual + : 16; // Reservado + + versus:: + + /* eax */ + /* + * Número de bits para deslocar o ID APIC para a direita para o ID de topologia + * no próximo nível + */ + u32 x2apic_shift : 5, + /* Reservado */ + : 27; + + /* ebx */ + /* Número de processadores no nível atual */ + u32 num_processors : 16, + /* Reservado */ + : 16; + +Comente as coisas importantes: + + Comentários devem ser adicionados onde a operação não é óbvia. Documentar + o óbvio é apenas uma distração:: + + /* Decrementa o refcount e verifica por zero */ + if (refcount_dec_and_test(&p->refcnt)) { + do; + lots; + of; + magic; + things; + } + + Em vez disso, os comentários devem explicar os detalhes não óbvios e documentar + as restrições:: + + if (refcount_dec_and_test(&p->refcnt)) { + /* + * Explicação muito boa de por que as coisas mágicas abaixo + * precisam ser feitas, restrições de ordenação e locking, + * etc.. + */ + do; + lots; + of; + magic; + /* Precisa ser a última operação porque ... */ + things; + } + +Comentários de documentação de função: + + Para documentar funções e seus argumentos por favor use o formato kernel-doc + e não comentários de formato livre:: + + /** + * magic_function - Faz muitas coisas mágicas + * @magic: Ponteiro para os dados mágicos nos quais operar + * @offset: Deslocamento no array de dados de @magic + * + * Explicação profunda das coisas misteriosas feitas com @magic junto + * com a documentação dos valores de retorno. + * + * Note que os descritores de argumento acima estão dispostos + * de forma tabular. + */ + + Isto se aplica especialmente a funções visíveis globalmente e funções + inline em arquivos de cabeçalho públicos. Pode ser um exagero usar o formato + kernel-doc para cada função (estática) que precisa de uma pequena explicação. O + uso de nomes de funções descritivos frequentemente substitui esses pequenos comentários. + Aplique o bom senso como sempre. + + +Documentando requisitos de locking +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + Documentar requisitos de locking é uma coisa boa, mas comentários não + são necessariamente a melhor escolha. Em vez de escrever:: + + /* Caller must hold foo->lock */ + void func(struct foo *foo) + { + ... + } + + Por favor, use:: + + void func(struct foo *foo) + { + lockdep_assert_held(&foo->lock); + ... + } + + Em kernels PROVE_LOCKING, lockdep_assert_held() emite um aviso + se o chamador não detém o lock. Comentários não podem fazer isso. + +Regras de chaves +^^^^^^^^^^^^^^^^ + +Chaves devem ser omitidas apenas se a instrução que se segue a 'if', 'for', +'while' etc. for verdadeiramente uma única linha:: + + if (foo) + do_something(); + +O seguinte não é considerado uma instrução de linha única mesmo +que o C não exija chaves:: + + for (i = 0; i < end; i++) + if (foo[i]) + do_something(foo[i]); + +Adicionar chaves ao redor do loop externo melhora o fluxo de leitura:: + + for (i = 0; i < end; i++) { + if (foo[i]) + do_something(foo[i]); + } + + +Declarações de variáveis +^^^^^^^^^^^^^^^^^^^^^^^^ + +A ordem preferida das declarações de variáveis no início de uma +função é a ordem de árvore de abeto invertida (reverse fir tree order):: + + struct long_struct_name *descriptive_name; + unsigned long foo, bar; + unsigned int tmp; + int ret; + +O que está acima é mais rápido de analisar do que a ordem invertida:: + + int ret; + unsigned int tmp; + unsigned long foo, bar; + struct long_struct_name *descriptive_name; + +E ainda mais do que uma ordem aleatória:: + + unsigned long foo, bar; + int ret; + struct long_struct_name *descriptive_name; + unsigned int tmp; + +Também por favor tente agregar variáveis do mesmo tipo em uma única +linha. Não há sentido em desperdiçar espaço na tela:: + + unsigned long a; + unsigned long b; + unsigned long c; + unsigned long d; + +É realmente suficiente fazer:: + + unsigned long a, b, c, d; + +Por favor, evite também introduzir divisões de linha em declarações de variáveis:: + + struct long_struct_name *descriptive_name = container_of(bar, + struct long_struct_name, + member); + struct foobar foo; + +É muito melhor mover a inicialização para uma linha separada após as +declarações:: + + struct long_struct_name *descriptive_name; + struct foobar foo; + + descriptive_name = container_of(bar, struct long_struct_name, member); + + +Tipos de variáveis +^^^^^^^^^^^^^^^^^^ + +Por favor use os tipos u8, u16, u32, u64 adequados para variáveis que são destinadas +a descrever hardware ou são usadas como argumentos para funções que acessam +hardware. Estes tipos definem claramente a largura em bits e evitam +truncamento, expansão e confusão entre 32/64 bits. + +u64 também é recomendado em código que se tornaria ambíguo para kernels +de 32 bits quando 'unsigned long' fosse usado em vez disso. Embora em tais +situações 'unsigned long long' pudesse ser usado também, u64 é mais curto +e também mostra claramente que a operação requer uma largura de 64 bits +independente da CPU alvo. + +Por favor use 'unsigned int' em vez de 'unsigned'. + + +Constantes +^^^^^^^^^^ + +Por favor, não use números (hexa)decimais literais em código ou inicializadores. +Ou use defines adequados que tenham nomes descritivos ou considere usar +um enum. + + +Declarações e inicializadores de struct +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +As declarações de struct devem alinhar os nomes dos membros da struct de forma +tabular:: + + struct bar_order { + unsigned int guest_id; + int ordered_item; + struct menu *menu; + }; + +Por favor, evite documentar os membros da struct dentro da declaração, pois +isso frequentemente resulta em comentários formatados de maneira estranha e os membros da struct +ficam ofuscados:: + + struct bar_order { + unsigned int guest_id; /* ID único do convidado */ + int ordered_item; + /* Ponteiro para uma instância de menu que contém todas as bebidas */ + struct menu *menu; + }; + +Em vez disso, por favor considere usar o formato kernel-doc em um comentário precedendo +a declaração da struct, que é mais fácil de ler e tem a vantagem adicional +de incluir a informação na documentação do kernel, por exemplo, da +seguinte forma:: + + + /** + * struct bar_order - Descrição de um pedido de bar + * @guest_id: ID único do convidado + * @ordered_item: O número do item do menu + * @menu: Ponteiro para o menu do qual o item + * foi pedido + * + * Informação suplementar para usar a struct. + * + * Note que os descritores dos membros da struct acima estão dispostos + * de forma tabular. + */ + struct bar_order { + unsigned int guest_id; + int ordered_item; + struct menu *menu; + }; + +Inicializadores de struct estáticos devem usar inicializadores C99 e também devem ser +alinhados de forma tabular:: + + static struct foo statfoo = { + .a = 0, + .plain_integer = CONSTANT_DEFINE_OR_ENUM, + .bar = &statbar, + }; + +Note que embora a sintaxe C99 permita a omissão da vírgula final, +nós recomendamos o uso de uma vírgula na última linha porque isso torna +o reordenamento e a adição de novas linhas mais fáceis, e também torna tais +patches futuros ligeiramente mais fáceis de ler. + +Quebras de linha +^^^^^^^^^^^^^^^^ + +Restringir o comprimento da linha a 80 caracteres torna código profundamente indentado difícil de +ler. Considere dividir o código em funções auxiliares para evitar quebra de +linha excessiva. + +A regra de 80 caracteres não é uma regra estrita, então por favor use bom senso ao +quebrar linhas. Especialmente strings de formato nunca devem ser divididas. + +Ao dividir declarações de funções ou chamadas de funções, então por favor alinhe +o primeiro argumento na segunda linha com o primeiro argumento na primeira +linha:: + + static int long_function_name(struct foobar *barfoo, unsigned int id, + unsigned int offset) + { + + if (!id) { + ret = longer_function_name(barfoo, DEFAULT_BARFOO_ID, + offset); + ... + +Namespaces +^^^^^^^^^^ + +Namespaces de funções/variáveis melhoram a legibilidade e permitem +grepping fácil. Estes namespaces são prefixos de string para nomes +de funções e variáveis visíveis globalmente, incluindo inlines. Estes prefixos devem +combinar o subsistema e o nome do componente como 'x86_comp\_', +'sched\_', 'irq\_', e 'mutex\_'. + +Isso também inclui funções estáticas de escopo de arquivo que são imediatamente colocadas +em templates de driver visíveis globalmente - é útil que esses símbolos +também carreguem um bom prefixo, para legibilidade do backtrace. + +Prefixos de namespace podem ser omitidos para funções e variáveis +estáticas locais. Funções verdadeiramente locais, chamadas apenas por outras funções locais, +podem ter nomes descritivos mais curtos - nossa preocupação principal é a facilidade de grepping +e a legibilidade do backtrace. + +Por favor note que os prefixos 'xxx_vendor\_' e 'vendor_xxx\_' não são +úteis para funções estáticas em arquivos específicos de fornecedores. Afinal, +já está claro que o código é específico do fornecedor. Além disso, nomes +de fornecedores devem ser apenas para funcionalidades verdadeiramente específicas de fornecedores. + +Como sempre, aplique o bom senso e vise a consistência e a legibilidade. + + +Notificações de commit +---------------------- + +A árvore tip é monitorada por um bot por novos commits. O bot envia um email +para cada novo commit para uma lista de discussão dedicada +(``linux-tip-commits@vger.kernel.org``) e coloca em Cc todas as pessoas que são +mencionadas em uma das tags de commit. Ele usa o ID da mensagem de email da +tag Link no final da lista de tags para definir o cabeçalho de email In-Reply-To para que +a mensagem seja encadeada corretamente com o email de submissão do patch. + +Os mantenedores e submantenedores tip tentam responder ao remetente +ao fazer o merge de um patch, mas às vezes eles esquecem ou isso não se encaixa no +fluxo de trabalho do momento. Embora a mensagem do bot seja puramente mecânica, ela +também implica em um 'Obrigado! Aplicado.'. diff --git a/Documentation/translations/pt_BR/process/management-style.rst b/Documentation/translations/pt_BR/process/management-style.rst index b92f8705c30f..9d067e04650a 100644 --- a/Documentation/translations/pt_BR/process/management-style.rst +++ b/Documentation/translations/pt_BR/process/management-style.rst @@ -1,13 +1,16 @@ .. SPDX-License-Identifier: GPL-2.0 +.. _pt_BR_managementstyle: + Estilo de gerenciamento do kernel Linux ======================================= Este é um documento curto descrevendo o estilo de gerenciamento preferido (ou inventado, dependendo de quem você perguntar) para o kernel do Linux. Ele se -destina a espelhar o documento :ref:`process/coding-style.rst <codingstyle>` em -algum grau, e foi escrito principalmente para evitar responder [#f1]_ as mesmas -(ou semelhantes) perguntas repetidamente. +destina a espelhar o documento +:ref:`Documentation/translations/pt_BR/process/coding-style.rst <pt_BR_codingstyle>` +em algum grau, e foi escrito principalmente para evitar responder [#f1]_ as +mesmas (ou semelhantes) perguntas repetidamente. Estilo de gerenciamento é muito pessoal e muito mais difícil de quantificar do que simples regras de estilo de codificação, então este documento pode ou não ter diff --git a/Documentation/translations/pt_BR/process/security-bugs.rst b/Documentation/translations/pt_BR/process/security-bugs.rst index 72c771869566..321575657b28 100644 --- a/Documentation/translations/pt_BR/process/security-bugs.rst +++ b/Documentation/translations/pt_BR/process/security-bugs.rst @@ -1,5 +1,7 @@ .. SPDX-License-Identifier: GPL-2.0 +.. _pt_BR_securitybugs: + Falhas de segurança =================== @@ -59,11 +61,11 @@ Além disso, as seguintes informações são altamente desejáveis: mantenedores, mesmo que a correção acabe não sendo a correta, pois ajuda a entender o bug. Ao propor uma correção testada, por favor, formate-a sempre de uma maneira que possa ser mesclada imediatamente (consulte - Documentation/process/submitting-patches.rst). Isso evitará algumas trocas - de mensagens caso ela seja aceita, e você receberá o crédito por - encontrar e corrigir o problema. Observe que, neste caso, apenas uma tag - ``Signed-off-by:`` é necessária, sem ``Reported-by:`` quando o relator e - o autor forem a mesma pessoa. + Documentation/translations/pt_BR/process/submitting-patches.rst). Isso + evitará algumas trocas de mensagens caso ela seja aceita, e você receberá + o crédito por encontrar e corrigir o problema. Observe que, neste caso, + apenas uma tag ``Signed-off-by:`` é necessária, sem ``Reported-by:`` + quando o relator e o autor forem a mesma pessoa. * **mitigações**: com muita frequência, durante a análise de um bug, surgem algumas maneiras de mitigar o problema. É útil compartilhá-las, @@ -228,8 +230,8 @@ a tornar esses relatórios desnecessariamente difíceis de lidar: Se a correção não puder ser testada porque depende de hardware raro ou de protocolos de rede quase extintos, é provável que o problema não seja um bug de segurança. Em qualquer caso, se uma correção for proposta, ela deve - aderir a Documentation/process/submitting-patches.rst e incluir uma tag - 'Fixes:' designando o commit que introduziu o bug. + aderir a Documentation/translations/pt_BR/process/submitting-patches.rst + e incluir uma tag 'Fixes:' designando o commit que introduziu o bug. A falha em considerar estes pontos expõe seu relatório ao risco de ser ignorado. @@ -280,7 +282,7 @@ entender e corrigir a vulnerabilidade de segurança. Por favor, envie e-mails em **texto simples** sem anexos, sempre que possível. É muito mais difícil ter uma discussão com citações de contexto sobre um problema complexo se todos os detalhes estiverem ocultos em anexos. Pense nisso -como uma :doc:`regular path submission </../../../process/submitting-patches>` +como uma :doc:`submissão pelo caminho normal <submitting-patches>` (mesmo que você ainda não tenha um patch): descreva o problema e o impacto, liste as etapas de reprodução e siga com uma proposta de correção, tudo em texto simples. Relatórios formatados em Markdown, HTML e RST são @@ -288,8 +290,9 @@ particularmente malvistos, pois são bastante difíceis de ler por humanos e incentivam o uso de visualizadores dedicados, às vezes online, o que por definição não é aceitável para um relatório de segurança confidencial. Note que alguns clientes de e-mail tendem a corromper a formatação de texto simples -por padrão; por favor, consulte Documentation/process/email-clients.rst para -mais informações. +por padrão; por favor, consulte +Documentation/translations/pt_BR/process/email-clients.rst para mais +informações. Divulgação e informações sob embargo ------------------------------------ @@ -359,7 +362,7 @@ A equipe de segurança não atribui CVEs, nem os exigimos para relatórios ou correções, pois isso pode complicar desnecessariamente o processo e adiar o tratamento do bug. Se um relator desejar que um identificador CVE seja atribuído para um problema confirmado, ele pode entrar em contato com a -:doc:`kernel CVE assignment team<../../../process/cve>` para obter um. +:doc:`equipe de atribuição de CVEs do kernel <cve>` para obter um. Acordo de não divulgação ------------------------ diff --git a/Documentation/translations/pt_BR/process/stable-api-nonsense.rst b/Documentation/translations/pt_BR/process/stable-api-nonsense.rst new file mode 100644 index 000000000000..c5d0e643eb32 --- /dev/null +++ b/Documentation/translations/pt_BR/process/stable-api-nonsense.rst @@ -0,0 +1,208 @@ +.. SPDX-License-Identifier: GPL-2.0 + +A interface de drivers do kernel Linux +======================================= + +(todas as suas perguntas respondidas e mais algumas) + +Greg Kroah-Hartman <greg@kroah.com> + +Este texto foi escrito para tentar explicar por que o Linux **não possui uma +interface binária do kernel nem uma interface estável do kernel**. + +.. note:: + + Observe que este artigo descreve as interfaces **internas do kernel**, e não + as interfaces entre o kernel e o espaço de usuário. + + A interface entre o kernel e o espaço de usuário é aquela utilizada pelos + aplicativos: a interface de chamadas de sistema (syscalls). Essa + interface é **muito** estável ao longo do tempo e não será quebrada. Tenho + programas antigos, compilados em uma versão do kernel anterior à 0.9 e alguma + coisa, que ainda funcionam perfeitamente na versão mais recente do kernel + 2.6. Essa é a interface cuja estabilidade os usuários e desenvolvedores de + aplicativos podem considerar garantida. + + +Resumo executivo +---------------- + +Você acha que quer uma interface estável do kernel, mas, na verdade, não quer, +e nem sabe disso. O que você realmente quer é um driver que continue +funcionando de maneira estável, e isso só é possível se o seu driver estiver +na árvore principal do kernel. Você também obtém muitos outros benefícios se +o seu driver fizer parte da árvore principal do kernel. São esses benefícios +que ajudaram a tornar o Linux um sistema operacional tão robusto, estável e +maduro — justamente a razão pela qual você o está usando. + + +Introdução +---------- + +Apenas quem escreve drivers para o kernel precisa se preocupar com as mudanças +nas interfaces internas do kernel. Para a grande maioria das pessoas, essas +interfaces nem sequer são visíveis e tampouco são motivo de preocupação. + +Antes de mais nada, não abordarei **nenhuma** questão jurídica relacionada a +código-fonte fechado, código-fonte oculto, blobs binários, wrappers de +código-fonte ou qualquer outro termo usado para descrever drivers do kernel +cujo código-fonte não seja disponibilizado sob a GPL. Consulte um advogado +caso tenha alguma dúvida jurídica. Sou programador e, portanto, descreverei +aqui apenas as questões técnicas (isso não significa que as questões +jurídicas sejam pouco importantes; elas são reais e você precisa estar sempre +ciente delas). + +Portanto, há dois tópicos principais: interfaces binárias do kernel e +interfaces estáveis de código-fonte do kernel. Ambos dependem um do outro, +mas discutiremos primeiro a parte referente às interfaces binárias para +deixá-la de lado. + + +Interface binária do kernel +--------------------------- + +Supondo que tivéssemos uma interface estável de código-fonte para o kernel, +uma interface binária surgiria naturalmente também, certo? Errado. Considere +os seguintes fatos sobre o kernel Linux: + + - Dependendo da versão do compilador C utilizada, diferentes estruturas de + dados do kernel terão diferentes alinhamentos e poderão até mesmo incluir + funções de maneiras distintas (por exemplo, tornando determinadas funções + inline ou não). A organização das funções individuais não é tão importante, + mas as diferenças no preenchimento das estruturas de dados são muito + importantes. + - Dependendo das opções selecionadas durante a compilação do kernel, uma + grande variedade de comportamentos pode ser assumida pelo kernel: + + - diferentes estruturas podem conter campos diferentes; + - algumas funções podem nem sequer ser implementadas (por exemplo, + determinados bloqueios são completamente eliminados durante a + compilação em kernels sem SMP); + - a memória dentro do kernel pode ser alinhada de maneiras diferentes, + dependendo das opções de compilação. + - O Linux é executado em uma grande variedade de arquiteturas de + processadores. Não há como drivers binários compilados para uma arquitetura + funcionarem corretamente em outra. + +Vários desses problemas podem ser contornados simplesmente compilando o módulo +para uma configuração específica e exata do kernel, utilizando exatamente o +mesmo compilador C empregado na compilação do kernel. Isso é suficiente caso +você queira fornecer um módulo para uma determinada versão de uma distribuição +Linux específica. Porém, multiplique essa única compilação pelo número de +distribuições Linux existentes e pelo número de versões suportadas de cada +distribuição e você rapidamente terá um pesadelo de diferentes opções de +compilação em diferentes versões. Além disso, cada versão de uma distribuição +Linux contém vários kernels, cada um ajustado para diferentes tipos de +hardware (diferentes tipos de processadores e diferentes opções). Portanto, +mesmo para uma única versão, você precisará criar várias versões do seu módulo. + +Acredite em mim: com o tempo, você enlouquecerá se tentar oferecer suporte a +esse tipo de distribuição. Aprendi isso da maneira mais difícil há muito +tempo... + +Interfaces estáveis de código-fonte do kernel +---------------------------------------------- + +Esse é um tópico um pouco mais "volátil" se você conversar com alguém que está +tentando manter atualizado, ao longo do tempo, um driver do kernel Linux que +não está na árvore principal do kernel. + +O desenvolvimento do kernel Linux é contínuo e ocorre em ritmo acelerado, +sem desacelerar. Por isso, os desenvolvedores do kernel encontram bugs nas +interfaces existentes ou descobrem maneiras melhores de fazer as coisas. +Quando isso acontece, eles corrigem as interfaces atuais para que funcionem +melhor. Nesse processo, nomes de funções podem mudar, estruturas podem crescer +ou diminuir e parâmetros de funções podem ser reformulados. Quando isso +acontece, todos os locais dentro do kernel que utilizam essa interface são +corrigidos ao mesmo tempo, garantindo que tudo continue funcionando +corretamente. + +Como exemplos específicos disso, as interfaces USB internas do kernel +passaram por pelo menos três reformulações diferentes ao longo da existência +desse subsistema. Essas reformulações foram feitas para resolver diversos +problemas: + + - Uma mudança de um modelo síncrono de fluxos de dados para um modelo + assíncrono. Isso reduziu a complexidade de vários drivers e aumentou a + taxa de transferência de todos os drivers USB, de modo que atualmente + executamos quase todos os dispositivos USB na maior velocidade possível. + - Foi feita uma mudança na maneira como os pacotes de dados eram alocados + pelos drivers USB a partir do núcleo USB, de modo que todos os drivers + passaram a precisar fornecer mais informações ao núcleo USB, corrigindo + diversos deadlocks documentados. + +Isso contrasta fortemente com vários sistemas operacionais de código fechado, +que tiveram de manter suas interfaces USB antigas ao longo do tempo. Isso +permite que novos desenvolvedores utilizem acidentalmente interfaces antigas +e façam as coisas de maneira inadequada, prejudicando a estabilidade do +sistema operacional. + +Em ambos os casos, todos os desenvolvedores concordaram que essas eram +mudanças importantes que precisavam ser feitas, e elas foram realizadas com +relativamente pouco esforço. Se o Linux tivesse de garantir a preservação de +uma interface de código-fonte estável, uma nova interface teria de ser criada, +enquanto a interface antiga e defeituosa teria de continuar sendo mantida ao +longo do tempo, resultando em trabalho adicional para os desenvolvedores USB. +Como todos os desenvolvedores USB do Linux realizam esse trabalho em seu +próprio tempo, pedir que programadores façam trabalho extra, sem nenhum +benefício e gratuitamente, não é uma possibilidade. + +Questões de segurança também são muito importantes para o Linux. Quando um +problema de segurança é encontrado, ele é corrigido em um período muito curto. +Em diversas ocasiões, isso fez com que interfaces internas do kernel fossem +reformuladas para impedir que o problema de segurança ocorresse. Quando isso +acontece, todos os drivers que utilizam essas interfaces também são corrigidos +ao mesmo tempo, garantindo que o problema de segurança seja resolvido e não +possa reaparecer acidentalmente no futuro. Se as interfaces internas não +pudessem ser alteradas, não seria possível corrigir esse tipo de problema de +segurança e garantir que ele não voltasse a ocorrer. + +As interfaces do kernel são aprimoradas ao longo do tempo. Se ninguém estiver +utilizando uma determinada interface, ela é removida. Isso garante que o +kernel permaneça o menor possível e que todas as interfaces existentes possam +ser testadas da melhor maneira possível (é praticamente impossível testar +adequadamente a validade de interfaces que não são utilizadas). + + +O que fazer +----------- + +Então, se você possui um driver do kernel Linux que não está na árvore +principal do kernel, o que você, como desenvolvedor, deve fazer? Distribuir +um driver binário para cada versão diferente do kernel em cada distribuição +é um pesadelo, e tentar acompanhar uma interface do kernel que está em +constante mudança também é uma tarefa difícil. + +Simples: coloque seu driver na árvore principal do kernel (lembre-se de que +estamos falando aqui de drivers distribuídos sob uma licença compatível com +a GPL; se seu código não se enquadra nessa categoria, boa sorte, você está +por conta própria aqui, seu parasita). Se seu driver estiver na árvore e uma +interface do kernel mudar, ele será corrigido pela própria pessoa que realizou +a alteração no kernel. Isso garante que seu driver continue sempre compilável +e funcionando ao longo do tempo, exigindo muito pouco esforço de sua parte. + +Os excelentes efeitos colaterais de ter seu driver na árvore principal do +kernel são: + + - A qualidade do driver aumentará, enquanto os custos de manutenção + (para o desenvolvedor original) diminuirão. + - Outros desenvolvedores adicionarão funcionalidades ao seu driver. + - Outras pessoas encontrarão e corrigirão bugs no seu driver. + - Outras pessoas encontrarão oportunidades de otimização no seu driver. + - Outras pessoas atualizarão o driver para você quando mudanças em + interfaces externas exigirem isso. + - O driver será automaticamente distribuído por todas as distribuições + Linux, sem que seja necessário pedir às distribuições que o adicionem. + +Como o Linux oferece suporte, "pronto para uso", a um número maior de +dispositivos diferentes do que qualquer outro sistema operacional, e oferece +suporte a esses dispositivos em mais arquiteturas de processadores diferentes +do que qualquer outro sistema operacional, esse modelo comprovado de +desenvolvimento deve estar fazendo alguma coisa certa :) + + +------ + +Agradecimentos a Randy Dunlap, Andrew Morton, David Brownell, Hanna Linder, +Robert Love e Nishanth Aravamudan pela revisão e pelos comentários sobre +este documento. diff --git a/Documentation/translations/pt_BR/process/submit-checklist.rst b/Documentation/translations/pt_BR/process/submit-checklist.rst index 003fc956832d..3e0ee38b9a72 100644 --- a/Documentation/translations/pt_BR/process/submit-checklist.rst +++ b/Documentation/translations/pt_BR/process/submit-checklist.rst @@ -8,7 +8,7 @@ Aqui estão algumas coisas básicas que os desenvolvedores devem fazer se quiserem ver suas submissões de patches de kernel aceitas mais rapidamente. Estas diretrizes vão além da documentação fornecida em -:ref:`Documentation/process/submitting-patches.rst <submittingpatches>` +:ref:`Documentation/translations/pt_BR/process/submitting-patches.rst <pt_BR_submittingpatches>` e em outros locais sobre o envio de patches para o kernel Linux. Revise seu código @@ -19,7 +19,7 @@ Revise seu código os que você usa de forma indireta. 2) Verifique o estilo geral do seu patch conforme detalhado em - :ref:`Documentation//process/coding-style.rst <codingstyle>`. + :ref:`Documentation/translations/pt_BR/process/coding-style.rst <pt_BR_codingstyle>`. 3) Todas as barreiras de memória {por exemplo, ``barrier()``, ``rmb()``, ``wmb()``} precisam de um comentário no código-fonte que explique a diff --git a/Documentation/translations/pt_BR/process/submitting-patches.rst b/Documentation/translations/pt_BR/process/submitting-patches.rst new file mode 100644 index 000000000000..aad926c17fb4 --- /dev/null +++ b/Documentation/translations/pt_BR/process/submitting-patches.rst @@ -0,0 +1,963 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _pt_BR_submittingpatches: + +Enviando patches: o guia essencial para colocar o seu código no kernel +====================================================================== + +Para uma pessoa ou empresa que deseja enviar uma mudança para o +kernel Linux, o processo pode, por vezes, ser intimidador se você não +estiver familiarizado com "o sistema". Este texto é uma coleção de sugestões +que podem aumentar muito as chances de sua mudança ser aceita. + +Este documento contém um grande número de sugestões em um formato relativamente +conciso. Para informações detalhadas sobre como funciona o processo de +desenvolvimento do kernel, consulte Documentation/process/development-process.rst. +Além disso, leia Documentation/process/submit-checklist.rst +para uma lista de itens a serem verificados antes de enviar o código. +Para patches de binding de device tree, leia +Documentation/devicetree/bindings/submitting-patches.rst. + +Esta documentação assume que você está usando o ``git`` para preparar seus +patches. Se você não está familiarizado com o ``git``, é muito recomendado que +você aprenda a usá-lo, ele tornará a sua vida como um desenvolvedor do kernel e, +em geral, muito mais fácil. + +Alguns subsistemas e árvores de mantenedores possuem informações adicionais +sobre seus fluxos de trabalho e expectativas, consulte +Documentation/process/maintainer-handbooks.rst. + +Obtenha uma árvore de código-fonte atual +---------------------------------------- + +Se você não tiver um repositório com o código-fonte atual do kernel em mãos, +use o ``git`` para obter um. Você vai querer começar com o repositório mainline, +que pode ser obtido com:: + + git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git + +Note, no entanto, que você pode não querer desenvolver diretamente na +árvore mainline. A maioria dos mantenedores de subsistemas mantém suas +próprias árvores e desejam ver os patches preparados em relação a essas árvores. +Consulte a entrada **T:** do subsistema no arquivo MAINTAINERS para encontrar +essa árvore, ou simplesmente pergunte ao mantenedor se a árvore não estiver +listada lá. + +.. _pt_BR_describe_changes: + +Descreva as suas mudanças +------------------------- + +Descreva o seu problema. Seja o seu patch uma correção de bug de uma linha ou +5000 linhas de um novo recurso, deve haver um problema subjacente que o motivou +a fazer esse trabalho. Convença o revisor de que existe um problema que vale a +pena corrigir e que faz sentido que ele leia além do primeiro parágrafo. + +Descreva o impacto visível ao usuário. Travamentos e bloqueios diretos são +bastante convincentes, mas nem todos os bugs são tão evidentes. Mesmo que o +problema tenha sido identificado durante a revisão do código, descreva o impacto +que você acredita que ele pode ter sobre os usuários. Tenha em mente que a +maioria das instalações Linux executa kernels de árvores estáveis secundárias +ou árvores específicas de fornecedores/produtos que selecionam apenas patches +específicos do upstream, então inclua qualquer coisa que possa ajudar a +direcionar sua mudança downstream: circunstâncias provocadoras, trechos do +dmesg, descrições do travamento, regressões de desempenho, picos de latência, +bloqueios, etc. + +Quantifique as otimizações e compensações. Se você afirma haver melhorias no +desempenho, consumo de memória, uso da pilha ou tamanho do binário, inclua +números que as comprovem. Mas também descreva custos que não são óbvios. +Otimizações geralmente não são gratuitas, sendo trocas entre CPU, memória e +legibilidade; ou, quando se trata de heurísticas, entre diferentes cargas de +trabalho. Descreva as desvantagens esperadas da sua otimização para que o +revisor possa pesar os custos contra os benefícios. + +Uma vez estabelecido o problema, descreva o que você está efetivamente fazendo +sobre ele, com detalhes técnicos. É importante descrever a mudança em inglês +claro para o revisor verificar que o código está se comportando como +você pretendia. + +O mantenedor agradecerá se você escrever a descrição do seu patch em uma forma +que possa ser facilmente inserida no sistema de gerenciamento de código-fonte do +Linux, o ``git``, como uma "mensagem de commit". Veja +:ref:`pt_BR_the_canonical_patch_format`. + +Resolva apenas um problema por patch. Se a sua descrição começar a ficar longa, +isso é um sinal de que você provavelmente precisa dividir o seu patch. +Consulte :ref:`pt_BR_split_changes`. + +Quando você enviar ou reenviar um patch ou uma série de patches, inclua a +descrição completa do patch e a justificativa para ele. Não diga apenas +que esta é a versão N do patch (ou série). Não espere que o mantenedor +do subsistema consulte versões anteriores do patch ou URLs de referência +para encontrar a descrição do patch e colocá-la no patch. +Ou seja, o patch (ou a série) e sua descrição devem ser autossuficientes. +Isso beneficia tanto os mantenedores quanto os revisores. Alguns revisores +provavelmente nem chegaram a receber as versões anteriores do patch. + +Descreva suas alterações no modo imperativo, por exemplo, "faça xyzzy executar +frotz" em vez de "[Este patch] faz xyzzy executar frotz" ou "[Eu] mudei xyzzy +para executar frotz", como se você estivesse dando ordens à base de código para +mudar o seu comportamento. + +Se você quiser se referir a um commit específico, não se refira apenas ao +ID SHA-1 do commit. Por favor, inclua também o resumo de uma linha do +commit, para tornar mais fácil para os revisores saberem sobre o que se trata. +Exemplo:: + + Commit e21d2170f36602ae2708 ("video: remove unnecessary + platform_set_drvdata()") removed the unnecessary + platform_set_drvdata(), but left the variable "dev" unused, + delete it. + +Você também deve ter a certeza de usar pelo menos os primeiros doze caracteres do +ID SHA-1. O repositório do kernel possui um número *muito* grande de objetos, o que torna as +colisões com IDs mais curtos uma possibilidade real. Tenha em mente que, mesmo que +não haja colisão com o seu ID de seis caracteres agora, essa condição pode +mudar daqui a cinco anos. + +Se discussões relacionadas ou qualquer outra informação de contexto por trás da mudança +puderem ser encontradas na web, adicione tags 'Link:' apontando para isso. Se o patch é o +resultado de algumas discussões anteriores na lista de e-mails ou algo documentado na +web, aponte para ele. + +Ao criar links para arquivos de listas de e-mails, de preferência use o serviço +de arquivo de mensagens lore.kernel.org. Para criar a URL do link, use o +conteúdo do cabeçalho ``Message-ID`` da mensagem, sem os colchetes angulares +circundantes. Por exemplo:: + + Link: https://lore.kernel.org/30th.anniversary.repost@klaava.Helsinki.FI + +Por favor, verifique o link para se certificar de que ele está realmente +funcionando e aponta para a mensagem relevante. + +No entanto, tente tornar a sua explicação compreensível sem recursos +externos. Além de fornecer um URL para um arquivo da lista de e-mails ou bug, +resuma os pontos relevantes da discussão que levaram ao patch conforme enviado. + +Caso o seu patch corrija um bug, use a tag 'Closes:' com um URL que referencie o +relato nos arquivos da lista de e-mails ou em um rastreador público de bugs. Por exemplo:: + + Closes: https://example.com/issues/1234 + +Alguns rastreadores de bugs têm a capacidade de fechar os problemas +automaticamente quando um commit com tal tag é aplicado. Alguns bots que monitoram as listas de +e-mails também podem rastrear tais tags e tomar certas ações. Rastreadores de bugs +privados e URLs inválidos são proibidos. + +Se o seu patch corrige um bug em um commit específico, por exemplo, você encontrou um problema usando +``git bisect``, por favor, use a tag 'Fixes:' com pelo menos os primeiros 12 +caracteres do ID SHA-1 e o resumo de uma linha. Não divida a tag em +várias linhas, as tags estão isentas da regra de "quebra de linha nas 75 colunas" para +simplificar os scripts de parsing. Por exemplo:: + + Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed") + +As seguintes configurações do ``git config`` podem ser usadas para adicionar um formato aprimorado para +exibir o estilo acima nos comandos ``git log`` ou ``git show``:: + + [core] + abbrev = 12 + [pretty] + fixes = Fixes: %h (\"%s\") + +Um exemplo de chamada:: + + $ git log -1 --pretty=fixes 54a4f0239f2e + Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed") + +.. _pt_BR_split_changes: + +Separe as suas mudanças +----------------------- + +Separe cada **mudança lógica** em um patch separado. + +Por exemplo, se as suas alterações incluírem tanto correções de bugs quanto melhorias +de desempenho para um único driver, separe essas alterações em dois +ou mais patches. Se as suas alterações incluírem uma atualização de API e um novo +driver que utiliza essa nova API, separe-os em dois patches. + +Por outro lado, se você fizer uma única alteração em vários arquivos, +agrupe essas alterações em um único patch. Assim, uma única mudança +lógica está contida em um único patch. + +O ponto a lembrar é que cada patch deve fazer uma mudança facilmente compreendida +que possa ser verificada pelos revisores. Cada patch deve ser justificável +por seus próprios méritos. + +Se um patch depender de outro patch para que uma mudança seja +completa, não tem problema. Simplesmente note **"this patch depends on patch X"** +na descrição do seu patch. + +Ao dividir a sua mudança em uma série de patches, tome um cuidado especial para +garantir que o kernel compile e seja executado adequadamente após cada patch da +série. Desenvolvedores que usam o ``git bisect`` para rastrear um problema podem acabar +dividindo a sua série de patches em qualquer ponto; eles não ficarão gratos se você +introduzir bugs no meio do processo. + +Se você não conseguir condensar o seu conjunto de patches em um conjunto menor +de patches, então publique, digamos, apenas uns 15 de cada vez e aguarde pela +revisão e integração. + + + +Verifique o estilo das suas mudanças +------------------------------------ + +Verifique o seu patch quanto a violações básicas de estilo, cujos detalhes podem ser +encontrados em Documentation/process/coding-style.rst. +Não fazer isso simplesmente desperdiça +o tempo dos revisores e fará com que o seu patch seja rejeitado, provavelmente +sem sequer ser lido. + +Uma exceção significativa é quando se move código de um arquivo para +outro -- neste caso você não deve modificar o código movido no +mesmo patch que o move. Isso delineia claramente o ato de +mover o código e as suas alterações. Isso ajuda muito a revisão das +diferenças reais e permite que as ferramentas rastreiem melhor o histórico do +próprio código. + +Verifique os seus patches com o verificador de estilo de patch antes de os submeter +(scripts/checkpatch.pl). Note, porém, que o verificador de estilo deve ser +visto como um guia, e não como um substituto para o julgamento humano. Se o seu +código parecer melhor com uma violação, provavelmente é melhor deixá-lo como está. + +O verificador emite relatórios em três níveis: + - ERROR: coisas que muito provavelmente estão erradas + - WARNING: coisas que requerem uma revisão cuidadosa + - CHECK: coisas que requerem reflexão + +Você deve ser capaz de justificar todas as violações que permanecerem no seu +patch. + +Selecione os destinatários do seu patch +--------------------------------------- + +Você deve sempre copiar o(s) mantenedor(es) e a(s) lista(s) do subsistema +apropriado(s) em qualquer patch para o código que eles mantêm; dê uma +olhada no arquivo MAINTAINERS e no histórico de revisão do código-fonte +para ver quem são esses mantenedores. O script scripts/get_maintainer.pl +pode ser muito útil nesta etapa (passe os caminhos para seus patches +como argumentos para scripts/get_maintainer.pl). Se você não conseguir +encontrar um mantenedor para o subsistema em que está trabalhando, +Andrew Morton (akpm@linux-foundation.org) serve como um mantenedor de +último recurso. + +linux-kernel@vger.kernel.org deve ser usado por padrão para todos os +patches, mas o volume dessa lista fez com que vários desenvolvedores a +ignorassem. Por favor, não envie spam para listas e pessoas não +relacionadas. + +Muitas listas relacionadas ao kernel estão hospedadas em kernel.org; +você pode encontrar uma lista delas em https://subspace.kernel.org. +Existem listas relacionadas ao kernel hospedadas em outros lugares +também, no entanto. + +Linus Torvalds é o árbitro final de todas as mudanças aceitas no +kernel do Linux. Seu endereço de e-mail é <torvalds@linux-foundation.org>. +Ele recebe muitos e-mails e, neste momento, muito poucos patches passam +por Linus diretamente, então, normalmente, você deve fazer o seu melhor +para -evitar- enviar e-mails para ele. + +Se você tiver um patch que corrija um bug de segurança explorável, +envie esse patch para security@kernel.org. Para bugs severos, um +curto embargo pode ser considerado para permitir que os distribuidores +disponibilizem o patch aos usuários; em tais casos, obviamente, o +patch não deve ser enviado a nenhuma lista pública. Veja também +Documentation/process/security-bugs.rst. + +Patches que corrigem um bug severo em um kernel já lançado devem ser +direcionados aos mantenedores stable (estáveis), colocando uma linha como esta:: + + Cc: stable@vger.kernel.org + +na área de sign-off do seu patch (note, NÃO como um destinatário de e-mail). +Você também deve ler Documentation/process/stable-kernel-rules.rst +além deste documento. + +Se as alterações afetarem as interfaces userland-kernel, +por favor, envie ao mantenedor das MAN-PAGES (como listado no arquivo MAINTAINERS) +um patch para as páginas de manual, ou pelo menos uma notificação da alteração, +para que alguma informação chegue às páginas de manual. Mudanças na API +do espaço de usuário também devem ser copiadas para linux-api@vger.kernel.org. + + +Sem MIME, sem links, sem compressão, sem anexos. Apenas texto puro +------------------------------------------------------------------ + +Linus e outros desenvolvedores do kernel precisam ser capazes de ler e +comentar as mudanças que você está enviando. É importante que um +desenvolvedor do kernel seja capaz de "citar" suas mudanças, usando +ferramentas de e-mail padrão, para que eles possam comentar em partes +específicas do seu código. + +Por esse motivo, todos os patches devem ser enviados por e-mail "inline". A +maneira mais fácil de fazer isso é com ``git send-email``, que é +fortemente recomendado. Um tutorial interativo para ``git send-email`` +está disponível em https://git-send-email.io. + +Se você optar por não usar ``git send-email``: + +.. warning:: + + Tenha cuidado com a quebra de linha do seu editor corrompendo seu patch, + se você optar por recortar e colar o seu patch. + +Não anexe o patch como um anexo MIME, comprimido ou não. +Muitos aplicativos populares de e-mail nem sempre transmitirão um +anexo MIME como texto puro, tornando impossível comentar o seu +código. Um anexo MIME também leva um pouco mais de tempo para Linus +processar, diminuindo a probabilidade da sua alteração anexada em MIME +ser aceita. + +Exceção: Se o seu cliente de e-mail estiver danificando os patches, +alguém pode pedir que você os reenvie usando MIME. + +Veja Documentation/process/email-clients.rst para dicas sobre como +configurar seu cliente de e-mail para que ele envie seus patches intocados. + +Responda aos comentários de revisão +----------------------------------- + +Seu patch quase certamente receberá comentários dos revisores sobre maneiras +pelas quais o patch pode ser melhorado, na forma de uma resposta ao seu +e-mail. Você deve responder a esses comentários; ignorar revisores é uma +boa maneira de ser ignorado em troca. Você pode simplesmente responder aos +e-mails deles para responder aos seus comentários. Comentários de revisão +ou perguntas que não levam a uma alteração no código devem quase certamente +resultar em um comentário ou entrada no changelog para que o próximo +revisor entenda melhor o que está acontecendo. + +Certifique-se de dizer aos revisores quais alterações você está fazendo e +de agradecê-los pelo tempo dedicado. A revisão de código é um processo +cansativo e demorado, e os revisores às vezes ficam mal-humorados. Mesmo +nesse caso, no entanto, responda educadamente e resolva os problemas que +eles apontaram. Ao enviar uma próxima versão, adicione um ``changelog do patch`` +à carta de apresentação (cover letter) ou aos patches individuais, +explicando a diferença em relação ao envio anterior (veja +:ref:`pt_BR_the_canonical_patch_format`). +Notifique as pessoas que comentaram no seu patch sobre as novas versões +adicionando-as à lista de CC dos patches. + +Veja Documentation/process/email-clients.rst para recomendações sobre +clientes de e-mail e etiqueta de listas de discussão. + +.. _pt_BR_interleaved_replies: + +Use respostas intercaladas e aparadas em discussões por e-mail +-------------------------------------------------------------- +O top-posting (responder no topo) é fortemente desencorajado em +discussões de desenvolvimento do kernel do Linux. Respostas +intercaladas (ou "inline") tornam as conversas muito mais fáceis de +acompanhar. Para mais detalhes, veja: +https://en.wikipedia.org/wiki/Posting_style#Interleaved_style + +Como é frequentemente citado na lista de discussão:: + + A: http://en.wikipedia.org/wiki/Top_post + Q: Onde encontro informações sobre essa coisa chamada top-posting? + A: Porque bagunça a ordem em que as pessoas normalmente leem o texto. + Q: Por que o top-posting é algo tão ruim? + A: Top-posting. + Q: Qual é a coisa mais irritante no e-mail? + +Da mesma forma, por favor, apare (corte) todas as citações +desnecessárias que não são relevantes para a sua resposta. Isso torna +as respostas mais fáceis de encontrar, e economiza tempo e espaço. Para +mais detalhes, veja: http://daringfireball.net/2007/07/on_top :: + + A: Não. + Q: Devo incluir citações após minha resposta? + +.. _pt_BR_resend_reminders: + +Não desanime - nem fique impaciente +----------------------------------- + +Depois de ter enviado a sua alteração, seja paciente e espere. Os +revisores são pessoas ocupadas e podem não chegar ao seu patch +imediatamente. + +Era uma vez, patches costumavam desaparecer no vazio sem comentários, +mas o processo de desenvolvimento funciona de forma mais suave do que +isso agora. Você deve receber comentários dentro de algumas semanas +(normalmente 2-3); se isso não acontecer, certifique-se de que você +enviou seus patches para o lugar certo. Espere por no mínimo uma +semana antes de reenviar ou dar um "ping" nos revisores - +possivelmente mais tempo durante períodos ocupados, como as janelas +de mesclagem (merge windows). + +Também não há problema em reenviar o patch ou a série de patches após +algumas semanas com a palavra "RESEND" adicionada à linha de Assunto:: + + [PATCH Vx RESEND] sub/sys: Resumo condensado do patch + +Não adicione "RESEND" quando você estiver enviando uma versão +modificada do seu patch ou série de patches - "RESEND" se aplica +apenas ao reenvio de um patch ou série de patches que não foram +modificados de forma alguma em relação ao envio anterior. + + +Inclua PATCH no Assunto +----------------------- + +Devido ao alto tráfego de e-mails para Linus e para a linux-kernel, é +uma convenção comum prefixar a sua linha de Assunto com [PATCH]. Isso +permite que Linus e outros desenvolvedores do kernel distingam +mais facilmente os patches de outras discussões por e-mail. + +O ``git send-email`` fará isso por você automaticamente. + + +Assine seu trabalho - o Certificado de Origem do Desenvolvedor +-------------------------------------------------------------- + +Para melhorar o rastreamento de quem fez o que, especialmente com patches +que podem percolar até o seu local de descanso final no kernel através de +várias camadas de mantenedores, nós introduzimos um procedimento de +"sign-off" nos patches que estão sendo enviados por e-mail. + +O sign-off é uma linha simples no final da explicação do patch, que +certifica que você o escreveu ou que de outra forma tem o direito de +repassá-lo como um patch de código aberto. As regras são bem simples: +se você pode certificar o seguinte:: + + Certificado de Origem do Desenvolvedor 1.1 + + Ao fazer uma contribuição para este projeto, eu certifico que: + + (a) A contribuição foi criada no todo ou em parte por mim e eu + tenho o direito de enviá-la sob a licença de código aberto + indicada no arquivo; ou + + (b) A contribuição baseia-se em trabalho anterior que, até onde eu + sei, é coberto por uma licença de código aberto apropriada + e eu tenho o direito, sob essa licença, de enviar esse + trabalho com modificações, tenham sido criadas no todo ou + em parte por mim, sob a mesma licença de código aberto (a menos que eu + tenha permissão para enviar sob uma licença diferente), conforme + indicado no arquivo; ou + + (c) A contribuição foi fornecida diretamente a mim por alguma outra + pessoa que certificou (a), (b) ou (c) e eu não a modifiquei. + + (d) Eu entendo e concordo que este projeto e a contribuição + são públicos e que um registro da contribuição (incluindo todas + as informações pessoais que eu envio com ela, incluindo meu + sign-off) é mantido indefinidamente e pode ser redistribuído de forma + consistente com este projeto ou com a(s) licença(s) de código + aberto envolvida(s). + +então você apenas adiciona uma linha dizendo:: + + Signed-off-by: Random J Developer <random@developer.example.org> + +usando uma identidade conhecida (desculpe, sem contribuições anônimas.) +Isso será feito para você automaticamente se você usar o ``git commit -s``. +As reversões também devem incluir "Signed-off-by". O ``git revert -s`` +faz isso por você. + +Algumas pessoas também colocam tags extras no final. Elas serão +apenas ignoradas por enquanto, mas você pode fazer isso para marcar +procedimentos internos da empresa ou apenas para apontar algum +detalhe especial sobre o sign-off. + +Quaisquer outros SoBs (Signed-off-by:'s) seguindo o SoB do autor +são de pessoas que manusearam e transportaram o patch, mas não +estiveram envolvidas no seu desenvolvimento. As cadeias de SoB devem +refletir a rota **real** que um patch percorreu à medida que foi +propagado aos mantenedores e, finalmente, para Linus, com a primeira +entrada de SoB sinalizando a autoria principal de um único autor. + + +Quando usar Acked-by:, Cc: e Co-developed-by: +--------------------------------------------- + +A tag Signed-off-by: indica que o signatário esteve envolvido no +desenvolvimento do patch, ou que ele/ela estava no caminho de +entrega do patch. + +Se uma pessoa não esteve diretamente envolvida na preparação ou manuseio de um +patch, mas deseja manifestar e registrar sua aprovação, ela pode +pedir para ter uma linha Acked-by: adicionada ao changelog do patch. + +Acked-by: destina-se a ser usado por aqueles responsáveis ou envolvidos com o +código afetado de uma forma ou de outra. Mais comumente, o mantenedor quando esse +mantenedor não contribuiu nem encaminhou o patch. + +Acked-by: também pode ser usado por outras partes interessadas, como pessoas com conhecimento de +domínio (por exemplo, o autor original do código sendo modificado), revisores +do lado do espaço de usuário para um patch uAPI do kernel ou usuários-chave de um recurso. Opcionalmente, +nestes casos, pode ser útil adicionar um "# Sufixo" para esclarecer seu significado:: + + Acked-by: The Stakeholder <stakeholder@example.org> # As primary user + +Acked-by: não é tão formal quanto Signed-off-by:. É um registro de que o avaliador +pelo menos revisou o patch e indicou aceitação. Por isso, os responsáveis pela fusão de +patches às vezes converterão manualmente um "sim, parece bom para mim" de um avaliador +em um Acked-by: (mas note que geralmente é melhor pedir um +ack explícito). + +Acked-by: também é menos formal do que Reviewed-by:. Por exemplo, mantenedores podem +usá-lo para sinalizar que estão de acordo com a inclusão de um patch, mas podem não tê-lo +revisado tão minuciosamente como se um Reviewed-by: fosse fornecido. Da mesma forma, um +usuário-chave pode não ter realizado uma revisão técnica do patch, mas ainda assim estar +satisfeito com a abordagem geral, o recurso ou a interface voltada para o usuário. + +Acked-by: não indica necessariamente o reconhecimento de todo o patch. +Por exemplo, se um patch afeta vários subsistemas e tem um Acked-by: de +um mantenedor de subsistema, isso geralmente indica o reconhecimento apenas +da parte que afeta o código desse mantenedor. O bom senso deve ser usado aqui. +Em caso de dúvida, as pessoas devem consultar a discussão original nos arquivos da +lista de discussão. Um "# Sufixo" também pode ser usado neste caso para esclarecer. + +Se uma pessoa teve a oportunidade de comentar em um patch, mas não +forneceu tais comentários, você pode opcionalmente adicionar uma tag ``Cc:`` ao patch. +Esta tag documenta que partes potencialmente interessadas foram incluídas na +discussão. Note que esta é uma de apenas três tags que você pode usar +sem a permissão explícita da pessoa nomeada (veja 'Marcar pessoas requer +permissão' abaixo para detalhes). + +Co-developed-by: afirma que o patch foi co-criado por múltiplos desenvolvedores; +é usado para dar atribuição a coautores (além do autor +atribuído pela tag From:) quando várias pessoas trabalham em um único patch. Como +Co-developed-by: denota autoria, cada Co-developed-by: deve ser imediatamente +seguido por um Signed-off-by: do coautor associado. O procedimento padrão de assinatura +se aplica, ou seja, a ordem das tags Signed-off-by: deve refletir a +história cronológica do patch na medida do possível, independentemente se +o autor for atribuído via From: ou Co-developed-by:. Notavelmente, o último +Signed-off-by: deve ser sempre o do desenvolvedor que está enviando o patch. + +Note que a tag From: é opcional quando o autor no From: também é a pessoa (e +e-mail) listada na linha From: do cabeçalho do e-mail. + +Exemplo de um patch enviado pelo autor do From::: + + <changelog> + + Co-developed-by: First Co-Author <first@coauthor.example.org> + Signed-off-by: First Co-Author <first@coauthor.example.org> + Co-developed-by: Second Co-Author <second@coauthor.example.org> + Signed-off-by: Second Co-Author <second@coauthor.example.org> + Signed-off-by: From Author <from@author.example.org> + +Exemplo de um patch enviado por um autor do Co-developed-by::: + + From: From Author <from@author.example.org> + + <changelog> + + Co-developed-by: Random Co-Author <random@coauthor.example.org> + Signed-off-by: Random Co-Author <random@coauthor.example.org> + Signed-off-by: From Author <from@author.example.org> + Co-developed-by: Submitting Co-Author <sub@coauthor.example.org> + Signed-off-by: Submitting Co-Author <sub@coauthor.example.org> + + +Usando Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: e Fixes: +--------------------------------------------------------------------- + +A tag Reported-by dá crédito às pessoas que encontram bugs e os relatam e +espera-se que isso as inspire a nos ajudar novamente no futuro. A tag destina-se a +bugs; por favor, não a use para dar crédito a solicitações de recursos. A tag deve ser +seguida por uma tag Closes: apontando para o relato, a menos que o relato não +esteja disponível na web. A tag Link: pode ser usada em vez de Closes: se o patch +corrigir uma parte do(s) problema(s) sendo relatado(s). Note que a tag Reported-by é +uma de apenas três tags que você pode usar sem a permissão explícita da +pessoa nomeada (veja 'Marcar pessoas requer permissão' abaixo para detalhes). + +Uma tag Tested-by: indica que o patch foi testado com sucesso (em +algum ambiente) pela pessoa nomeada. Esta tag informa aos mantenedores que +algum teste foi realizado, fornece um meio para localizar testadores para +patches futuros e garante crédito para os testadores. + +Reviewed-by:, por sua vez, indica que o patch foi revisado e considerado +aceitável de acordo com a Declaração do Revisor:: + + Declaração de supervisão do revisor + + Ao oferecer minha tag Reviewed-by:, eu declaro que: + + (a) Eu realizei uma revisão técnica deste patch para + avaliar sua adequação e prontidão para inclusão no + kernel mainline. + + (b) Quaisquer problemas, preocupações ou perguntas relacionadas ao patch + foram comunicadas de volta ao remetente. Eu estou satisfeito + com a resposta do remetente aos meus comentários. + + (c) Embora possa haver coisas que poderiam ser melhoradas com este + envio, eu acredito que é, neste momento, (1) uma + modificação que vale a pena para o kernel, e (2) livre de problemas + conhecidos que argumentariam contra sua inclusão. + + (d) Embora eu tenha revisado o patch e acredite que seja sólido, eu + não faço (a menos que explicitamente declarado em outro lugar) + garantias de que alcançará seu propósito + declarado ou funcionará adequadamente em qualquer situação. + +Uma tag Reviewed-by é uma declaração de opinião de que o patch é uma +modificação apropriada do kernel sem nenhum problema técnico sério +restante. Qualquer revisor interessado (que tenha feito o trabalho e seja uma +pessoa com identidade conhecida) pode oferecer uma tag Reviewed-by para um patch. Esta tag +serve para dar crédito aos revisores e para informar os mantenedores do grau de +revisão que foi feito no patch. Tags Reviewed-by:, quando fornecidas por +revisores conhecidos por entender a área de assunto e realizar revisões completas, +normalmente aumentarão a probabilidade de seu patch entrar no kernel. + +Ambas as tags Tested-by e Reviewed-by, uma vez recebidas na lista de discussão do testador +ou revisor, devem ser adicionadas pelo autor aos patches aplicáveis ao enviar as +próximas versões. No entanto, se o patch mudou substancialmente na versão +seguinte, essas tags podem não ser mais aplicáveis e, portanto, devem ser removidas. +Normalmente, a remoção das tags Acked-by, Tested-by ou Reviewed-by de alguém deve ser +mencionada no changelog do patch com uma explicação (após o separador '---'). + +Uma tag Suggested-by: indica que a ideia do patch foi sugerida pela pessoa +nomeada e garante crédito à pessoa pela ideia: se creditarmos diligentemente +nossos relatores de ideias, eles serão, com sorte, inspirados a nos ajudar novamente no +futuro. Note que esta é uma de apenas três tags que você pode usar sem +permissão explícita da pessoa nomeada (veja 'Marcar pessoas requer +permissão' abaixo para detalhes). + +Uma tag Fixes: indica que o patch corrige um bug em um commit anterior. Ela +é usada para facilitar a determinação de onde um problema se originou, o que pode ajudar +na revisão da correção de um bug. Esta tag também auxilia a equipe do kernel estável a determinar +quais versões do kernel estável devem receber sua correção. Este é o método preferido +para indicar um bug corrigido pelo patch. Veja :ref:`pt_BR_describe_changes` +para mais detalhes. + +Nota: Anexar uma tag Fixes: não subverte o processo de regras do kernel +estável, nem o requisito de enviar em Cc: para stable@vger.kernel.org em todos os patches +candidatos estáveis. Para mais informações, por favor, leia +Documentation/process/stable-kernel-rules.rst. + +Por fim, embora fornecer tags seja bem-vindo e tipicamente muito apreciado, por favor +note que os signatários (ou seja, remetentes e mantenedores) podem usar sua discrição ao +aplicar as tags oferecidas. + + +Marcar pessoas requer permissão +------------------------------- + +Tenha cuidado ao adicionar as tags mencionadas acima aos seus patches, pois todas +exceto Cc:, Reported-by: e Suggested-by: precisam de permissão explícita da +pessoa nomeada. Para essas três, a permissão implícita é suficiente se a pessoa +contribuiu para o kernel Linux usando esse nome e endereço de e-mail de acordo +com os arquivos do lore ou o histórico de commits -- e no caso de Reported-by: +e Suggested-by: tenha feito o relato ou sugestão em público. Note que o +bugzilla.kernel.org é um local público nesse sentido, mas os endereços de e-mail +usados lá são privados; portanto, não os exponha em tags, a menos que a pessoa +os tenha usado em contribuições anteriores. + +Usando Assisted-by: +------------------- + +Se você usou qualquer tipo de ferramenta avançada de codificação na criação do seu patch, +você precisa reconhecer esse uso adicionando uma tag Assisted-by. A falha em +fazer isso pode impedir a aceitação do seu trabalho. Por favor, veja +Documentation/process/coding-assistants.rst para detalhes sobre o +reconhecimento de assistentes de codificação. + + +.. _pt_BR_the_canonical_patch_format: + +O formato canônico do patch +--------------------------- + +Esta seção descreve como o próprio patch deve ser formatado. Note +que, se você tiver seus patches armazenados em um repositório ``git``, a formatação +adequada do patch pode ser obtida com ``git format-patch``. As ferramentas não podem criar +o texto necessário, no entanto, portanto, leia as instruções abaixo de qualquer maneira. + +Linha de Assunto +^^^^^^^^^^^^^^^^ + +A linha de assunto canônica do patch é:: + + Assunto: [PATCH 001/123] subsistema: frase de resumo + +O corpo canônico da mensagem do patch contém o seguinte: + + - Uma linha ``from`` especificando o autor do patch, seguida por uma linha + vazia (necessário apenas se a pessoa enviando o patch não for o autor). + + - O corpo da explicação, com quebra de linha em 75 colunas, que será + copiado para o changelog permanente para descrever este patch. + + - Uma linha vazia. + + - As linhas ``Signed-off-by:``, descritas acima, que também + irão para o changelog. + + - Uma linha de marcador contendo simplesmente ``---``. + + - Quaisquer comentários adicionais não adequados para o changelog. + + - O próprio patch (saída do ``diff``). + +O formato da linha de Assunto torna muito fácil classificar os e-mails +alfabeticamente pela linha de assunto - praticamente qualquer leitor de e-mail +suportará isso - pois, como o número de sequência é preenchido com zeros, +a classificação numérica e alfabética é a mesma. + +O ``subsystem`` no Assunto do e-mail deve identificar qual +área ou subsistema do kernel está recebendo o patch. + +A ``frase de resumo`` no Assunto do e-mail deve descrever de forma concisa +o patch que esse e-mail contém. A ``frase de resumo`` não deve ser um nome de arquivo. +Não use a mesma ``frase de resumo`` para cada patch em uma série de patches inteira (onde uma ``série +de patches`` é uma sequência ordenada de múltiplos patches relacionados). + +Tenha em mente que a ``frase de resumo`` do seu e-mail se torna um +identificador globalmente único para aquele patch. Ela se propaga por todo o caminho +até o changelog do ``git``. A ``frase de resumo`` pode ser usada posteriormente em +discussões de desenvolvedores que se referem ao patch. As pessoas vão querer +pesquisar no Google pela ``frase de resumo`` para ler a discussão sobre esse +patch. Também será a única coisa que as pessoas poderão ver rapidamente +quando, dois ou três meses depois, estiverem passando por talvez +milhares de patches usando ferramentas como ``gitk`` ou ``git log +--oneline``. + +Por essas razões, o ``resumo`` não deve ter mais de 70-75 +caracteres, e deve descrever tanto o que o patch altera, quanto +por que o patch pode ser necessário. É um desafio ser +sucinto e descritivo, mas é isso que um resumo bem escrito +deve fazer. + +A ``frase de resumo`` pode ser prefixada por tags delimitadas por colchetes +retos: "Assunto: [PATCH <tag>...] <frase de resumo>". As tags não +são consideradas parte da frase de resumo, mas descrevem como o patch +deve ser tratado. Tags comuns podem incluir um descritor de versão se +as múltiplas versões do patch tiverem sido enviadas em resposta a +comentários (ou seja, "v1, v2, v3"), ou "RFC" para indicar um pedido de +comentários. + +Se houver quatro patches em uma série de patches, os patches individuais podem +ser numerados assim: 1/4, 2/4, 3/4, 4/4. Isso garante que os desenvolvedores +entendam a ordem na qual os patches devem ser aplicados e que +eles tenham revisado ou aplicado todos os patches na série de patches. + +Aqui estão alguns bons exemplos de Assuntos:: + + Subject: [PATCH 2/5] ext2: improve scalability of bitmap searching + Subject: [PATCH v2 01/27] x86: fix eflags tracking + Subject: [PATCH v2] sub/sys: Condensed patch summary + Subject: [PATCH v2 M/N] sub/sys: Condensed patch summary + +Linha From +^^^^^^^^^^ + +A linha ``from`` deve ser a primeira linha no corpo da mensagem, +e tem a forma: + + From: Patch Author <author@example.com> + +A linha ``from`` especifica quem será creditado como o autor do +patch no changelog permanente. Se a linha ``from`` estiver faltando, +então a linha ``From:`` do cabeçalho do e-mail será usada para determinar +o autor do patch no changelog. + +O autor pode indicar sua afiliação ou o patrocinador do trabalho +adicionando o nome de uma organização às linhas ``from`` e ``SoB``, +por exemplo: + + From: Patch Author (Company) <author@example.com> + +Corpo da Explicação +^^^^^^^^^^^^^^^^^^^ + +O corpo da explicação será commitado no changelog +permanente da fonte, então deve fazer sentido para um leitor competente que já +esqueceu há muito tempo os detalhes imediatos da discussão que podem ter levado a +este patch. Incluir sintomas da falha que o patch aborda +(mensagens de log do kernel, mensagens oops, etc.) é especialmente útil para +pessoas que possam estar pesquisando nas mensagens de commit procurando pelo patch +aplicável. O texto deve ser escrito com detalhes suficientes para que, quando lido +semanas, meses ou até anos depois, possa dar ao leitor os detalhes +necessários para compreender o raciocínio do **por que** o patch foi criado. + +Se um patch corrige uma falha de compilação, pode não ser necessário incluir +_todas_ as falhas de compilação; apenas o suficiente para que seja provável que +alguém pesquisando pelo patch possa encontrá-lo. Como na ``frase de resumo``, +é importante ser tanto sucinto quanto descritivo. + +.. _pt_BR_backtraces: + +Backtraces em mensagens de commit +""""""""""""""""""""""""""""""""" + +Backtraces ajudam a documentar a cadeia de chamadas que leva a um problema. No entanto, +nem todos os backtraces são úteis. Por exemplo, as cadeias de chamadas iniciais de boot são +únicas e óbvias. Copiar a saída dmesg completa verbatim, no entanto, +adiciona informações que distraem, como timestamps, listas de módulos, dumps de +registradores e pilhas. + +Portanto, os backtraces mais úteis devem destilar as informações +relevantes do dump, o que facilita o foco no problema +real. Aqui está um exemplo de um backtrace bem aparado:: + + unchecked MSR access error: WRMSR to 0xd51 (tried to write 0x0000000000000064) + at rIP: 0xffffffffae059994 (native_write_msr+0x4/0x20) + Call Trace: + mba_wrmsr + update_domains + rdtgroup_mkdir + +Comentários +^^^^^^^^^^^ + +A linha marcadora ``---`` serve ao propósito essencial de marcar para +as ferramentas de manipulação de patches onde a mensagem do changelog termina. + +Um bom uso para os comentários adicionais após o marcador ``---`` é +para um ``diffstat``, para mostrar quais arquivos mudaram, e o número de +linhas inseridas e excluídas por arquivo. Um ``diffstat`` é especialmente útil +em patches maiores. Se você for incluir um ``diffstat`` após o +marcador ``---``, por favor, use as opções do ``diffstat`` ``-p 1 -w 70`` para que +os nomes dos arquivos sejam listados a partir do topo da árvore de código-fonte do kernel e não +usem muito espaço horizontal (cabem facilmente em 80 colunas, talvez com algum +recuo). (o ``git`` gera diffstats apropriados por padrão.) + +Outros comentários relevantes apenas para o momento ou para o mantenedor, não +adequados para o changelog permanente, também devem ir aqui. Um bom +exemplo de tais comentários podem ser ``changelogs do patch`` que descrevem +o que mudou entre as versões v1 e v2 do patch. + +Por favor, coloque esta informação **após** a linha ``---`` que separa +o changelog do restante do patch. A informação da versão não +faz parte do changelog que é commitado na árvore git. É +informação adicional para os revisores. Se for colocada acima das +tags de commit, precisará de interação manual para removê-la. Se estiver abaixo +da linha separadora, ela é automaticamente removida ao aplicar o +patch. Se disponíveis, adicionar links para as versões anteriores do patch (por exemplo, +link do arquivo lore.kernel.org) é recomendado para ajudar os revisores:: + + <commit message> + ... + Signed-off-by: Author <author@mail> + --- + V2 -> V3: Removed redundant helper function + V1 -> V2: Cleaned up coding style and addressed review comments + + v2: https://lore.kernel.org/bar + v1: https://lore.kernel.org/foo + + path/to/file | 5+++-- + ... + +Veja mais detalhes sobre o formato de patch adequado nas seguintes +referências. + + +Cabeçalhos In-Reply-To explícitos +--------------------------------- + +Pode ser útil adicionar manualmente cabeçalhos In-Reply-To: a um patch +(por exemplo, ao usar ``git send-email``) para associar o patch com +discussões relevantes anteriores, por exemplo, para vincular uma correção de bug ao e-mail com +o relatório do bug. No entanto, para uma série de múltiplos patches, geralmente é +melhor evitar usar In-Reply-To: para vincular a versões mais antigas da +série. Desta forma, múltiplas versões do patch não se tornam uma +floresta incontrolável de referências nos clientes de e-mail. Se um link for +útil, você pode usar o redirecionador https://lore.kernel.org/ (por exemplo, no +texto do e-mail de capa) para vincular a uma versão anterior da série de patches. + + +Informações sobre a árvore base +------------------------------- + +Quando outros desenvolvedores recebem seus patches e iniciam o processo de revisão, +é absolutamente necessário que eles saibam qual é o commit/branch +base no qual seu trabalho se aplica, considerando a enorme quantidade de +árvores de mantenedores presentes hoje em dia. Note novamente a entrada **T:** no +arquivo MAINTAINERS explicado acima. + +Isso é ainda mais importante para processos automatizados de CI que tentam +executar uma série de testes a fim de estabelecer a qualidade da sua +submissão antes que o mantenedor inicie a revisão. + +Se você estiver usando ``git format-patch`` para gerar seus patches, você pode +incluir automaticamente as informações da árvore base em sua submissão ao +usar a flag ``--base``. A maneira mais fácil e conveniente de usar +esta opção é com branches de tópicos (topical branches):: + + $ git checkout -t -b my-topical-branch master + Branch 'my-topical-branch' set up to track local branch 'master'. + Switched to a new branch 'my-topical-branch' + + [perform your edits and commits] + + $ git format-patch --base=auto --cover-letter -o outgoing/ master + outgoing/0000-cover-letter.patch + outgoing/0001-First-Commit.patch + outgoing/... + +Quando você abrir ``outgoing/0000-cover-letter.patch`` para edição, você +notará que ele terá o trailer ``base-commit:`` bem no +final, o qual fornece ao revisor e às ferramentas de CI informações suficientes +para realizar o ``git am`` adequadamente sem se preocupar com conflitos:: + + $ git checkout -b patch-review [base-commit-id] + Switched to a new branch 'patch-review' + $ git am patches.mbox + Applying: First Commit + Applying: ... + +Por favor, veja ``man git-format-patch`` para mais informações sobre esta +opção. + +.. note:: + + A funcionalidade ``--base`` foi introduzida no git versão 2.9.0. + +Se você não estiver usando git para formatar seus patches, você ainda pode incluir +o mesmo trailer ``base-commit`` para indicar o hash do commit da árvore +na qual seu trabalho se baseia. Você deve adicioná-lo na cover +letter (carta de apresentação) ou no primeiro patch da série e ele deve ser colocado +abaixo da linha ``---`` ou bem no final de todo o outro +conteúdo, logo antes da sua assinatura de e-mail. + +Certifique-se de que o commit base está em uma árvore oficial de mantenedor/mainline +e não em alguma árvore interna acessível apenas por você - caso contrário seria +inútil. + +Ferramentas +----------- + +Muitos dos aspectos técnicos deste processo podem ser automatizados usando +b4, documentado em <https://b4.docs.kernel.org/en/latest/>. Isso pode +ajudar com coisas como rastreamento de dependências, execução do checkpatch e +com a formatação e o envio de e-mails. + +Referências +----------- + +Andrew Morton, "The perfect patch" (tpp). + <https://www.ozlabs.org/~akpm/stuff/tpp.txt> + +Jeff Garzik, "Linux kernel patch submission format". + <https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html> + +Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". + <http://www.kroah.com/log/linux/maintainer.html> + + <http://www.kroah.com/log/linux/maintainer-02.html> + + <http://www.kroah.com/log/linux/maintainer-03.html> + + <http://www.kroah.com/log/linux/maintainer-04.html> + + <http://www.kroah.com/log/linux/maintainer-05.html> + + <http://www.kroah.com/log/linux/maintainer-06.html> + +Kernel Documentation/process/coding-style.rst + +Linus Torvalds's mail on the canonical patch format: + <https://lore.kernel.org/r/Pine.LNX.4.58.0504071023190.28951@ppc970.osdl.org> + +Andi Kleen, "On submitting kernel patches" + Some strategies to get difficult or controversial changes in. + + http://halobates.de/on-submitting-patches.pdf diff --git a/Documentation/translations/pt_BR/process/volatile-considered-harmful.rst b/Documentation/translations/pt_BR/process/volatile-considered-harmful.rst new file mode 100644 index 000000000000..b8774c0bae77 --- /dev/null +++ b/Documentation/translations/pt_BR/process/volatile-considered-harmful.rst @@ -0,0 +1,130 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Por que a classe de tipo "volatile" não deve ser usada +-------------------------------------------------------- + +Programadores C frequentemente interpretam volatile como uma indicação de +que uma variável pode ser alterada fora da thread de execução atual; como +resultado, às vezes são tentados a usá-la no código do kernel quando +estruturas de dados compartilhadas estão sendo utilizadas. Em outras +palavras, há quem trate tipos volatile como uma espécie de variável +atômica simplificada, mas não são. O uso de volatile no código do +kernel quase nunca é correto; este documento explica o porquê. + +O ponto-chave a entender sobre volatile é que seu propósito é suprimir +otimizações, o que quase nunca é o que realmente se deseja fazer. No kernel, +é necessário proteger estruturas de dados compartilhadas contra acessos +concorrentes indesejados, o que é uma tarefa bastante diferente. O processo +de proteção contra concorrência indesejada também evita, de forma mais +eficiente, quase todos os problemas relacionados a otimizações. + +Assim como volatile, as primitivas do kernel que tornam seguro o acesso +concorrente a dados (spinlocks, mutexes, barreiras de memória etc.) são +projetadas para evitar otimizações indesejadas. Se forem usadas +corretamente, também não haverá necessidade de usar volatile. Se +volatile ainda for necessário, quase certamente há algum bug no código. +Em código de kernel corretamente escrito, volatile só serve para deixar +as coisas mais lentas. + +Considere um bloco típico de código do kernel:: + + spin_lock(&the_lock); + do_something_on(&shared_data); + do_something_else_with(&shared_data); + spin_unlock(&the_lock); + +Se todo o código seguir as regras de bloqueio, o valor de shared_data não +poderá mudar inesperadamente enquanto the_lock estiver mantido. Qualquer +outro código que queira manipular esses dados estará aguardando o bloqueio. +As primitivas de spinlock atuam como barreiras de memória (são escritas +explicitamente para isso), o que significa que os acessos aos dados não +serão otimizados de forma a atravessar essas barreiras. Assim, o compilador +até pode achar que sabe qual será o valor de shared_data, mas a chamada a +spin_lock(), por atuar como barreira de memória, o forçará a esquecer tudo +o que sabia. Não haverá problemas de otimização nos acessos a esses dados. + +Se shared_data fosse declarada volatile, o bloqueio ainda seria +necessário. No entanto, o compilador também seria impedido de otimizar o +acesso a shared_data _dentro_ da seção crítica, justamente quando sabemos +que ninguém mais pode estar manipulando esses dados. Enquanto o bloqueio +estiver mantido, shared_data não é volatile. Ao lidar com dados +compartilhados, um bloqueio adequado torna volatile desnecessário e +potencialmente prejudicial. + +A classe de armazenamento volatile foi originalmente concebida para +registradores de E/S mapeados em memória. No kernel, os acessos a esses +registradores também devem ser protegidos por bloqueios, mas também não se +deseja que o compilador "otimize" esses acessos dentro de uma seção crítica. +Contudo, no kernel, os acessos à memória de E/S são sempre feitos por meio de +funções de acesso; acessar diretamente a memória de E/S via ponteiros é +desencorajado e não funciona em todas as arquiteturas. Essas funções de +acesso são implementadas de modo a impedir otimizações indesejadas e, +portanto, mais uma vez, volatile é desnecessário. + +Outra situação em que se pode ser tentado a usar volatile é quando o +processador fica em espera ocupada pelo valor de uma variável. A forma +correta de realizar essa espera ocupada é:: + + while (my_variable != what_i_want) + cpu_relax(); + +A chamada a cpu_relax() pode reduzir o consumo de energia da CPU ou ceder +recursos a um processador lógico gêmeo hyperthreaded; ela também atua +como barreira para o compilador e, portanto, mais uma vez, volatile é +desnecessário. Naturalmente, a espera ocupada já é, por si só, uma prática +geralmente antissocial. + +Ainda existem algumas situações raras em que volatile faz sentido no +kernel: + + - As funções de acesso mencionadas acima podem usar volatile em + arquiteturas nas quais o acesso direto à memória de E/S funciona. + Essencialmente, cada chamada a uma função de acesso torna-se uma + pequena seção crítica por si só e garante que o acesso ocorra conforme + esperado pelo programador. + - Código assembly inline que modifica memória, mas não tem outros + efeitos colaterais visíveis, corre o risco de ser removido pelo GCC. + Adicionar a palavra-chave volatile às instruções asm impede essa + remoção. + - A variável jiffies é especial, pois pode ter um valor diferente a cada + vez que é referenciada, mas pode ser lida sem qualquer bloqueio + especial. Portanto, jiffies pode ser volatile, mas a adição de + outras variáveis desse tipo é fortemente desencorajada. Nesse + sentido, jiffies é considerada um problema de "legado idiota" (nas + palavras de Linus); corrigi-la daria mais trabalho do que valeria a + pena. + - Ponteiros para estruturas de dados em memória coerente que possam ser + modificadas por dispositivos de E/S podem, às vezes, ser + legitimamente volatile. Um buffer circular usado por um adaptador + de rede, no qual esse adaptador altera ponteiros para indicar quais + descritores já foram processados, é um exemplo desse tipo de + situação. + +Na maior parte do código, nenhuma das justificativas acima para o uso de +volatile se aplica. Como resultado, o uso de volatile provavelmente +será considerado um bug e fará com que o código seja submetido a uma análise +mais rigorosa. Desenvolvedores que se sintam tentados a usar volatile devem +dar um passo atrás e pensar no que realmente estão tentando alcançar. + +Patches para remover variáveis volatile são, em geral, bem-vindos, desde +que venham acompanhados de uma justificativa que demonstre que as questões +de concorrência foram devidamente analisadas. + + +Referências +=========== + +[1] https://lwn.net/Articles/233481/ + +[2] https://lwn.net/Articles/233482/ + +Créditos +======== + +Motivação original e pesquisa por Randy Dunlap + +Escrito por Jonathan Corbet + +Melhorias a partir de comentários de Satyam Sharma, Johannes Stezenbach, +Jesper Juhl, Heikki Orsila, H. Peter Anvin, Philipp Hahn e Stefan +Richter. |