[PATCH 00/10] docs/translations/pt_BR: admin-guide: add multiple translations

[PATCH 00/10] docs/translations/pt_BR: admin-guide: add multiple translations

[Daniel Pereira]

This series adds Portuguese (pt_BR) translations for several documents
in Documentation/admin-guide/, continuing the effort to expand the
Brazilian Portuguese documentation in the Linux kernel:

- features.rst
- sysfs-rules.rst
- sysctl/index.rst
- cputopology.rst
- hw-vuln/index.rst
- LSM/index.rst
- perf-security.rst
- bootconfig.rst
- kernel-parameters.rst
- efi-stub.rst

All documents were translated following the original documentation
closely and keeping formatting, Sphinx directives and code blocks
intact. The admin-guide/index.rst was updated alongside each translation,
moving translated documents from Todolist into appropriate toctrees.
All patches have been validated with checkpatch.pl and verified with
'make htmldocs'.


Daniel Pereira (10):
  docs/translations/pt_BR: admin-guide: add features.rst
  docs/translations/pt_BR: admin-guide: add sysfs-rules.rst
  docs/translations/pt_BR: admin-guide: add sysctl/index.rst
  docs/translations/pt_BR: admin-guide: add cputopology.rst
  docs/translations/pt_BR: admin-guide: add hw-vuln/index.rst
  docs/translations/pt_BR: admin-guide: add LSM/index.rst
  docs/translations/pt_BR: admin-guide: add perf-security.rst
  docs/translations/pt_BR: admin-guide: add bootconfig.rst
  docs/translations/pt_BR: admin-guide: add kernel-parameters.rst
  docs/translations/pt_BR: admin-guide: add efi-stub.rst

 .../pt_BR/admin-guide/LSM/index.rst           |  53 +++
 .../pt_BR/admin-guide/bootconfig.rst          | 423 ++++++++++++++++++
 .../pt_BR/admin-guide/cputopology.rst         | 105 +++++
 .../pt_BR/admin-guide/efi-stub.rst            | 102 +++++
 .../pt_BR/admin-guide/features.rst            |   3 +
 .../pt_BR/admin-guide/hw-vuln/index.rst       |  30 ++
 .../translations/pt_BR/admin-guide/index.rst  |  34 +-
 .../pt_BR/admin-guide/kernel-parameters.rst   | 134 ++++++
 .../pt_BR/admin-guide/perf-security.rst       | 328 ++++++++++++++
 .../pt_BR/admin-guide/sysctl/index.rst        | 108 +++++
 .../pt_BR/admin-guide/sysfs-rules.rst         | 195 ++++++++
 11 files changed, 1501 insertions(+), 14 deletions(-)
 create mode 100644 Documentation/translations/pt_BR/admin-guide/LSM/index.rst
 create mode 100644 Documentation/translations/pt_BR/admin-guide/bootconfig.rst
 create mode 100644 Documentation/translations/pt_BR/admin-guide/cputopology.rst
 create mode 100644 Documentation/translations/pt_BR/admin-guide/efi-stub.rst
 create mode 100644 Documentation/translations/pt_BR/admin-guide/features.rst
 create mode 100644 Documentation/translations/pt_BR/admin-guide/hw-vuln/index.rst
 create mode 100644 Documentation/translations/pt_BR/admin-guide/kernel-parameters.rst
 create mode 100644 Documentation/translations/pt_BR/admin-guide/perf-security.rst
 create mode 100644 Documentation/translations/pt_BR/admin-guide/sysctl/index.rst
 create mode 100644 Documentation/translations/pt_BR/admin-guide/sysfs-rules.rst

-- 
2.47.3

[PATCH 01/10] docs/translations/pt_BR: admin-guide: add features.rst

[Daniel Pereira]

Add features.rst and update admin-guide/index.rst.

Signed-off-by: Daniel Pereira <danielmaraboo@gmail.com>
---
 Documentation/translations/pt_BR/admin-guide/features.rst | 3 +++
 Documentation/translations/pt_BR/admin-guide/index.rst    | 5 +----
 2 files changed, 4 insertions(+), 4 deletions(-)
 create mode 100644 Documentation/translations/pt_BR/admin-guide/features.rst

diff --git a/Documentation/translations/pt_BR/admin-guide/features.rst b/Documentation/translations/pt_BR/admin-guide/features.rst
new file mode 100644
index 000000000..7651eca38
--- /dev/null
+++ b/Documentation/translations/pt_BR/admin-guide/features.rst
@@ -0,0 +1,3 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. kernel-feat:: features
diff --git a/Documentation/translations/pt_BR/admin-guide/index.rst b/Documentation/translations/pt_BR/admin-guide/index.rst
index 471b76f00..2db14d3b4 100644
--- a/Documentation/translations/pt_BR/admin-guide/index.rst
+++ b/Documentation/translations/pt_BR/admin-guide/index.rst
@@ -26,10 +26,7 @@ etc.
 
    README
    devices
-
-Todolist:
-
-*   features
+   features
 
 Uma grande parte da interface administrativa do kernel são os sistemas de
 arquivos virtuais /proc e sysfs; estes documentos descrevem como interagir
-- 
2.47.3

[PATCH 02/10] docs/translations/pt_BR: admin-guide: add sysfs-rules.rst

[Daniel Pereira]

Add translation of sysfs-rules.rst to Portuguese and update
admin-guide/index.rst.

Signed-off-by: Daniel Pereira <danielmaraboo@gmail.com>
---
 .../translations/pt_BR/admin-guide/index.rst  |   6 +-
 .../pt_BR/admin-guide/sysfs-rules.rst         | 195 ++++++++++++++++++
 2 files changed, 200 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/translations/pt_BR/admin-guide/sysfs-rules.rst

diff --git a/Documentation/translations/pt_BR/admin-guide/index.rst b/Documentation/translations/pt_BR/admin-guide/index.rst
index 2db14d3b4..90f536bdb 100644
--- a/Documentation/translations/pt_BR/admin-guide/index.rst
+++ b/Documentation/translations/pt_BR/admin-guide/index.rst
@@ -32,9 +32,13 @@ Uma grande parte da interface administrativa do kernel são os sistemas de
 arquivos virtuais /proc e sysfs; estes documentos descrevem como interagir
 com eles.
 
+.. toctree::
+   :maxdepth: 1
+
+   sysfs-rules
+
 Todolist:
 
-*   sysfs-rules
 *   sysctl/index
 *   cputopology
 *   abi
