[PATCH] docs: translations: pt_BR: translate gdb-kernel-debugging

[Giovanna Macedo Cox <giovannamccds@gmail.com>]

Translate gdb-kernel-debugging to Brazilian Portuguese
and add toctree section in index.

Signed-off-by: Giovanna Macedo Cox <giovannamccds@gmail.com>
---
 .../debugging/gdb-kernel-debugging.rst        | 187 ++++++++++++++++++
 .../pt_BR/process/debugging/index.rst         |   6 +-
 2 files changed, 192 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/translations/pt_BR/process/debugging/gdb-kernel-debugging.rst

diff --git a/Documentation/translations/pt_BR/process/debugging/gdb-kernel-debugging.rst b/Documentation/translations/pt_BR/process/debugging/gdb-kernel-debugging.rst
new file mode 100644
index 000000000..cc1146aea
--- /dev/null
+++ b/Documentation/translations/pt_BR/process/debugging/gdb-kernel-debugging.rst
@@ -0,0 +1,187 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. highlight:: none
+
+Depuração do kernel e módulos via gdb
+=====================================
+
+O depurador de kernel kgdb, hipervisores como o QEMU ou interfaces de
+hardware baseadas em JTAG permitem depurar o kernel do Linux e seus módulos
+durante a execução utilizando o gdb. O gdb vem com um poderoso script de
+interface python. O kernel fornece uma coleção de scripts de ajuda que
+podem simplificar passos de depuração típicos do kernel. Este é um pequeno
+tutorial sobre como habilitar e usá-los. Ele se concentra em máquinas
+virtuais QEMU/KVM como destino, mas os exemplos também podem ser adaptados
+para outros stubs do gdb.
+
+Requisitos
+----------
+
+- gdb 7.2+ (recomendado: 7.4+) com suporte python habilitado (normalmente
+  habilitados em distribuições)
+
+Configurações:
+--------------
+
+- Crie uma máquina virtual Linux para QEMU/KVM (veja www.linux-kvm.org
+  www.qemu.org para mais detalhes). Para desenvolvimento cruzado,
+  https://landley.net/aboriginal/bin mantém um conjunto de imagens de
+  máquinas e conjuntos de ferramentas que podem ser úteis como ponto de
+  partida.
+
+- Construa (Build) o kernel com CONFIG_GDB_SCRIPTS habilitado, mas deixe
+  CONFIG_DEBUG_INFO_REDUCED desabilitado. Se sua arquitetura suportar
+  CONFIG_FRAME_POINTER, mantenha habilitado.
+
+- Instale esse kernel no sistema convidado e desative o KASLR se
+  necessário, adicionando “nokaslr” à linha de comando do kernel. Como
+  alternativa, o QEMU permite inicializar o kernel diretamente
+  usando -kernel, -append, -initrd troca de comando de linha. Isso é
+  geralmente usado apenas se você não depender de módulos. Veja a
+  documentação QEMU para mais detalhes sobre esse modo. Nesse caso,
+  você deve construir(Build) o kernel com CONFIG_RANDOMIZE_BASE
+  desabilitado se a arquitetura suportar KASLR.
+
+- Construa os scripts gdb(necessário no kernel v5.1 ou superior)
+
+        - Crie scripts_gdb
+
+- Habilite o stub gdb do QEMU/KVM, seja
+
+    - No momento da inicialização da VM adicione "-s" na linha de
+      comando QEMU
+
+  ou
+
+    - durante o tempo de execução, digitando "gdbserver" no console de
+      monitor QEMU
+
+- cd /path/to/linux-build
+
+- Inicie a gdb: gdb vmlinux
+
+    Observação: algumas distribuições podem restringir o carregamento
+    automático de scripts do gdb a diretórios conhecidos como seguros.
+    Caso o gdb informe que se recusa a carregar o vmlinux-gdb.py,
+    adicione::
+
+        add-auto-load-safe-path /path/to/linux-build
+
+    Para ~/.gdbinit. Veja gdb help para mais detalhes.
+
+- Conecte-se ao sistema convidado já inicializado::
+
+    (gdb) target remote :1234
+
+Exemplos de uso do Linux-provided gdb helpers
+----------------------------------------------
+
+- Carregue os símbolos do módulo (e do kernel principal)::
+
+    (gdb) lx-symbols
+    loading vmlinux
+    scanning for modules in /home/user/linux/build
+    loading @0xffffffffa0020000: /home/user/linux/build/net/netfilter/xt_tcpudp.ko
+    loading @0xffffffffa0016000: /home/user/linux/build/net/netfilter/xt_pkttype.ko
+    loading @0xffffffffa0002000: /home/user/linux/build/net/netfilter/xt_limit.ko
+    loading @0xffffffffa00ca000: /home/user/linux/build/net/packet/af_packet.ko
+    loading @0xffffffffa003c000: /home/user/linux/build/fs/fuse/fuse.ko
+    ...
+    loading @0xffffffffa0000000: /home/user/linux/build/drivers/ata/ata_generic.ko
+
+- Defina um ponto de interrupção em alguma função de um módulo que ainda
+  não foi carregado, por exemplo::
+
+    (gdb) b btrfs_init_sysfs
+    Function "btrfs_init_sysfs" not defined.
+    Make breakpoint pending on future shared library load? (y or [n]) y
+    Breakpoint 1 (btrfs_init_sysfs) pending.
+
+- Continue com o alvo::
+
+    (gdb) c
+
+- Carregue o módulo no alvo e veja os símbolos serem carregados, bem como o
+  ponto de interrupção sendo acionado::
+
+    loading @0xffffffffa0034000: /home/user/linux/build/lib/libcrc32c.ko
+    loading @0xffffffffa0050000: /home/user/linux/build/lib/lzo/lzo_compress.ko
+    loading @0xffffffffa006e000: /home/user/linux/build/lib/zlib_deflate/zlib_deflate.ko
+    loading @0xffffffffa01b1000: /home/user/linux/build/fs/btrfs/btrfs.ko
+
+    Breakpoint 1, btrfs_init_sysfs () at /home/user/linux/fs/btrfs/sysfs.c:36
+    36              btrfs_kset = kset_create_and_add("btrfs", NULL, fs_kobj);
+
+- Descarregue o buffer de log do kernel de destino::
+
+    (gdb) lx-dmesg
+    [     0.000000] Initializing cgroup subsys cpuset
+    [     0.000000] Initializing cgroup subsys cpu
+    [     0.000000] Linux version 3.8.0-rc4-dbg+ (...
+    [     0.000000] Command line: root=/dev/sda2 resume=/dev/sda1 vga=0x314
+    [     0.000000] e820: BIOS-provided physical RAM map:
+    [     0.000000] BIOS-e820: [mem 0x0000000000000000-0x000000000009fbff] usable
+    [     0.000000] BIOS-e820: [mem 0x000000000009fc00-0x000000000009ffff] reserved
+    ....
+
+- Examinar os campos da estrutura da tarefa atual (compatível apenas com
+  x86 e arm64)::
+
+    (gdb) p $lx_per_cpu(runqueues).nr_running
+    $3 = 1
+    (gdb) p $lx_per_cpu(runqueues, 2).nr_running
+    $4 = 0
+
+- Explore os hrtimers usando o auxiliar `container_of`::
+
+    (gdb) set $leftmost = $lx_per_cpu(hrtimer_bases).clock_base[0].active.rb_root.rb_leftmost
+    (gdb) p *$container_of($leftmost, "struct hrtimer", "node")
+    $5 = {
+      node = {
+        node = {
+          __rb_parent_color = 18446612686384860673,
+          rb_right = 0xffff888231da8b00,
+          rb_left = 0x0
+        },
+        expires = 1228461000000
+      },
+      _softexpires = 1228461000000,
+      function = 0xffffffff8137ab20 <tick_nohz_handler>,
+      base = 0xffff888231d9b4c0,
+      state = 1 '\001',
+      is_rel = 0 '\000',
+      is_soft = 0 '\000',
+      is_hard = 1 '\001'
+    }
+
+Lista de comandos e funções
+---------------------------
+
+O número de comandos e funções úteis pode mudar com o tempo; esta é apenas
+uma visão geral da versão inicial::
+
+ (gdb) apropos lx
+ função lx_current -- Voltar à tarefa atual
+ função lx_module -- Encontrar o módulo pelo nome e retornar a variável
+ do módulo
+ função lx_per_cpu -- Retorna a variável por CPU
+ função lx_task_by_pid -- Localiza uma tarefa do Linux pelo PID e retorna a
+ variável `task_struct`
+ função lx_thread_info -- Calcula as informações da thread do Linux a
+ partir da variável da tarefa
+ lx-dmesg -- Exibe o buffer de log do kernel do Linux
+ lx-lsmod -- Lista os módulos carregados no momento
+ lx-symbols -- (Re)carrega os símbolos do kernel do Linux e dos módulos
+ carregados no momento
+
+Detalhes da ajuda podem ser obtidos por "help <command-name>" para
+comandos e "help function <function-name>" para funções.
+
+Depuração de scripts GDB
+------------------------
+
+O GDB não permite um backtrace completo do Python, o que pode tornar a
+depuração de scripts do GDB mais difícil do que o necessário. O código a
+seguir permitirá exibir um backtrace completo do ambiente Python::
+
+ (gdb) set python print-stack full
diff --git a/Documentation/translations/pt_BR/process/debugging/index.rst b/Documentation/translations/pt_BR/process/debugging/index.rst
index b223fae34..179d1a1e3 100644
--- a/Documentation/translations/pt_BR/process/debugging/index.rst
+++ b/Documentation/translations/pt_BR/process/debugging/index.rst
@@ -7,10 +7,14 @@ Dicas de depuração para desenvolvedores do Kernel Linux
 Guias gerais
 ------------
 
+.. toctree::
+    :maxdepth: 1
+
+    Guia de depuração do kernel com gdb <gdb-kernel-debugging>
+
 Todolist:
 
 *   driver_development_debugging_guide
-*   gdb-kernel-debugging
 *   kgdb
 *   userspace_debugging_guide
 
-- 
2.55.0