diff --git a/Documentation/translations/pt_BR/admin-guide/sysfs-rules.rst b/Documentation/translations/pt_BR/admin-guide/sysfs-rules.rst
new file mode 100644
index 000000000..97459a9a0
--- /dev/null
+++ b/Documentation/translations/pt_BR/admin-guide/sysfs-rules.rst
@@ -0,0 +1,195 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+Regras sobre como acessar informações no sysfs
+==============================================
+
+O sysfs exportado pelo kernel expõe detalhes internos de implementação do
+kernel e depende de estruturas e do leiaute internos do kernel. Há um consenso
+entre os desenvolvedores do kernel de que o kernel Linux não fornece uma API
+interna estável. Portanto, existem aspectos da interface do sysfs que podem
+não ser estáveis entre lançamentos do kernel.
+
+Para minimizar o risco de quebrar os usuários do sysfs — que, na maioria dos
+casos, são aplicações de espaço de usuário de baixo nível — a cada novo
+lançamento do kernel, os usuários do sysfs devem seguir algumas regras para usar
+uma forma o mais abstrata possível de acessar esse sistema de arquivos. Os
+programas udev e HAL atuais já implementam isso, e os usuários são incentivados
+a se conectar, se possível, às abstrações que esses programas fornecem em vez de
+acessar o sysfs diretamente.
+
+Mas, se você realmente quer ou precisa acessar o sysfs diretamente, siga as
+seguintes regras e, assim, seus programas deverão funcionar com versões
+futuras da interface do sysfs.
+
+- Não use a libsysfs
+    Ela faz suposições sobre o sysfs que não são verdadeiras. Sua API não
+    oferece nenhuma abstração; ela expõe todos os detalhes de implementação do
+    driver-core do kernel em sua própria API. Portanto, ela não é melhor do que
+    ler diretórios e abrir os próprios arquivos.
+    Além disso, ela não é mantida ativamente no sentido de refletir o
+    desenvolvimento atual do kernel. O objetivo de fornecer uma interface
+    estável para o sysfs falhou; ela causa mais problemas do que resolve. Ela
+    viola muitas das regras deste documento.
+
+- sysfs está sempre em ``/sys``
+    Analisar ``/proc/mounts`` é perda de tempo. Outros pontos de montagem são um
+    bug de configuração do sistema que você não deve tentar contornar. Para
+    casos de teste, talvez ofereça suporte a uma variável de ambiente
+    ``SYSFS_PATH`` para sobrescrever o comportamento da aplicação, mas nunca
+    tente procurar pelo sysfs. Nunca tente montá-lo, a menos que você seja um
+    script de inicialização inicial (early boot).
+
+- Dispositivos são apenas "dispositivos"
+    Não existe algo como dispositivos de classe, de barramento, físicos,
+    interfaces e afins com os quais você possa contar no espaço de usuário.
+    Tudo é simplesmente um "dispositivo". Tipos como classe, barramento,
+    físico... são apenas detalhes de implementação do kernel que não devem ser
+    esperados por aplicações que procuram dispositivos no sysfs.
+
+    As propriedades de um dispositivo são:
+
+    - devpath (``/devices/pci0000:00/0000:00:1d.1/usb2/2-2/2-2:1.0``)
+
+      - idêntico ao valor de DEVPATH no evento enviado pelo kernel na criação e
+        remoção do dispositivo
+      - a chave única para o dispositivo naquele momento
+      - o caminho do kernel para o diretório do dispositivo sem o ``/sys`` inicial,
+        e sempre começando com uma barra
+      - todos os elementos de um devpath devem ser diretórios reais. Links
+        simbólicos apontando para /sys/devices devem ser sempre resolvidos para o
+        seu alvo real e o caminho do alvo deve ser usado para acessar o dispositivo.
+        Dessa forma, o devpath para o dispositivo corresponde ao devpath do kernel
+        usado no momento do evento.
+      - usar ou expor valores de symlinks como elementos em uma string de devpath
+        é um bug na aplicação
+
+    - nome do kernel (``sda``, ``tty``, ``0000:00:1f.2``, ...)
+
+      - um nome de diretório, idêntico ao último elemento do devpath
+      - as aplicações precisam lidar com espaços e caracteres como ``!`` no
+        nome
+
+    - subsistema (``block``, ``tty``, ``pci``, ...)
+
+      - string simples, nunca um caminho ou um link
+      - recuperado através da leitura do link "subsystem" e usando apenas o
+        último elemento do caminho de destino
+
+    - driver (``tg3``, ``ata_piix``, ``uhci_hcd``)
+
+      - uma string simples, que pode conter espaços, nunca um caminho ou um
+        link
+      - é recuperado pela leitura do link "driver" e usando apenas o último
+        elemento do caminho de destino
+      - dispositivos que não possuem o link "driver" simplesmente não possuem um
+        driver; copiar o valor do driver no contexto de um dispositivo filho é
+        um bug na aplicação
+
+    - atributos
+
+      - os arquivos no diretório do dispositivo ou arquivos abaixo de subdiretórios
+        do mesmo diretório de dispositivo
+      - acessar atributos alcançados por um symlink apontando para outro dispositivo,
+        como o link "device", é um bug na aplicação
+
+    Tudo o mais é apenas um detalhe de implementação do driver-core do kernel
+    que não deve ser presumido como estável entre lançamentos do kernel.
+
+- Propriedades de dispositivos pais nunca pertencem a um dispositivo filho.
+    Sempre olhe para os próprios dispositivos pais para determinar as propriedades
+    de contexto do dispositivo. Se o dispositivo ``eth0`` ou ``sda`` não tiver
+    um link "driver", então esse dispositivo não possui um driver. Seu valor é vazio.
+    Nunca copie nenhuma propriedade do dispositivo pai para um dispositivo filho.
+    As propriedades do dispositivo pai podem mudar dinamicamente sem qualquer aviso
+    para o dispositivo filho.
+
+- Hierarquia em uma única árvore de dispositivos
+    Há apenas um lugar válido no sysfs onde a hierarquia pode ser examinada
+    e este é abaixo de: ``/sys/devices.``
+    Está planejado que todos os diretórios de dispositivos terminarão na árvore
+    abaixo deste diretório.
+
+- Classificação por subsistema
+    Atualmente, existem três locais para classificação de dispositivos:
+    ``/sys/block,`` ``/sys/class`` e ``/sys/bus.`` Está planejado que estes não
+    conterão diretórios de dispositivos em si, mas apenas listas planas de
+    symlinks apontando para a árvore unificada ``/sys/devices``.
+    Todos os três locais têm regras completamente diferentes sobre como acessar
+    informações de dispositivos. Está planejado fundir todos os três diretórios de
+    classificação em um único local em ``/sys/subsystem``, seguindo o leiaute dos
+    diretórios de barramentos. Todos os barramentos e classes, incluindo o
+    subsistema de blocos convertido, aparecerão lá.
+    Os dispositivos pertencentes a um subsistema criarão um symlink no diretório
+    "devices" em ``/sys/subsystem/<name>/devices``,
+
+    Se ``/sys/subsystem`` existir, ``/sys/bus``, ``/sys/class`` e ``/sys/block``
+    podem ser ignorados. Se ele não existir, você sempre terá que varrer todos os
+    três locais, já que o kernel é livre para mover um subsistema de um local para
+    o outro, desde que os dispositivos ainda sejam acessíveis pelo mesmo nome de
+    subsistema.
+
+    Presumir que ``/sys/class/<subsystem>`` e ``/sys/bus/<subsystem>``, ou
+    ``/sys/block`` e ``/sys/class/block`` não são intercambiáveis é um bug na
+    aplicação.
+
+- Bloco
+    O subsistema de blocos convertido em ``/sys/class/block`` ou
+    ``/sys/subsystem/block`` conterá os links para discos e partições no mesmo
+    nível, nunca em uma hierarquia. Presumir que o subsistema de blocos contém
+    apenas discos e não dispositivos de partição na mesma lista plana é um bug
+    na aplicação.
+
+- Link "device" e links <subsystem>:<kernel name>
+    Nunca dependa do link "device". O link "device" é uma solução alternativa
+    para o leiaute antigo, onde dispositivos de classe não são criados em
+    ``/sys/devices/`` como os dispositivos de barramento. Se a resolução de links
+    de um diretório de dispositivo não terminar em ``/sys/devices/``, você pode
+    usar o link "device" para encontrar os dispositivos pais em ``/sys/devices/``;
+    esse é o único uso válido do link "device"; ele nunca deve aparecer em nenhum
+    caminho como um elemento. Presumir a existência do link "device" para um
+    dispositivo em ``/sys/devices/`` é um bug na aplicação.
+    Acessar ``/sys/class/net/eth0/device`` é um bug na aplicação.
+
+    Nunca dependa dos links específicos de classe de volta para o diretório
+    ``/sys/class``. Esses links também são uma solução paliativa para o erro de
+    projeto no qual dispositivos de classe não são criados em ``/sys/devices.``
+    Se um diretório de dispositivo não contiver diretórios para dispositivos
+    filhos, esses links podem ser usados para encontrar os dispositivos filhos em
+    ``/sys/class.`` Esse é o único uso válido desses links; eles nunca devem
+    aparecer em nenhum caminho como um elemento. Presumir a existência desses links
+    para dispositivos que são diretórios reais de dispositivos filhos na árvore
+    ``/sys/devices`` é um bug na aplicação.
+
+    Está planejado remover todos esses links quando todos os diretórios de
+    dispositivos de classe residirem em ``/sys/devices.``
+
+- A posição dos dispositivos ao longo da cadeia de dispositivos pode mudar.
+    Nunca dependa de uma posição específica do dispositivo pai no devpath,
+    ou da cadeia de dispositivos pais. O kernel é livre para inserir dispositivos
+    na cadeia. Você deve sempre requisitar o dispositivo pai que procura pelo
+    valor do seu subsistema. Você precisa percorrer a cadeia para cima até
+    encontrar o dispositivo correspondente ao subsistema esperado. Depender de
+    uma posição específica de um dispositivo pai ou expor caminhos relativos
+    usando ``../`` para acessar a cadeia de pais é um bug na aplicação.
+
+- Ao ler e gravar arquivos de atributos de dispositivo do sysfs, evite a dependência
+    de códigos de erro específicos sempre que possível. Isso minimiza o acoplamento
+    com a implementação do tratamento de erros dentro do kernel.
+
+    Em geral, falhas ao ler ou gravar atributos de dispositivos no sysfs devem
+    propagar erros sempre que possível. Erros comuns incluem, mas não estão
+    limitados a:
+
+	``-EIO``: A operação de leitura ou gravação não é suportada, tipicamente
+	retornada pelo próprio sistema sysfs se o ponteiro de leitura ou gravação
+	for ``NULL``.
+
+	``-ENXIO``: A operação de leitura ou gravação falhou
+
+    Os códigos de erro não serão alterados sem um bom motivo, e caso uma alteração
+    nos códigos de erro resulte em quebra no espaço de usuário, ela será corrigida,
+    ou a alteração causadora será revertida.
+
+    As aplicações do espaço de usuário podem, no entanto, esperar que o formato e
+    o conteúdo dos arquivos de atributos permaneçam consistentes na ausência de uma
+    mudança no atributo de versão no contexto de um determinado atributo.
-- 
2.47.3

[PATCH 03/10] docs/translations/pt_BR: admin-guide: add sysctl/index.rst

[Daniel Pereira]

Add translation of sysctl/index.rst to Portuguese and update
admin-guide/index.rst.

Signed-off-by: Daniel Pereira <danielmaraboo@gmail.com>
---
 .../translations/pt_BR/admin-guide/index.rst  |   2 +-
 .../pt_BR/admin-guide/sysctl/index.rst        | 108 ++++++++++++++++++
 2 files changed, 109 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/translations/pt_BR/admin-guide/sysctl/index.rst

diff --git a/Documentation/translations/pt_BR/admin-guide/index.rst b/Documentation/translations/pt_BR/admin-guide/index.rst
index 90f536bdb..878a88d71 100644
--- a/Documentation/translations/pt_BR/admin-guide/index.rst
+++ b/Documentation/translations/pt_BR/admin-guide/index.rst
@@ -36,10 +36,10 @@ com eles.
    :maxdepth: 1
 
    sysfs-rules
+   sysctl/index
 
 Todolist:
 
-*   sysctl/index
 *   cputopology
 *   abi
 
diff --git a/Documentation/translations/pt_BR/admin-guide/sysctl/index.rst b/Documentation/translations/pt_BR/admin-guide/sysctl/index.rst
new file mode 100644
index 000000000..dd52a1522
--- /dev/null
+++ b/Documentation/translations/pt_BR/admin-guide/sysctl/index.rst
@@ -0,0 +1,108 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===========================
+Documentação para /proc/sys
+===========================
+
+Copyright (c) 1998, 1999,  Rik van Riel <riel@nl.linux.org>
+
+------------------------------------------------------------------------------
+
+'Por que', ouço você perguntar, 'alguém iria sequer _querer_ documentação
+para esses arquivos sysctl? Se alguém realmente precisa, está tudo no
+código-fonte...'
+
+Bem, esta documentação foi escrita porque algumas pessoas ou não sabem
+que precisam ajustar algo, ou porque não têm tempo ou conhecimento
+para ler o código-fonte.
+
+Além disso, os programadores que construíram o sysctl o fizeram para
+ser realmente utilizado, e não apenas pela diversão de programá-lo :-)
+
+------------------------------------------------------------------------------
+
+Aviso legal:
+
+Como de costume, há duas coisas principais a se considerar:
+
+1. você recebe pelo que paga
+2. é de graça
+
+As consequências são que eu não garanto a exatidão deste
+documento e, se você vier reclamar comigo sobre como você bagunçou seu
+sistema por causa de uma documentação incorreta, não sentirei pena de você.
+Eu posso até rir de você...
+
+Mas é claro, se você _realmente_ conseguir bagunçar seu sistema usando
+apenas as opções de sysctl utilizadas neste arquivo, eu gostaria de saber
+disso. Não apenas para dar boas risadas, mas também para ter certeza de que
+você é a última pessoa lendo o manual (RTFM) a fazer essa besteira.
+
+Em resumo, envie suas sugestões, correções e/ou histórias de terror
+por e-mail para: <riel@nl.linux.org>
+
+Rik van Riel.
+
+--------------------------------------------------------------
+
+Introdução
+==========
+
+O sysctl é um meio de configurar determinados aspectos do kernel
+em tempo de execução, e o diretório /proc/sys/ existe para que você
+nem precise de ferramentas especiais para fazer isso!
+Na verdade, são necessárias apenas quatro coisas para usar esses recursos
+de configuração:
+
+- um sistema Linux em execução
+- acesso root
+- bom senso (isso é especialmente difícil de encontrar hoje em dia)
+- conhecimento sobre o que todos esses valores significam
+
+Como um rápido 'ls /proc/sys' mostrará, o diretório consiste em
+vários subdiretórios (dependentes de arquitetura?). Cada subdiretório
+trata principalmente de uma parte do kernel, permitindo que você faça
+a configuração parte por parte, ou apenas algumas 'modificações temáticas'.
+
+Esta documentação é sobre:
+
+=============== ===============================================================
+abi/		domínios de execução e personalidades
+<$ARCH>		controles de ajuste para várias arquiteturas de CPU (ex.: csky, s390)
+crypto/		subsistema criptográfico
+debug/		recursos de depuração
+dev/		informações específicas de dispositivos (ex.: dev/cdrom/info)
+fs/		sistemas de arquivos específicos
+		ajustes de manipuladores de arquivos (filehandle), inode, dentry e cotas
+		binfmt_misc <Documentation/admin-guide/binfmt-misc.rst>
+kernel/		informações globais / ajustes do kernel
+		coisas diversas
+		alguns controles específicos de arquitetura
+		coisas de segurança (LSM)
+net/		coisas de rede; para documentação consulte:
+		<Documentation/networking/>
+proc/		<vazio>
+sunrpc/		SUN Remote Procedure Call (NFS)
+user/		limites por namespace de usuário
+vm/		ajustes de gerenciamento de memória
+		gerenciamento de buffers e cache
+xen/		controles do hipervisor Xen
+=============== ===============================================================
+
+Estes são os subdiretórios que tenho no meu sistema ou que foram descobertos
+pesquisando pelo código-fonte. Pode haver mais ou outros subdiretórios em
+outra configuração. Se você encontrar outro diretório, eu realmente gostaria de
+saber sobre ele :-)
+
+Todolist:
+
+*   abi
+*   crypto
+*   debug
+*   fs
+*   kernel
+*   net
+*   sunrpc
+*   user
+*   vm
+*   xen
-- 
2.47.3

[PATCH 04/10] docs/translations/pt_BR: admin-guide: add cputopology.rst

[Daniel Pereira]

Add translation of cputopology.rst to Portuguese and update
admin-guide/index.rst.

Signed-off-by: Daniel Pereira <danielmaraboo@gmail.com>
---
 .../pt_BR/admin-guide/cputopology.rst         | 105 ++++++++++++++++++
 .../translations/pt_BR/admin-guide/index.rst  |   2 +-
 2 files changed, 106 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/translations/pt_BR/admin-guide/cputopology.rst

diff --git a/Documentation/translations/pt_BR/admin-guide/cputopology.rst b/Documentation/translations/pt_BR/admin-guide/cputopology.rst
new file mode 100644
index 000000000..f7321e275
--- /dev/null
+++ b/Documentation/translations/pt_BR/admin-guide/cputopology.rst
@@ -0,0 +1,105 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+================================================================
+Como as informações de topologia de CPU são exportadas via sysfs
+================================================================
+
+As informações de topologia de CPU são exportadas via sysfs. Os itens
+(atributos) são semelhantes à saída de /proc/cpuinfo em algumas arquiteturas.
+Eles residem em /sys/devices/system/cpu/cpuX/topology/. Por favor, consulte o
+arquivo de ABI: Documentation/ABI/stable/sysfs-devices-system-cpu.
+
+O arquivo independente de arquitetura, drivers/base/topology.c, exporta esses
+atributos. No entanto, os arquivos do sysfs relacionados à hierarquia de die,
+cluster, book e drawer só serão criados se uma arquitetura fornecer as macros
+relacionadas, conforme descrito abaixo.
+
+Para que uma arquitetura ofereça suporte a esse recurso, ela deve definir
+algumas dessas macros em include/asm-XXX/topology.h::
+
+	#define topology_physical_package_id(cpu)
+	#define topology_die_id(cpu)
+	#define topology_cluster_id(cpu)
+	#define topology_core_id(cpu)
+	#define topology_book_id(cpu)
+	#define topology_drawer_id(cpu)
+	#define topology_sibling_cpumask(cpu)
+	#define topology_core_cpumask(cpu)
+	#define topology_cluster_cpumask(cpu)
+	#define topology_die_cpumask(cpu)
+	#define topology_book_cpumask(cpu)
+	#define topology_drawer_cpumask(cpu)
+
+O tipo das ``macros **_id`` é int.
+O tipo das ``macros **_cpumask`` é ``(const) struct cpumask *``. Estas últimas
+correspondem aos atributos apropriados ``**_siblings`` do sysfs (exceto por
+topology_sibling_cpumask(), que corresponde a thread_siblings).
+
+Para manter a consistência em todas as arquiteturas, include/linux/topology.h
+fornece definições padrão para qualquer uma das macros acima que não estejam
+definidas em include/asm-XXX/topology.h:
+
+1) topology_physical_package_id: -1
+2) topology_die_id: -1
+3) topology_cluster_id: -1
+4) topology_core_id: 0
+5) topology_book_id: -1
+6) topology_drawer_id: -1
+7) topology_sibling_cpumask: apenas a CPU fornecida
+8) topology_core_cpumask: apenas a CPU fornecida
+9) topology_cluster_cpumask: apenas a CPU fornecida
+10) topology_die_cpumask: apenas a CPU fornecida
+11) topology_book_cpumask: apenas a CPU fornecida
+12) topology_drawer_cpumask: apenas a CPU fornecida
+
+Além disso, as informações de topologia de CPU são fornecidas sob
+/sys/devices/system/cpu e incluem estes arquivos. A fonte interna para a saída
+está entre colchetes ("[]").
+
+    =========== ==========================================================
+    kernel_max: o índice máximo de CPU permitido pela configuração do kernel.
+		[NR_CPUS-1]
+
+    offline:	CPUs que não estão online porque foram desligadas via
+		HOTPLUG ou excedem o limite de CPUs permitido pela
+		configuração do kernel (kernel_max acima).
+		[~cpu_online_mask + cpus >= NR_CPUS]
+
+    online:	CPUs que estão online e sendo escalonadas [cpu_online_mask]
+
+    possible:	CPUs para as quais foram alocados recursos e que podem ser
+		colocadas online se estiverem presentes. [cpu_possible_mask]
+
+    present:	CPUs que foram identificadas como presentes no
+		sistema. [cpu_present_mask]
+    =========== ==========================================================
+
+O formato para a saída acima é compatível com cpulist_parse()
+[veja <linux/cpumask.h>]. Alguns exemplos a seguir.
+
+Neste exemplo, existem 64 CPUs no sistema, mas as cpus 32-63 excedem
+o máximo do kernel, que está limitado a 0..31 devido à opção de
+configuração NR_CPUS ser 32. Observe também que as CPUs 2 e 4-31 não estão
+online, mas poderiam ser colocadas online, pois estão tanto presentes
+quanto possíveis::
+
+     kernel_max: 31
+        offline: 2,4-31,32-63
+         online: 0-1,3
+       possible: 0-31
+        present: 0-31
+
+Neste exemplo, a opção de configuração NR_CPUS é 128, mas o kernel foi
+iniciado com possible_cpus=144. Existem 4 CPUs no sistema e a cpu2
+foi colocada offline manualmente (e é a única CPU que pode ser colocada
+online.)::
+
+     kernel_max: 127
+        offline: 2,4-127,128-143
+         online: 0-1,3
+       possible: 0-127
+        present: 0-3
+
+Consulte Documentation/core-api/cpu_hotplug.rst para o parâmetro de inicialização
+do kernel possible_cpus=NUM, bem como para obter mais informações sobre as
+várias cpumasks.
diff --git a/Documentation/translations/pt_BR/admin-guide/index.rst b/Documentation/translations/pt_BR/admin-guide/index.rst
index 878a88d71..c574515c2 100644
--- a/Documentation/translations/pt_BR/admin-guide/index.rst
+++ b/Documentation/translations/pt_BR/admin-guide/index.rst
@@ -37,10 +37,10 @@ com eles.
 
    sysfs-rules
    sysctl/index
+   cputopology
 
 Todolist:
 
-*   cputopology
 *   abi
 
 Documentação relacionada à segurança:
-- 
2.47.3

[PATCH 05/10] docs/translations/pt_BR: admin-guide: add hw-vuln/index.rst

[Daniel Pereira]

Add translation of hw-vuln/index.rst to Portuguese and update
admin-guide/index.rst.

Signed-off-by: Daniel Pereira <danielmaraboo@gmail.com>
---
 .../pt_BR/admin-guide/hw-vuln/index.rst       | 30 +++++++++++++++++++
 .../translations/pt_BR/admin-guide/index.rst  |  6 +++-
 2 files changed, 35 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/translations/pt_BR/admin-guide/hw-vuln/index.rst

diff --git a/Documentation/translations/pt_BR/admin-guide/hw-vuln/index.rst b/Documentation/translations/pt_BR/admin-guide/hw-vuln/index.rst
new file mode 100644
index 000000000..46cdf7ebb
--- /dev/null
+++ b/Documentation/translations/pt_BR/admin-guide/hw-vuln/index.rst
@@ -0,0 +1,30 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+============================
+Vulnerabilidades de hardware
+============================
+
+Esta seção descreve vulnerabilidades de CPU e fornece uma visão geral das
+possíveis mitigações, juntamente com orientações para a seleção de mitigações,
+caso sejam configuráveis em tempo de compilação, inicialização ou execução.
+
+Todolist:
+
+*   attack_vector_controls
+*   spectre
+*   l1tf
+*   mds
+*   tsx_async_abort
+*   multihit
+*   special-register-buffer-data-sampling
+*   core-scheduling
+*   l1d_flush
+*   processor_mmio_stale_data
+*   cross-thread-rsb
+*   srso
+*   gather_data_sampling
+*   reg-file-data-sampling
+*   rsb
+*   old_microcode
+*   indirect-target-selection
+*   vmscape
diff --git a/Documentation/translations/pt_BR/admin-guide/index.rst b/Documentation/translations/pt_BR/admin-guide/index.rst
index c574515c2..9f7933c57 100644
--- a/Documentation/translations/pt_BR/admin-guide/index.rst
+++ b/Documentation/translations/pt_BR/admin-guide/index.rst
@@ -45,9 +45,13 @@ Todolist:
 
 Documentação relacionada à segurança:
 
+.. toctree::
+   :maxdepth: 1
+
+   hw-vuln/index
+
 Todolist:
 
-*   hw-vuln/index
 *   LSM/index
 *   perf-security
 
-- 
2.47.3

[PATCH 06/10] docs/translations/pt_BR: admin-guide: add LSM/index.rst

[Daniel Pereira]

Add translation of LSM/index.rst to Portuguese and update
admin-guide/index.rst.

Signed-off-by: Daniel Pereira <danielmaraboo@gmail.com>
---
 .../pt_BR/admin-guide/LSM/index.rst           | 53 +++++++++++++++++++
 .../translations/pt_BR/admin-guide/index.rst  |  2 +-
 2 files changed, 54 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/translations/pt_BR/admin-guide/LSM/index.rst

diff --git a/Documentation/translations/pt_BR/admin-guide/LSM/index.rst b/Documentation/translations/pt_BR/admin-guide/LSM/index.rst
new file mode 100644
index 000000000..353ed472f
--- /dev/null
+++ b/Documentation/translations/pt_BR/admin-guide/LSM/index.rst
@@ -0,0 +1,53 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===========================================
+Uso dos Módulos de Segurança do Linux (LSM)
+===========================================
+
+O framework dos Módulos de Segurança do Linux (LSM - Linux Security Module)
+fornece um mecanismo para que várias verificações de segurança sejam interceptadas
+por novas extensões do kernel. O nome "módulo" é um pouco impróprio, já que essas
+extensões não são, na verdade, módulos carregáveis do kernel. Em vez disso, elas
+são selecionáveis em tempo de compilação via CONFIG_DEFAULT_SECURITY e podem ser
+substituídas em tempo de inicialização pelo argumento de linha de comando do
+kernel ``"security=..."``, no caso em que múltiplos LSMs foram compilados em um
+determinado kernel.
+
+Os principais usuários da interface LSM são as extensões de Controle de Acesso
+Obrigatório (MAC - Mandatory Access Control), que fornecem uma política de
+segurança abrangente. Os exemplos incluem SELinux, Smack, Tomoyo e AppArmor. Além
+das extensões MAC maiores, outras extensões podem ser construídas usando o LSM
+para fornecer alterações específicas na operação do sistema quando esses ajustes
+não estão disponíveis na funcionalidade principal do próprio Linux.
+
+Os módulos de capacidades do Linux sempre serão incluídos. Isso pode ser seguido
+por qualquer número de módulos "menores" (minor) e no máximo um módulo "maior"
+(major). Para obter mais detalhes sobre capacidades, consulte ``capabilities(7)``
+no projeto Linux man-pages.
+
+Uma lista dos módulos de segurança ativos pode ser encontrada lendo
+``/sys/kernel/security/lsm``. Esta é uma lista separada por vírgulas e sempre
+incluirá o módulo de capacidade. A lista reflete a ordem na qual as verificações
+são feitas. O módulo de capacidade sempre será o primeiro, seguido por quaisquer
+módulos "menores" (por exemplo, Yama) e depois pelo módulo "maior" (por exemplo,
+SELinux), se houver um configurado.
+
+Os atributos de processo associados aos módulos de segurança "maiores" devem ser
+acessados e mantidos usando os arquivos especiais em ``/proc/.../attr``. Um módulo
+de segurança pode manter um subdiretório específico do módulo lá, nomeado após o
+módulo. ``/proc/.../attr/smack`` é fornecido pelo módulo de segurança Smack e
+contém todos os seus arquivos especiais. Os arquivos diretamente em
+``/proc/.../attr`` permanecem como interfaces legadas para módulos que fornecem
+subdiretórios.
+
+Todolist:
+
+*   apparmor
+*   LoadPin
+*   SELinux
+*   Smack
+*   tomoyo
+*   Yama
+*   SafeSetID
+*   ipe
+*   landlock
diff --git a/Documentation/translations/pt_BR/admin-guide/index.rst b/Documentation/translations/pt_BR/admin-guide/index.rst
index 9f7933c57..19678a358 100644
--- a/Documentation/translations/pt_BR/admin-guide/index.rst
+++ b/Documentation/translations/pt_BR/admin-guide/index.rst
@@ -49,10 +49,10 @@ Documentação relacionada à segurança:
    :maxdepth: 1
 
    hw-vuln/index
+   LSM/index
 
 Todolist:
 
-*   LSM/index
 *   perf-security
 
 Inicializando o kernel
-- 
2.47.3

[PATCH 07/10] docs/translations/pt_BR: admin-guide: add perf-security.rst

[Daniel Pereira]

Add translation of perf-security.rst to Portuguese and update
admin-guide/index.rst.

Signed-off-by: Daniel Pereira <danielmaraboo@gmail.com>
---
 .../translations/pt_BR/admin-guide/index.rst  |   5 +-
 .../pt_BR/admin-guide/perf-security.rst       | 328 ++++++++++++++++++
 2 files changed, 329 insertions(+), 4 deletions(-)
 create mode 100644 Documentation/translations/pt_BR/admin-guide/perf-security.rst

diff --git a/Documentation/translations/pt_BR/admin-guide/index.rst b/Documentation/translations/pt_BR/admin-guide/index.rst
index 19678a358..264b3c1c8 100644
--- a/Documentation/translations/pt_BR/admin-guide/index.rst
+++ b/Documentation/translations/pt_BR/admin-guide/index.rst
@@ -50,10 +50,7 @@ Documentação relacionada à segurança:
 
    hw-vuln/index
    LSM/index
-
-Todolist:
-
-*   perf-security
+   perf-security
 
 Inicializando o kernel
 ----------------------
diff --git a/Documentation/translations/pt_BR/admin-guide/perf-security.rst b/Documentation/translations/pt_BR/admin-guide/perf-security.rst
new file mode 100644
index 000000000..7af45868a
--- /dev/null
+++ b/Documentation/translations/pt_BR/admin-guide/perf-security.rst
@@ -0,0 +1,328 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+Segurança das ferramentas e eventos Perf
+========================================
+
+Visão geral
+-----------
+
+O uso dos Contadores de Desempenho para Linux (perf_events) [1]_ , [2]_ , [3]_
+pode impor um risco considerável de vazamento de dados confidenciais acessados
+por processos monitorados. O vazamento de dados é possível tanto em cenários de
+uso direto da API de chamadas de sistema perf_events [2]_ quanto por meio de
+arquivos de dados gerados pelo utilitário em modo de usuário da ferramenta
+Perf (Perf) [3]_ , [4]_ . O risco depende da natureza dos dados que as unidades
+de monitoramento de desempenho (PMU - Performance Monitoring Units) do
+perf_events [2]_ e o Perf coletam e expõem para análise de desempenho.
+Os dados de sistema e de desempenho coletados podem ser divididos em várias
+categorias:
+
+1. Dados de configuração de hardware e software do sistema, por exemplo: um
+   modelo de CPU e sua configuração de cache, a quantidade de memória disponível
+   e sua topologia, versões do kernel e do Perf utilizadas, configuração de
+   monitoramento de desempenho incluindo tempo de experimento, configuração de
+   eventos, parâmetros de linha de comando do Perf, etc.
+
+2. Caminhos de módulos de usuário e de kernel e seus endereços de carregamento com
+   tamanhos, nomes de processos e threads com seus PIDs e TIDs, registros de data
+   e hora (timestamps) para eventos capturados de hardware e software.
+
+3. Conteúdo de contadores de software do kernel (por exemplo, para trocas de contexto,
+   falhas de página, migrações de CPU), contadores arquiteturais de desempenho de
+   hardware (PMC) [8]_ e registradores específicos de modelo (MSR) [9]_ que fornecem
+   métricas de execução para várias partes monitoradas do sistema (por exemplo,
+   controlador de memória (IMC), interconexão (QPI/UPI) ou contadores uncore
+   periféricos (PCIe)) sem atribuição direta a qualquer estado de contexto de execução.
+
+4. Conteúdo de registradores de contexto de execução arquiteturais (por exemplo,
+   RIP, RSP, RBP em x86_64), endereços de memória e dados de espaço de usuário
+   e de kernel de processos, conteúdo de vários MSRs arquiteturais que capturam
+   dados desta categoria.
+
+Dados que pertencem à quarta categoria podem conter potencialmente dados confidenciais
+do processo. Se as PMUs em alguns modos de monitoramento capturam valores de registradores
+de contexto de execução ou dados da memória do processo, o acesso a esses modos de
+monitoramento precisa ser ordenado e protegido adequadamente. Portanto, as operações de
+monitoramento de desempenho e observabilidade do perf_events são objeto de gerenciamento
+de controle de acesso de segurança [5]_ .
+
+Controle de acesso do perf_events
+---------------------------------
+
+Para realizar verificações de segurança, a implementação do Linux divide os
+processos em duas categorias [6]_ : a) processos privilegiados (cujo ID de
+usuário efetivo é 0, chamados de superusuário ou root) e b) processos não
+privilegiados (cujo UID efetivo é diferente de zero). Processos privilegiados
+ignoram todas as verificações de permissão de segurança do kernel, de modo que
+o monitoramento de desempenho do perf_events está totalmente disponível para
+processos privilegiados sem restrições de acesso, escopo e recursos.
+
+Processos não privilegiados estão sujeitos a uma verificação completa de permissão
+de segurança com base nas credenciais do processo [5]_ (geralmente: UID efetivo,
+GID efetivo e lista de grupos suplementares).
+
+O Linux divide os privilégios tradicionalmente associados ao superusuário em
+unidades distintas, conhecidas como capacidades (capabilities) [6]_ , que podem
+ser habilitadas e desabilitadas independentemente por thread para processos e
+arquivos de usuários não privilegiados.
+
+Processos não privilegiados com a capacidade CAP_PERFMON habilitada são tratados
+como processos privilegiados em relação às operações de monitoramento de
+desempenho e observabilidade do perf_events, contornando, assim, as verificações
+de permissões de *escopo* no kernel. A CAP_PERFMON implementa o princípio do menor
+privilégio [13]_ (POSIX 1003.1e: 2.2.2.39) para operações de monitoramento de
+desempenho e observabilidade no kernel e fornece uma abordagem segura para o
+monitoramento de desempenho e observabilidade no sistema.
+
+Por motivos de compatibilidade retroativa, o acesso às operações de monitoramento
+e observabilidade do perf_events também é aberto para processos privilegiados com
+CAP_SYS_ADMIN, mas o uso de CAP_SYS_ADMIN para casos de uso de monitoramento e
+observabilidade seguros é desencorajado em relação à capacidade CAP_PERFMON.
+Se os registros de auditoria do sistema [14]_ para um processo usando a API de
+chamada de sistema perf_events contiverem registros de negação para a obtenção de
+ambas as capacidades CAP_PERFMON e CAP_SYS_ADMIN, fornecer ao processo apenas a
+capacidade CAP_PERFMON é recomendado como a abordagem segura preferida para resolver
+o log duplo de negação de acesso relacionado ao uso de monitoramento de desempenho
+e observabilidade.
+
+Antes do Linux v5.9, processos não privilegiados que usavam a chamada de sistema
+perf_events também estavam sujeitos à verificação do modo de acesso ptrace
+PTRACE_MODE_READ_REALCREDS [7]_ , cujo resultado determina se o monitoramento é
+permitido. Portanto, processos não privilegiados com a capacidade CAP_SYS_PTRACE
+recebiam permissão efetiva para passar na verificação. A partir do Linux v5.9, a
+capacidade CAP_SYS_PTRACE não é necessária e a CAP_PERFMON é suficiente para que
+processos executem operações de monitoramento de desempenho e observabilidade.
+
+Outras capacidades concedidas a processos não privilegiados podem efetivamente
+permitir a captura de dados adicionais necessários para análises posteriores de
+desempenho de processos monitorados ou do sistema. Por exemplo, a capacidade
+CAP_SYSLOG permite a leitura de endereços de memória do espaço de kernel a partir
+do arquivo /proc/kallsyms.
+
+Grupos de usuários privilegiados do Perf
+----------------------------------------
+
+Mecanismos de capacidades, arquivos privilegiados desprovidos de capacidade
+(capability-dumb) [6]_, ACLs de sistema de arquivos [10]_ e o utilitário
+sudo [15]_ podem ser usados para criar grupos dedicados de usuários privilegiados
+do Perf com permissão para executar monitoramento de desempenho e observabilidade
+sem limites. As etapas a seguir podem ser seguidas para criar esses grupos de
+usuários privilegiados do Perf.
+
+1. Crie o grupo perf_users de usuários privilegiados do Perf, atribua o grupo
+   perf_users ao executável da ferramenta Perf e restrinja o acesso ao executável
+   para outros usuários no sistema que não estejam no grupo perf_users:
+
+::
+
+   # groupadd perf_users
+   # ls -alhF
+   -rwxr-xr-x  2 root root  11M Oct 19 15:12 perf
+   # chgrp perf_users perf
+   # ls -alhF
+   -rwxr-xr-x  2 root perf_users  11M Oct 19 15:12 perf
+   # chmod o-rwx perf
+   # ls -alhF
+   -rwxr-x---  2 root perf_users  11M Oct 19 15:12 perf
+
+2. Atribua as capacidades necessárias ao arquivo executável da ferramenta Perf e
+   habilite os membros do grupo perf_users com privilégios de monitoramento e
+   observabilidade [6]_ :
+
+::
+
+   # setcap "cap_perfmon,cap_sys_ptrace,cap_syslog=ep" perf
+   # setcap -v "cap_perfmon,cap_sys_ptrace,cap_syslog=ep" perf
+   perf: OK
+   # getcap perf
+   perf = cap_sys_ptrace,cap_syslog,cap_perfmon+ep
+
+Se a libcap [16]_ instalada ainda não oferecer suporte a "cap_perfmon", use "38",
+ou seja:
+
+::
+
+   # setcap "38,cap_ipc_lock,cap_sys_ptrace,cap_syslog=ep" perf
+
+Observe que você pode precisar incluir 'cap_ipc_lock' na combinação para
+ferramentas como 'perf top'; alternativamente, use 'perf top -m N' para reduzir a
+memória que ele usa para o buffer de anel (ring buffer) do perf; consulte a seção
+de alocação de memória abaixo.
+
+O uso de uma libcap sem suporte a CAP_PERFMON fará com que cap_get_flag(caps, 38,
+CAP_EFFECTIVE, &val) falhe, o que fará com que o evento padrão seja 'cycles:u',
+portanto, como solução alternativa, solicite explicitamente o evento 'cycles', ou seja:
+
+::
+
+  # perf top -e cycles
+
+Para obter amostras do kernel e do usuário com um binário do perf com apenas CAP_PERFMON.
+
+Como resultado, os membros do grupo perf_users são capazes de conduzir
+monitoramento de desempenho e observabilidade utilizando a funcionalidade do
+executável da ferramenta Perf configurado que, ao ser executado, passa nas
+verificações de escopo do subsistema perf_events.
+
+Caso não seja possível atribuir as capacidades necessárias ao executável da
+ferramenta Perf (por exemplo, o sistema de arquivos está montado com a opção
+nosuid ou atributos estendidos não são suportados pelo sistema de arquivos), a
+criação de um ambiente privilegiado por capacidades, naturalmente um shell, é
+possível. O shell fornece aos processos herdados a CAP_PERFMON e outras
+capacidades necessárias para que operações de monitoramento de desempenho e
+observabilidade estejam disponíveis no ambiente sem limites. O acesso ao ambiente
+pode ser aberto via utilitário sudo apenas para membros do grupo perf_users. Para
+criar tal ambiente:
+
+1. Crie um script shell que utilize o utilitário capsh [16]_ para atribuir a
+   CAP_PERFMON e outras capacidades necessárias no conjunto de capacidades
+   ambiente (ambient capability set) do processo do shell, travar os bits de
+   segurança do processo após habilitar os bits SECBIT_NO_SETUID_FIXUP,
+   SECBIT_NOROOT e SECBIT_NO_CAP_AMBIENT_RAISE e, em seguida, alterar a
+   identidade do processo para o chamador do script via sudo, que deve ser
+   essencialmente um membro do grupo perf_users:
+
+::
+
+   # ls -alh /usr/local/bin/perf.shell
+   -rwxr-xr-x. 1 root root 83 Oct 13 23:57 /usr/local/bin/perf.shell
+   # cat /usr/local/bin/perf.shell
+   exec /usr/sbin/capsh --iab=^cap_perfmon --secbits=239 --user=$SUDO_USER -- -l
+
+2. Estenda a política do sudo no arquivo /etc/sudoers com uma regra para o grupo
+   perf_users:
+
+::
+
+   # grep perf_users /etc/sudoers
+   %perf_users    ALL=/usr/local/bin/perf.shell
+
+3. Verifique se os membros do grupo perf_users têm acesso ao shell privilegiado
+   e têm a CAP_PERFMON e outras capacidades necessárias habilitadas nos conjuntos
+   de capacidades permitidas (permitted), efetivas (effective) e ambiente (ambient)
+   de um processo herdado:
+
+::
+
+  $ id
+  uid=1003(capsh_test) gid=1004(capsh_test) groups=1004(capsh_test),1000(perf_users) context=unconfined_u:unconfined_r:unconfined_t:s0-s0:c0.c1023
+  $ sudo perf.shell
+  [sudo] password for capsh_test:
+  $ grep Cap /proc/self/status
+  CapInh:        0000004000000000
+  CapPrm:        0000004000000000
+  CapEff:        0000004000000000
+  CapBnd:        000000ffffffffff
+  CapAmb:        0000004000000000
+  $ capsh --decode=0000004000000000
+  0x0000004000000000=cap_perfmon
+
+Como resultado, os membros do grupo perf_users têm acesso ao ambiente
+privilegiado onde podem usar ferramentas que empregam APIs de monitoramento
+de desempenho governadas pela capacidade Linux CAP_PERFMON.
+
+Este gerenciamento específico de controle de acesso está disponível apenas para
+processos em execução pelo superusuário ou root com as capacidades CAP_SETPCAP,
+CAP_SETFCAP [6]_ .
+
+Usuários não privilegiados
+--------------------------
+
+O controle de *escopo* e *acesso* do perf_events para processos não
+privilegiados é governado pela configuração perf_event_paranoid [2]_ :
+
+-1:
+     Não impõe restrições de *escopo* e *acesso* ao uso do monitoramento de
+     desempenho do perf_events. O limite de travamento perf_event_mlock_kb [2]_
+     por usuário e por CPU é ignorado ao alocar buffers de memória para armazenar
+     dados de desempenho. Este é o modo menos seguro, pois o *escopo* monitorado
+     permitido é maximizado e nenhum limite específico do perf_events é imposto
+     aos *recursos* alocados para o monitoramento de desempenho.
+
+>=0:
+     O *escopo* inclui o monitoramento de desempenho por processo e em todo o
+     sistema, mas exclui o monitoramento de tracepoints brutos e tracepoints de
+     funções do ftrace. Eventos de CPU e do sistema ocorridos durante a execução
+     no espaço de usuário ou no espaço de kernel podem ser monitorados e capturados
+     para análise posterior. O limite de travamento perf_event_mlock_kb por usuário
+     e por CPU é imposto, mas ignorado para processos não privilegiados com a
+     capacidade CAP_IPC_LOCK [6]_ .
+
+>=1:
+     O *escopo* inclui apenas o monitoramento de desempenho por processo e exclui
+     o monitoramento de desempenho em todo o sistema. Eventos de CPU e do sistema
+     ocorridos durante a execução no espaço de usuário ou no espaço de kernel podem
+     ser monitorados e capturados para análise posterior. O limite de travamento
+     perf_event_mlock_kb por usuário e por CPU é imposto, mas ignorado para
+     processos não privilegiados com a capacidade CAP_IPC_LOCK.
+
+>=2:
+     O *escopo* inclui apenas o monitoramento de desempenho por processo. Eventos
+     de CPU e do sistema ocorridos durante a execução apenas no espaço de usuário
+     podem ser monitorados e capturados para análise posterior. O limite de
+     travamento perf_event_mlock_kb por usuário e por CPU é imposto, mas ignorado
+     para processos não privilegiados com a capacidade CAP_IPC_LOCK.
+
+Controle de recursos
+--------------------
+
+Descritores de arquivo abertos
+++++++++++++++++++++++++++++++
+
+A API de chamada de sistema perf_events [2]_ aloca descritores de arquivo para cada
+evento de PMU configurado. Descritores de arquivos abertos são um recurso contabilizado
+por processo e governado pelo limite RLIMIT_NOFILE [11]_ (ulimit -n), que geralmente é
+derivado do processo do shell de login. Ao configurar a coleta do Perf para uma longa
+lista de eventos em um sistema de servidor grande, esse limite pode ser facilmente
+atingido, impedindo a configuração de monitoramento necessária. O limite RLIMIT_NOFILE
+pode ser aumentado por usuário modificando o conteúdo do arquivo limits.conf [12]_ .
+Normalmente, uma sessão de amostragem do Perf (perf record) requer uma quantidade de
+descritores de arquivos perf_event abertos que não seja inferior ao número de eventos
+monitorados multiplicado pelo número de CPUs monitoradas.
+
+Alocação de memória
++++++++++++++++++++
+
+A quantidade de memória disponível para processos de usuário para captura de dados
+de monitoramento de desempenho é governada pela configuração perf_event_mlock_kb [2]_ .
+Esta configuração de recurso específica do perf_event define os limites gerais de
+memória por CPU permitidos para mapeamento pelos processos de usuário para executar
+o monitoramento de desempenho. A configuração essencialmente estende o limite
+RLIMIT_MEMLOCK [11]_ , mas apenas para regiões de memória mapeadas especificamente
+para a captura de eventos de desempenho monitorados e dados relacionados.
+
+Por exemplo, se uma máquina tiver oito núcleos e o limite perf_event_mlock_kb estiver
+definido como 516 KiB, então um processo de usuário receberá 516 KiB * 8 = 4128 KiB
+de memória acima do limite RLIMIT_MEMLOCK (ulimit -l) para buffers mmap do perf_event.
+Em particular, isso significa que, se o usuário desejar iniciar dois ou mais processos
+de monitoramento de desempenho, ele deverá distribuir manualmente os 4128 KiB disponíveis
+entre os processos de monitoramento, por exemplo, usando a opção do modo de gravação
+--mmap-pages do Perf. Caso contrário, o primeiro processo de monitoramento de desempenho
+iniciado alocará todos os 4128 KiB disponíveis e os outros processos falharão em prosseguir
+devido à falta de memória.
+
+As restrições de recursos RLIMIT_MEMLOCK e perf_event_mlock_kb são ignoradas para
+processos com a capacidade CAP_IPC_LOCK. Assim, usuários privilegiados de
+perf_events/Perf podem receber memória acima das restrições para fins de monitoramento
+de desempenho de perf_events/Perf fornecendo a capacidade CAP_IPC_LOCK ao executável
+do Perf.
+
+Bibliografia
+------------
+
+.. [1] `<https://lwn.net/Articles/337493/>`_
+.. [2] `<http://man7.org/linux/man-pages/man2/perf_event_open.2.html>`_
+.. [3] `<http://web.eece.maine.edu/~vweaver/projects/perf_events/>`_
+.. [4] `<https://perf.wiki.kernel.org/index.php/Main_Page>`_
+.. [5] `<https://www.kernel.org/doc/html/latest/security/credentials.html>`_
+.. [6] `<http://man7.org/linux/man-pages/man7/capabilities.7.html>`_
+.. [7] `<http://man7.org/linux/man-pages/man2/ptrace.2.html>`_
+.. [8] `<https://en.wikipedia.org/wiki/Hardware_performance_counter>`_
+.. [9] `<https://en.wikipedia.org/wiki/Model-specific_register>`_
+.. [10] `<http://man7.org/linux/man-pages/man5/acl.5.html>`_
+.. [11] `<http://man7.org/linux/man-pages/man2/getrlimit.2.html>`_
+.. [12] `<http://man7.org/linux/man-pages/man5/limits.conf.5.html>`_
+.. [13] `<https://sites.google.com/site/fullycapable>`_
+.. [14] `<http://man7.org/linux/man-pages/man8/auditd.8.html>`_
+.. [15] `<https://man7.org/linux/man-pages/man8/sudo.8.html>`_
+.. [16] `<https://git.kernel.org/pub/scm/libs/libcap/libcap.git/>`_
-- 
2.47.3

[PATCH 08/10] docs/translations/pt_BR: admin-guide: add bootconfig.rst

[Daniel Pereira]

Add translation of bootconfig.rst to Portuguese and update
admin-guide/index.rst.

Signed-off-by: Daniel Pereira <danielmaraboo@gmail.com>
---
 .../pt_BR/admin-guide/bootconfig.rst          | 423 ++++++++++++++++++
 .../translations/pt_BR/admin-guide/index.rst  |   6 +-
 2 files changed, 428 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/translations/pt_BR/admin-guide/bootconfig.rst

diff --git a/Documentation/translations/pt_BR/admin-guide/bootconfig.rst b/Documentation/translations/pt_BR/admin-guide/bootconfig.rst
new file mode 100644
index 000000000..aa73c5752
--- /dev/null
+++ b/Documentation/translations/pt_BR/admin-guide/bootconfig.rst
@@ -0,0 +1,423 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+====================
+Configuração de boot
+====================
+
+:Autor: Masami Hiramatsu <mhiramat@kernel.org>
+
+Visão geral
+===========
+
+A configuração de boot expande a linha de comando atual do kernel para suportar
+dados adicionais de chave-valor ao inicializar o kernel de forma eficiente.
+Isso permite que os administradores passem um arquivo de configuração estruturado
+por chaves.
+
+Sintaxe do arquivo de configuração
+==================================
+
+A sintaxe de configuração de boot é uma estrutura simples de chave-valor. Cada
+chave consiste em palavras conectadas por pontos, e a chave e o valor são
+conectados por ``=``. A string de valor deve ser terminada pelos seguintes
+delimitadores descritos abaixo.
+
+Cada palavra-chave deve conter apenas letras do alfabeto, números, traço (``-``)
+ou sublinhado (``_``). E cada valor contém apenas caracteres imprimíveis ou espaços,
+exceto delimitadores como ponto e vírgula (``;``), quebra de linha (``\n``),
+vírgula (``,``), cerquilha (``#``) e chave de fechamento (``}``).
+
+Se o ``=`` for seguido por espaços em branco até um desses delimitadores, a chave
+será atribuída a um valor vazio.
+
+Para arrays, os valores do array são separados por vírgula (``,``), e comentários
+e quebras de linha com nova linha (``\n``) são permitidos entre os valores do array
+para facilitar a legibilidade. Assim, a primeira entrada do array deve estar na
+mesma linha da chave.::
+
+  CHAVE[.PALAVRA[...]] = VALOR[, VALOR2[...]][;]
+
+Diferente da sintaxe de linha de comando do kernel, espaços em branco (incluindo
+tabs) são ignorados ao redor da vírgula e do ``=``.
+
+Se você quiser usar esses delimitadores em um valor, pode usar aspas duplas
+(``"VALOR"``) ou aspas simples (``'VALOR'``) para colocá-lo entre aspas. Observe
+que você não pode escapar essas aspas.
+
+Pode haver uma chave que não tenha valor ou tenha um valor vazio. Essas chaves
+são usadas para verificar se a chave existe ou não (como um booleano).
+
+Sintaxe de chave-valor
+----------------------
+
+A sintaxe do arquivo de configuração de boot permite que o usuário mescle chaves
+com palavras parcialmente iguais usando chaves (braces). Por exemplo::
+
+ foo.bar.baz = value1
+ foo.bar.qux.quux = value2
+
+Elas também podem ser escritas assim::
+
+ foo.bar {
+    baz = value1
+    qux.quux = value2
+ }
+
+Ou de forma mais concisa, escrita da seguinte maneira::
+
+ foo.bar { baz = value1; qux.quux = value2 }
+
+Em ambos os estilos, as mesmas palavras-chave são mescladas automaticamente ao
+serem analisadas no momento da inicialização. Assim, você pode anexar árvores ou
+pares de chave-valor semelhantes.
+
+Valores com a mesma chave
+-------------------------
+
+É proibido que dois ou mais valores ou arrays compartilhem a mesma chave.
+Por exemplo::
+
+ foo = bar, baz
+ foo = qux  # !ERRO! não podemos redefinir a mesma chave
+
+Se você quiser atualizar o valor, deve usar o operador de substituição (override)
+``:=`` explicitamente. Por exemplo::
+
+ foo = bar, baz
+ foo := qux
+
+então, ``qux`` é atribuído à chave ``foo``. Isso é útil para sobrescrever o
+valor padrão adicionando bootconfigs personalizados (parciais) sem precisar
+analisar o bootconfig padrão.
+
+Se você quiser anexar o valor a uma chave existente como membro de um array,
+pode usar o operador ``+=``. Por exemplo::
+
+ foo = bar, baz
+ foo += qux
+
+Neste caso, a chave ``foo`` conterá ``bar``, ``baz`` e ``qux``.
+
+Além disso, subchaves e um valor podem coexistir sob uma chave pai.
+Por exemplo, a seguinte configuração é permitida::
+
+ foo = value1
+ foo.bar = value2
+ foo := value3 # Isto atualizará o valor de foo.
+
+Observe que, como não há sintaxe para colocar um valor puro diretamente sob uma
+chave estruturada, você deve defini-lo fora das chaves. Por exemplo::
+
+ foo {
+     bar = value1
+     bar {
+         baz = value2
+         qux = value3
+     }
+ }
+
+Além disso, a ordem do nó de valor sob uma chave é fixa. Se houver um valor e
+subchaves, o valor será sempre o primeiro nó filho da chave. Portanto, se o
+usuário especificar subchaves primeiro, por exemplo::
+
+ foo.bar = value1
+ foo = value2
+
+No programa (e em /proc/bootconfig), ele será exibido conforme abaixo::
+
+ foo = value2
+ foo.bar = value1
+
+Comentários
+-----------
+
+A sintaxe de configuração aceita comentários no estilo shell-script. Os comentários
+iniciados com cerquilha ("#") até a quebra de linha ("\n") serão ignorados.
+
+::
+
+ # linha de comentário
+ foo = value # valor atribuído a foo.
+ bar = 1, # 1º elemento
+       2, # 2º elemento
+       3  # 3º elemento
+
+Isto é analisado como abaixo::
+
+ foo = value
+ bar = 1, 2, 3
+
+Observe que você NÃO pode colocar um comentário ou uma quebra de linha entre o
+valor e o delimitador (``,`` ou ``;``). Isso significa que a seguinte configuração
+possui um erro de sintaxe::
+
+ key = 1 # comentário
+       ,2
+
+
+/proc/bootconfig
+================
+
+/proc/bootconfig é uma interface de espaço de usuário da configuração de boot.
+Diferente de /proc/cmdline, este arquivo exibe a lista no estilo chave-valor.
+Cada par chave-valor é mostrado em cada linha no seguinte formato::
+
+ CHAVE[.PALAVRAS...] = "[VALOR]"[,"VALOR2"...]
+
+
+Inicializando o kernel com um Boot Config
+=========================================
+
+Existem duas opções para inicializar o kernel com bootconfig: anexar o bootconfig
+à imagem initrd ou embuti-lo no próprio kernel.
+
+Anexando um Boot Config ao Initrd
+---------------------------------
+
+Como o arquivo de configuração de boot é carregado com o initrd por padrão, ele
+será adicionado ao final do arquivo de imagem do initrd (initramfs) com
+preenchimento (padding), tamanho, checksum e palavra mágica de 12 bytes conforme
+abaixo.
+
+[initrd][bootconfig][padding][size(le32)][checksum(le32)][#BOOTCONFIG\n]
+
+Os campos de tamanho (size) e checksum são valores de 32 bits sem sinal em little endian.
+
+Quando a configuração de boot é adicionada à imagem do initrd, o tamanho total
+do arquivo é alinhado a 4 bytes. Para preencher a lacuna, caracteres nulos
+(``\0``) serão adicionados. Assim, ``size`` é o comprimento do arquivo bootconfig
++ bytes de preenchimento.
+
+O kernel Linux decodifica a última parte da imagem do initrd na memória para
+obter os dados de configuração de boot.
+Por causa desse método "piggyback", não há necessidade de alterar ou atualizar o
+carregador de inicialização (boot loader) e a própria imagem do kernel, desde que
+o boot loader passe o tamanho correto do arquivo initrd. Se, por qualquer motivo,
+o boot loader passar um tamanho maior, o kernel não conseguirá encontrar os
+dados do bootconfig.
+
+Para realizar esta operação, o kernel Linux fornece o comando ``bootconfig`` sob
+tools/bootconfig, que permite ao administrador aplicar ou excluir o arquivo de
+configuração na/da imagem do initrd. Você pode compilá-lo com o seguinte comando::
+
+ # make -C tools/bootconfig
+
+Para adicionar seu arquivo de configuração de boot à imagem do initrd, execute o
+bootconfig conforme abaixo (dados antigos são removidos automaticamente se existirem)::
+
+ # tools/bootconfig/bootconfig -a your-config /boot/initrd.img-X.Y.Z
+
+Para remover a configuração da imagem, você pode usar a opção -d como abaixo::
+
+ # tools/bootconfig/bootconfig -d /boot/initrd.img-X.Y.Z
+
+Em seguida, adicione "bootconfig" na linha de comando normal do kernel para instruir
+o kernel a procurar pelo bootconfig no final do arquivo initrd.
+Como alternativa, compile seu kernel com a opção Kconfig ``CONFIG_BOOT_CONFIG_FORCE``
+selecionada.
+
+Embutindo um Boot Config no kernel
+----------------------------------
+
+Se você não puder usar initrd, também poderá embutir o arquivo bootconfig no
+kernel através de opções do Kconfig. Nesse caso, você precisa recompilar o
+kernel com as seguintes configurações::
+
+ CONFIG_BOOT_CONFIG_EMBED=y
+ CONFIG_BOOT_CONFIG_EMBED_FILE="/CAMINHO/PARA/ARQUIVO/BOOTCONFIG"
+
+``CONFIG_BOOT_CONFIG_EMBED_FILE`` requer um caminho absoluto ou um caminho
+relativo para o arquivo bootconfig a partir da árvore de código-fonte ou da
+árvore de objetos. O kernel o embutirá como o bootconfig padrão.
+
+Assim como ao anexar o bootconfig ao initrd, você precisa da opção ``bootconfig``
+na linha de comando do kernel para habilitar o bootconfig embutido ou,
+alternativamente, compilar seu kernel com a opção Kconfig
+``CONFIG_BOOT_CONFIG_FORCE`` selecionada.
+
+Observe que, mesmo se você definir esta opção, poderá sobrescrever o bootconfig
+embutido por outro bootconfig anexado ao initrd.
+
+Renderizando chaves kernel.* embutidas em tempo de compilação
+-------------------------------------------------------------
+
+Por padrão, o bootconfig embutido (``CONFIG_BOOT_CONFIG_EMBED=y``) é analisado
+em tempo de execução, após ``parse_early_param()`` já ter sido executado. Os
+tratadores de parâmetros iniciais (early parameters) (``mem=``, ``earlycon=``,
+``loglevel=``, ...) não conseguem, portanto, ver valores fornecidos através da
+subárvore ``kernel`` embutida.
+
+A opção ``CONFIG_CMDLINE_FROM_BOOTCONFIG`` resolve isso renderizando a subárvore
+``kernel`` de ``CONFIG_BOOT_CONFIG_EMBED_FILE`` em uma string de cmdline plana em
+tempo de compilação do kernel (via ``tools/bootconfig -C``) e prefixando-a a
+``boot_command_line`` durante a configuração arquitetural inicial, de modo que
+as chaves fiquem visíveis para ``parse_early_param()``.
+
+A opção requer ``CONFIG_BOOT_CONFIG_EMBED=y``, um ``CONFIG_BOOT_CONFIG_EMBED_FILE``
+não vazio, ``CONFIG_CMDLINE`` vazio e uma arquitetura que selecione
+``CONFIG_ARCH_SUPPORTS_CMDLINE_FROM_BOOTCONFIG``. Atualmente apenas x86 a seleciona;
+em outras arquiteturas, o bootconfig embutido ainda funciona, mas apenas por meio
+do analisador tardio em tempo de execução.
+
+A mesma ativação explícita de ``bootconfig`` se aplica como em outros lugares:
+as chaves renderizadas são prefixadas apenas quando ``bootconfig`` (em qualquer
+forma) aparece na linha de comando do kernel, ou quando ``CONFIG_BOOT_CONFIG_FORCE``
+está definido, cujo padrão é ``y`` quando ``CONFIG_BOOT_CONFIG_EMBED`` está definido.
+
+Por exemplo, dado::
+
+ kernel {
+   loglevel = 7
+   mem = 4G
+ }
+
+o kernel inicializa como se ``loglevel=7 mem=4G`` tivesse sido prefixado à linha
+de comando do carregador de inicialização, com os valores visíveis para os
+tratadores analisados precocemente. Valores separados por vírgula ainda são
+expandidos em múltiplas entradas de linha de comando de acordo com a convenção
+de array do bootconfig -- o ``kernel.earlycon = "uart8250,io,0x3f8"`` embutido
+deve estar entre aspas para resultar em uma única entrada ``earlycon=``, exatamente
+como no analisador em tempo de execução.
+
+Se a string renderizada não couber em ``COMMAND_LINE_SIZE`` juntamente com a
+linha de comando existente, o prefixo será ignorado e um erro será registrado,
+de modo que um bootconfig embutido superdimensionado não possa travar a inicialização.
+
+Interação com outras fontes de linha de comando e bootconfig
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Com ``CONFIG_CMDLINE_FROM_BOOTCONFIG=y``, a subárvore ``kernel`` renderizada
+comporta-se como uma linha de comando em tempo de compilação (semelhante a
+``CONFIG_CMDLINE``), e não como uma fonte de bootconfig. Ela é prefixada a
+``boot_command_line`` em ``setup_arch()``, antes de ``parse_early_param()`` e
+muito antes de o analisador em tempo de execução inspecionar um initrd. As opções
+podem chegar ao kernel a partir de até quatro locais:
+
+- Linha de comando do carregador de inicialização (bootloader): os argumentos
+  que o carregador de inicialização passa. A linha de comando embutida é
+  prefixada na frente deles, portanto, para parâmetros onde o último vence
+  (last-one-wins), uma opção do bootloader ainda sobrescreve o valor embutido.
+  Visível em /proc/cmdline.
+- Linha de comando embutida (esta opção): a subárvore ``kernel`` renderizada,
+  prefixada precocemente para ser vista por ``parse_early_param()``. Visível em
+  /proc/cmdline.
+- Bootconfig do initrd: analisado tardiamente em ``setup_boot_config()``; suas
+  chaves ``kernel`` são colocadas antes de ``boot_command_line``, ou seja, antes
+  da linha de comando embutida, portanto, a regra do último vencedor favorece os
+  valores embutidos. Como uma fonte de bootconfig, um bootconfig do initrd ainda
+  substitui o bootconfig embutido. Visível em /proc/cmdline e /proc/bootconfig.
+- Bootconfig embutido (tempo de execução): analisado tardiamente, apenas quando
+  nenhum bootconfig do initrd estiver presente. Visível em /proc/cmdline e
+  /proc/bootconfig.
+
+Assim, com esta opção, os valores ``kernel.*`` embutidos têm precedência sobre os
+valores ``kernel.*`` de um bootconfig do initrd: para parâmetros iniciais, o initrd
+ainda não foi analisado e, para parâmetros comuns, as chaves embutidas chegam mais
+tarde na linha de comando. Se você precisa que um bootconfig do initrd sobrescreva
+as chaves ``kernel.*`` embutidas, deixe esta opção desativada e confie no analisador
+em tempo de execução.
+
+A string renderizada faz parte da linha de comando, portanto aparece em
+/proc/cmdline. Ela deliberadamente não é mostrada em /proc/bootconfig: esse
+arquivo continua relatando a árvore de bootconfig analisada -- o bootconfig do
+initrd se presente, caso contrário o bootconfig embutido -- independentemente de a
+renderização da linha de comando em tempo de compilação estar ativada.
+
+Parâmetros do kernel via Boot Config
+====================================
+
+Além da linha de comando do kernel, a configuração de boot pode ser usada para
+passar os parâmetros do kernel. Todos os pares chave-valor sob a chave ``kernel``
+serão passados diretamente para a linha de comando do kernel. Além disso, os pares
+chave-valor sob ``init`` serão passados para o processo init via linha de comando.
+Os parâmetros são concatenados com a string de linha de comando do kernel fornecida
+pelo usuário na seguinte ordem, de modo que o parâmetro de linha de comando possa
+sobrescrever os parâmetros de bootconfig (isso depende de como o subsistema lida com
+parâmetros, mas em geral, o parâmetro anterior será sobrescrito pelo posterior)::
+
+ [bootconfig params][cmdline params] -- [bootconfig init params][cmdline init params]
+
+Aqui está um exemplo de arquivo bootconfig para parâmetros de kernel/init::
+
+ kernel {
+   root = 01234567-89ab-cdef-0123-456789abcd
+ }
+ init {
+  splash
+ }
+
+Isto será copiado na string de linha de comando do kernel da seguinte forma::
+
+ root="01234567-89ab-cdef-0123-456789abcd" -- splash
+
+Se o usuário fornecer alguma outra linha de comando como::
+
+ ro bootconfig -- quiet
+
+A linha de comando final do kernel será a seguinte::
+
+ root="01234567-89ab-cdef-0123-456789abcd" ro bootconfig -- splash quiet
+
+
+Limitações do arquivo de configuração
+=====================================
+
+Atualmente, o tamanho máximo da configuração é de 32 KB e o total de palavras-chave
+(não entradas de chave-valor) deve ser inferior a 1024 nós.
+Nota: este não é o número de entradas, mas de nós; uma entrada deve consumir mais
+de 2 nós (uma palavra-chave e um valor). Portanto, teoricamente, haverá até 512
+pares chave-valor. Se as chaves contiverem 3 palavras em média, poderá conter 256
+pares chave-valor. Na maioria dos casos, o número de itens de configuração estará
+abaixo de 100 entradas e será menor que 8 KB, o que seria suficiente.
+Se o número de nós exceder 1024, o analisador retornará um erro mesmo se o tamanho
+do arquivo for menor que 32 KB. (Observe que esse tamanho máximo não inclui os
+caracteres nulos de preenchimento.)
+De qualquer forma, como o comando bootconfig verifica isso ao anexar uma configuração
+de boot à imagem initrd, o usuário pode perceber antes da inicialização.
+
+
+APIs do Bootconfig
+==================
+
+O usuário pode consultar ou iterar sobre pares chave-valor; também é possível
+encontrar um nó de chave raiz (prefixo) e encontrar chaves-valores sob esse nó.
+
+Se você tiver uma string de chave, poderá consultar o valor diretamente com a chave
+usando xbc_find_value(). Se quiser saber quais chaves existem no bootconfig, pode
+usar xbc_for_each_key_value() para iterar sobre os pares chave-valor.
+Observe que você precisa usar xbc_array_for_each_value() para acessar o valor de
+cada array, por exemplo::
+
+ vnode = NULL;
+ xbc_find_value("key.word", &vnode);
+ if (vnode && xbc_node_is_array(vnode))
+    xbc_array_for_each_value(vnode, value) {
+      printk("%s ", value);
+    }
+
+Se você quiser focar em chaves que tenham uma string de prefixo, pode usar
+xbc_find_node() para encontrar um nó pela string de prefixo e iterar pelas chaves
+sob o nó de prefixo com xbc_node_for_each_key_value().
+
+Mas o uso mais típico é obter o valor nomeado sob o prefixo ou obter o array
+nomeado sob o prefixo, como abaixo::
+
+ root = xbc_find_node("key.prefix");
+ value = xbc_node_find_value(root, "option", &vnode);
+ ...
+ xbc_node_for_each_array_value(root, "array-option", value, anode) {
+    ...
+ }
+
+Isso acessa um valor de "key.prefix.option" e um array de "key.prefix.array-option".
+
+O bloqueio (locking) não é necessário, pois após a inicialização, a configuração
+torna-se somente leitura. Todos os dados e chaves devem ser copiados se você
+precisar modificá-los.
+
+
+Funções e estruturas
+====================
+
+.. kernel-doc:: include/linux/bootconfig.h
+.. kernel-doc:: lib/bootconfig.c
diff --git a/Documentation/translations/pt_BR/admin-guide/index.rst b/Documentation/translations/pt_BR/admin-guide/index.rst
index 264b3c1c8..96a54595f 100644
--- a/Documentation/translations/pt_BR/admin-guide/index.rst
+++ b/Documentation/translations/pt_BR/admin-guide/index.rst
@@ -55,9 +55,13 @@ Documentação relacionada à segurança:
 Inicializando o kernel
 ----------------------
 
+.. toctree::
+   :maxdepth: 1
+
+   bootconfig
+
 Todolist:
 
-*   bootconfig
 *   kernel-parameters
 *   efi-stub
 *   initrd
-- 
2.47.3

[PATCH 09/10] docs/translations/pt_BR: admin-guide: add kernel-parameters.rst

[Daniel Pereira]

Add translation of kernel-parameters.rst to Portuguese and update
admin-guide/index.rst.

Signed-off-by: Daniel Pereira <danielmaraboo@gmail.com>
---
 .../translations/pt_BR/admin-guide/index.rst  |   2 +-
 .../pt_BR/admin-guide/kernel-parameters.rst   | 134 ++++++++++++++++++
 2 files changed, 135 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/translations/pt_BR/admin-guide/kernel-parameters.rst

diff --git a/Documentation/translations/pt_BR/admin-guide/index.rst b/Documentation/translations/pt_BR/admin-guide/index.rst
index 96a54595f..40397ef77 100644
--- a/Documentation/translations/pt_BR/admin-guide/index.rst
+++ b/Documentation/translations/pt_BR/admin-guide/index.rst
@@ -59,10 +59,10 @@ Inicializando o kernel
    :maxdepth: 1
 
    bootconfig
+   kernel-parameters
 
 Todolist:
 
-*   kernel-parameters
 *   efi-stub
 *   initrd
 
diff --git a/Documentation/translations/pt_BR/admin-guide/kernel-parameters.rst b/Documentation/translations/pt_BR/admin-guide/kernel-parameters.rst
new file mode 100644
index 000000000..42a646632
--- /dev/null
+++ b/Documentation/translations/pt_BR/admin-guide/kernel-parameters.rst
@@ -0,0 +1,134 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+Os parâmetros de linha de comando do kernel
+===========================================
+
+A seguir está uma lista consolidada dos parâmetros do kernel conforme
+implementados pelas macros __setup(), early_param(), core_param() e
+module_param(), ordenados na ordem do dicionário inglês (definida como ignorar
+toda a pontuação e ordenar dígitos antes de letras sem distinção entre
+maiúsculas e minúsculas), e com descrições onde conhecidas.
+
+O kernel analisa os parâmetros da linha de comando do kernel até "``--``";
+se ele não reconhecer um parâmetro e este não contiver um '.', o parâmetro
+será passado para o init: parâmetros com '=' vão para o ambiente do init,
+outros são passados como argumentos de linha de comando para o init.
+Tudo após "``--``" é passado como argumento para o init.
+
+Os parâmetros de módulo podem ser especificados de duas maneiras: através da
+linha de comando do kernel com um prefixo de nome de módulo, ou via modprobe,
+por exemplo::
+
+	(linha de comando do kernel) usbcore.blinkenlights=1
+	(linha de comando do modprobe) modprobe usbcore blinkenlights=1
+
+Os parâmetros para módulos compilados embutidos no kernel precisam ser
+especificados na linha de comando do kernel. O modprobe examina a linha de
+comando do kernel (/proc/cmdline) e coleta parâmetros de módulo ao carregar um
+módulo, de modo que a linha de comando do kernel também pode ser usada para
+módulos carregáveis.
+
+Este documento pode não estar totalmente atualizado e abrangente. O comando
+"modinfo -p ${nomedomodulo}" exibe uma lista atual de todos os parâmetros de um
+módulo carregável. Módulos carregáveis, após serem carregados no kernel em
+execução, também revelam seus parâmetros em /sys/module/${nomedomodulo}/parameters/.
+Alguns desses parâmetros podem ser alterados em tempo de execução pelo comando
+``echo -n ${valor} > /sys/module/${nomedomodulo}/parameters/${param}``.
+
+Tratamento especial
+-------------------
+
+Hífens (traços) e sublinhados são equivalentes em nomes de parâmetros, portanto::
+
+	log_buf_len=1M print-fatal-signals=1
+
+também pode ser inserido como::
+
+	log-buf-len=1M print_fatal_signals=1
+
+Aspas duplas podem ser usadas para proteger espaços nos valores, por exemplo::
+
+	param="spaces in here"
+
+Listas de CPUs
+~~~~~~~~~~~~~~
+
+Alguns parâmetros do kernel recebem uma lista de CPUs como valor, por exemplo:
+isolcpus, nohz_full, irqaffinity, rcu_nocbs. O formato desta lista é:
+
+	<número da cpu>,...,<número da cpu>
+
+ou
+
+	<número da cpu>-<número da cpu>
+	(deve ser um intervalo positivo em ordem crescente)
+
+ou uma mistura
+
+	<número da cpu>,...,<número da cpu>-<número da cpu>
+
+Observe que, para o caso especial de um intervalo, é possível dividir o intervalo em
+grupos de tamanhos iguais e, para cada grupo, usar uma determinada quantidade a
+partir do início desse grupo:
+
+	<número da cpu>-<número da cpu>:<tamanho usado>/<tamanho do grupo>
+
+Por exemplo, pode-se adicionar à linha de comando o seguinte parâmetro:
+
+	isolcpus=1,2,10-20,100-2000:2/25
+
+onde o item final representa as CPUs 100,101,125,126,150,151,...
+
+O valor "N" pode ser usado para representar a última CPU numericamente no sistema,
+ou seja, "foo_cpus=16-N" seria equivalente a "16-31" em um sistema de 32 núcleos.
+
+Tenha em mente que "N" é dinâmico; portanto, se alterações no sistema fizerem com
+que a largura do bitmap mude, como menos núcleos na lista de CPUs, N e quaisquer
+intervalos que usem N também mudarão. Use o mesmo em um sistema pequeno de 4 núcleos,
+e "16-N" se tornará "16-3", e agora a mesma entrada de boot será sinalizada como
+inválida (início > fim).
+
+O nome de grupo especial tolerante a maiúsculas/minúsculas "all" tem o significado
+de selecionar todas as CPUs, de modo que "nohz_full=all" seja o equivalente a
+"nohz_full=0-N".
+
+A semântica de "N" e "all" é suportada em nível de bitmaps e é válida para todos
+os usuários de bitmap_parselist().
+
+Sufixos métricos
+~~~~~~~~~~~~~~~~
+
+O sufixo [KMG] é comumente descrito após vários valores de parâmetros do kernel.
+Os sufixos 'K', 'M', 'G', 'T', 'P' e 'E' são permitidos. Essas letras representam
+os multiplicadores _binários_ 'Quilo', 'Mega', 'Giga', 'Tera', 'Peta' e 'Exa',
+equivalendo a 2^10, 2^20, 2^30, 2^40, 2^50 e 2^60 bytes, respectivamente. Esses
+sufixos de letras também podem ser totalmente omitidos.
+
+Opções de compilação do kernel
+------------------------------
+
+Os parâmetros listados abaixo só são válidos se certas opções de compilação do
+kernel foram ativadas e se o respectivo hardware estiver presente. Esta lista deve
+ser mantida em ordem alfabética. O texto entre colchetes no início de cada descrição
+informa as restrições sob as quais um parâmetro é aplicável.
+
+Os parâmetros indicados com BOOT são, na verdade, interpretados pelo carregador
+de inicialização e não têm significado diretamente para o kernel.
+Não modifique a sintaxe dos parâmetros do carregador de inicialização sem extrema
+necessidade ou coordenação com <Documentation/arch/x86/boot.rst>.
+
+Existem também parâmetros do kernel específicos de arquitetura não documentados aqui.
+
+Observe que TODOS os parâmetros do kernel listados abaixo DISTINGUEM MAIÚSCULAS DE
+MINÚSCULAS, e que um = final no nome de qualquer parâmetro indica que o parâmetro
+será inserido como uma variável de ambiente, enquanto sua ausência indica que ele
+aparecerá como um argumento do kernel legível via /proc/cmdline por programas em
+execução assim que o sistema estiver ativo.
+
+O número de parâmetros do kernel não é limitado, mas o comprimento da linha de
+comando completa (parâmetros incluindo espaços, etc.) é limitado a um número fixo
+de caracteres. Este limite depende da arquitetura e varia entre 256 e 4096 caracteres.
+Ele é definido no arquivo ./include/uapi/asm-generic/setup.h como COMMAND_LINE_SIZE.
+
+.. include:: ../../../admin-guide/kernel-parameters.txt
+   :literal:
-- 
2.47.3

[PATCH 10/10] docs/translations/pt_BR: admin-guide: add efi-stub.rst

[Daniel Pereira]

Add translation of efi-stub.rst to Portuguese and update
admin-guide/index.rst.

Signed-off-by: Daniel Pereira <danielmaraboo@gmail.com>
---
 .../pt_BR/admin-guide/efi-stub.rst            | 102 ++++++++++++++++++
 .../translations/pt_BR/admin-guide/index.rst  |   2 +-
 2 files changed, 103 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/translations/pt_BR/admin-guide/efi-stub.rst

diff --git a/Documentation/translations/pt_BR/admin-guide/efi-stub.rst b/Documentation/translations/pt_BR/admin-guide/efi-stub.rst
new file mode 100644
index 000000000..d21f134ab
--- /dev/null
+++ b/Documentation/translations/pt_BR/admin-guide/efi-stub.rst
@@ -0,0 +1,102 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=================
+O EFI Boot Stub
+=================
+
+Nas plataformas x86 e ARM, uma zImage/bzImage do kernel pode se passar por
+uma imagem PE/COFF, convencendo assim os carregadores de firmware EFI a
+carregá-la como um executável EFI. O código que modifica o cabeçalho da bzImage,
+juntamente com o ponto de entrada específico do EFI para o qual o carregador de
+firmware salta, são conhecidos coletivamente como o "EFI boot stub", e residem
+em arch/x86/boot/header.S e drivers/firmware/efi/libstub/x86-stub.c, respectivamente.
+Para ARM, o stub EFI é implementado em arch/arm/boot/compressed/efi-header.S e
+drivers/firmware/efi/libstub/arm32-stub.c. O código do stub EFI compartilhado
+entre arquiteturas está em drivers/firmware/efi/libstub.
+
+Para arm64, não há suporte a kernel compactado, portanto a própria Imagem se
+passa por uma imagem PE/COFF e o stub EFI é vinculado diretamente ao kernel. O
+stub EFI para arm64 reside em drivers/firmware/efi/libstub/arm64.c e
+drivers/firmware/efi/libstub/arm64-stub.c.
+
+Ao usar o EFI boot stub, é possível inicializar um kernel Linux sem o uso de um
+carregador de boot EFI convencional, como o grub ou elilo. Como o EFI boot stub
+desempenha as tarefas de um carregador de inicialização, em certo sentido ele *É*
+o carregador de inicialização.
+
+O EFI boot stub é ativado com a opção de kernel CONFIG_EFI_STUB.
+
+
+Como instalar bzImage.efi
+-------------------------
+
+A bzImage localizada em arch/x86/boot/bzImage deve ser copiada para a Partição
+de Sistema EFI (ESP - EFI System Partition) e renomeada com a extensão ".efi".
+Sem a extensão, o carregador de firmware EFI se recusará a executá-la. Não é
+possível executar bzImage.efi a partir dos sistemas de arquivos normais do Linux
+porque o firmware EFI não possui suporte para eles. Para ARM, a
+arch/arm/boot/zImage deve ser copiada para a partição de sistema e pode não
+precisar ser renomeada. Da mesma forma, para arm64, arch/arm64/boot/Image deve
+ser copiada, mas não necessariamente renomeada.
+
+
+Passando parâmetros do kernel a partir do shell EFI
+---------------------------------------------------
+
+Argumentos para o kernel podem ser passados após bzImage.efi, por exemplo::
+
+	fs0:> bzImage.efi console=ttyS0 root=/dev/sda4
+
+A opção "initrd="
+-----------------
+
+Como a maioria dos carregadores de inicialização, o stub EFI permite que o
+usuário especifique múltiplos arquivos initrd usando a opção "initrd=". Este é
+o único parâmetro de linha de comando específico do stub EFI; tudo o mais é
+passado para o kernel quando ele inicializa.
+
+O caminho para o arquivo initrd deve ser um caminho absoluto a partir do início
+da ESP; nomes de caminhos relativos não funcionam. Além disso, o caminho é no
+estilo EFI e os elementos de diretório devem ser separados com barras invertidas
+(\). Por exemplo, dada a seguinte estrutura de diretórios::
+
+  fs0:>
+	Kernels\
+			bzImage.efi
+			initrd-large.img
+
+	Ramdisks\
+			initrd-small.img
+			initrd-medium.img
+
+para inicializar com o arquivo initrd-large.img se o diretório de trabalho atual
+for fs0:\Kernels, o seguinte comando deve ser usado::
+
+	fs0:\Kernels> bzImage.efi initrd=\Kernels\initrd-large.img
+
+Observe como bzImage.efi pode ser especificado com um caminho relativo. Isso ocorre
+porque a imagem que estamos executando é interpretada pelo shell EFI, que entende
+caminhos relativos, enquanto o restante da linha de comando é passado para bzImage.efi.
+
+.. hint::
+   Também é possível fornecer um initrd usando um protocolo UEFI específico do
+   Linux no momento da inicialização. Consulte :ref:`pe-coff-entry-point` para
+   obter detalhes.
+
+A opção "dtb="
+--------------
+
+Para as arquiteturas ARM e arm64, uma árvore de dispositivos (device tree) deve ser
+fornecida ao kernel. Normalmente, o firmware deve fornecer a árvore de dispositivos
+através da EFI CONFIGURATION TABLE. No entanto, a opção de linha de comando "dtb="
+pode ser usada para sobrescrever a árvore de dispositivos fornecida pelo firmware
+ou para fornecer uma quando o firmware não puder fazê-lo.
+
+Observe: O firmware adiciona informações de configuração em tempo de execução à
+árvore de dispositivos antes de inicializar o kernel. Se dtb= for usado para
+sobrescrever a árvore de dispositivos, quaisquer dados em tempo de execução
+fornecidos pelo firmware serão perdidos. A opção dtb= deve ser usada apenas como
+uma ferramenta de depuração ou como último recurso quando uma árvore de dispositivos
+não for fornecida na EFI CONFIGURATION TABLE.
+
+"dtb=" é processado da mesma maneira que a opção "initrd=" descrita acima.
diff --git a/Documentation/translations/pt_BR/admin-guide/index.rst b/Documentation/translations/pt_BR/admin-guide/index.rst
index 40397ef77..f0f096a74 100644
--- a/Documentation/translations/pt_BR/admin-guide/index.rst
+++ b/Documentation/translations/pt_BR/admin-guide/index.rst
@@ -60,10 +60,10 @@ Inicializando o kernel
 
    bootconfig
    kernel-parameters
+   efi-stub
 
 Todolist:
 
-*   efi-stub
 *   initrd
 
 Rastreando e identificando problemas
-- 
2.47.3

Re: [PATCH 00/10] docs/translations/pt_BR: admin-guide: add multiple translations

[Jonathan Corbet]

Daniel Pereira <danielmaraboo@gmail.com> writes:

> This series adds Portuguese (pt_BR) translations for several documents
> in Documentation/admin-guide/, continuing the effort to expand the
> Brazilian Portuguese documentation in the Linux kernel:
>
> - features.rst
> - sysfs-rules.rst
> - sysctl/index.rst
> - cputopology.rst
> - hw-vuln/index.rst
> - LSM/index.rst
> - perf-security.rst
> - bootconfig.rst
> - kernel-parameters.rst
> - efi-stub.rst
>
> All documents were translated following the original documentation
> closely and keeping formatting, Sphinx directives and code blocks
> intact. The admin-guide/index.rst was updated alongside each translation,
> moving translated documents from Todolist into appropriate toctrees.
> All patches have been validated with checkpatch.pl and verified with
> 'make htmldocs'.

These add a huge set of warnings...?

  Documentation/translations/pt_BR/admin-guide/bootconfig:422: ./include/linux/bootconfig.h:31: WARNING: Duplicate C declaration, also defined at admin-guide/bootconfig:31.
+Declaration is '.. c:function:: uint32_t xbc_calc_checksum (const void *data, uint32_t size)'. [duplicate_declaration.c]
    Documentation/translations/pt_BR/admin-guide/bootconfig:422: ./include/linux/bootconfig.h:76: WARNING: Duplicate C declaration, also defined at admin-guide/bootconfig:76.

...lots more...

jon