diff mbox series

[v2,9/9] GDB: doc: Document Linux AArch64 support for Guarded Control Stacks

Message ID 20250618055445.709416-10-thiago.bauermann@linaro.org
State New
Headers show
Series AArch64 Guarded Control Stack support | expand

Commit Message

Thiago Jung Bauermann June 18, 2025, 5:54 a.m. UTC 
Add NEWS entry and new sections to the "Configuration-Specific Information"
and "Standard Target Features" parts of the manual.

---
 gdb/NEWS            |  3 ++
 gdb/doc/gdb.texinfo | 83 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 86 insertions(+)

I didn't include Eli's Reviewed-by in this version because there were a few
additions to the manual since v1.

Changes since v1:
- Reword 1st paragraph of GCS configuration-specific section to make it
  clear that the special registers are only available on the Linux kernel
  (suggested by Luis).
- Describe flags in the custom flags type used for the GCSPR in the GCS
  feature section (suggested by Luis).
- Fix NEWS wording from "are now supported" to "is now supported".

Comments

Eli Zaretskii June 18, 2025, 12:04 p.m. UTC | #1 
> From: Thiago Jung Bauermann <thiago.bauermann@linaro.org>
> Cc: Eli Zaretskii <eliz@gnu.org>,
> 	"Schimpe, Christina" <christina.schimpe@intel.com>,
> 	Luis Machado <luis.machado@arm.com>
> Date: Wed, 18 Jun 2025 02:54:45 -0300
> 
> Add NEWS entry and new sections to the "Configuration-Specific Information"
> and "Standard Target Features" parts of the manual.
> 
> ---
>  gdb/NEWS            |  3 ++
>  gdb/doc/gdb.texinfo | 83 +++++++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 86 insertions(+)

Thanks, this patch in the series is okay, with the following minor
nits:

> +Naturally the Guarded Control Stack pointer at EL0 is also available,
> +as the @code{gcspr} register.

I guess @code{EL0}, since it's the name of a register?

> +The custom flags type allows GDB to print a human-friendly
                                ^^^
@value{GDBN}.

Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Thiago Jung Bauermann June 18, 2025, 7:48 p.m. UTC | #2 
Eli Zaretskii <eliz@gnu.org> writes:

>> From: Thiago Jung Bauermann <thiago.bauermann@linaro.org>
>> Cc: Eli Zaretskii <eliz@gnu.org>,
>> 	"Schimpe, Christina" <christina.schimpe@intel.com>,
>> 	Luis Machado <luis.machado@arm.com>
>> Date: Wed, 18 Jun 2025 02:54:45 -0300
>> 
>> Add NEWS entry and new sections to the "Configuration-Specific Information"
>> and "Standard Target Features" parts of the manual.
>> 
>> ---
>>  gdb/NEWS            |  3 ++
>>  gdb/doc/gdb.texinfo | 83 +++++++++++++++++++++++++++++++++++++++++++++
>>  2 files changed, 86 insertions(+)
>
> Thanks, this patch in the series is okay, with the following minor
> nits:
>
>> +Naturally the Guarded Control Stack pointer at EL0 is also available,
>> +as the @code{gcspr} register.

I agree. Fixed.

> I guess @code{EL0}, since it's the name of a register?
>
>> +The custom flags type allows GDB to print a human-friendly
>                                 ^^^
> @value{GDBN}.

Fixed.

> Reviewed-By: Eli Zaretskii <eliz@gnu.org>

Thank you! I made these changes in my local branch and they'll appear
either in v3 or when committing the patches, if v2 is approved.
diff mbox series

Patch

diff --git a/gdb/NEWS b/gdb/NEWS
index 4dcc344b0727..54a61f0e87b3 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -48,6 +48,9 @@ 
 
 * Add record full support for rv64gc architectures
 
+* Debugging Linux programs that use AArch64 Guarded Control Stacks is now
+  supported.
+
 * New commands
 
 maintenance check psymtabs
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index c41aa89a3c48..2bf20ad06230 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -26992,6 +26992,32 @@  information automatically from the core file, and will show one of the above
 messages depending on whether the synchronous or asynchronous mode is selected.
 @xref{Memory Tagging}. @xref{Memory}.
 
+@subsubsection AArch64 Guarded Control Stack
+@cindex Guarded Control Stack, AArch64
+@cindex GCS, AArch64
+
+When @value{GDBN} is debugging the AArch64 architecture, the program is
+using the feature Guarded Control Stack (GCS), the operating system kernel
+is Linux and it supports GCS, @value{GDBN} will make a couple of special
+registers --- @code{gcs_features_enabled} and @code{gcs_features_locked}
+--- available through the @code{org.gnu.gdb.aarch64.gcs.linux} feature.
+These registers expose some options that can be controlled at runtime and
+emulate the @code{prctl} option @code{PR_SET_SHADOW_STACK_STATUS}.  For
+further information, see the
+@uref{https://www.kernel.org/doc/html/latest/arch/arm64/gcs.html,ignored,
+documentation} in the Linux kernel.
+
+Naturally the Guarded Control Stack pointer at EL0 is also available,
+as the @code{gcspr} register.
+
+To aid debugging, @value{GDBN} will note when SIGSEGV signals are generated
+as a result of a Guarded Control Stack error:
+
+@smallexample
+Program received signal SIGSEGV, Segmentation fault
+Guarded Control Stack error.
+@end smallexample
+
 @node x86
 @subsection x86
 
@@ -49505,6 +49531,63 @@  of bytes.
 Extra registers are allowed in this feature, but they will not affect
 @value{GDBN}.
 
+@subsubsection AArch64 GCS registers feature
+
+The @samp{org.gnu.gdb.aarch64.gcs} feature is optional.  If present, it
+means the target supports Guarded Control Stacks and must contain the
+following register:
+
+@itemize @minus
+
+@item
+@code{gcspr}, which points to the thread's Guarded Control Stack.  It is 64
+bits in size and has a type of @samp{data_ptr}.
+
+@end itemize
+
+The @samp{org.gnu.gdb.aarch64.gcs.linux} feature is optional.  If present,
+then the @samp{org.gnu.gdb.aarch64.gcs} feature must also be present.  The
+@samp{org.gnu.gdb.aarch64.gcs.linux} feature represents facilities provided
+by the Linux kernel for GCS support and should contain the following:
+
+@itemize @minus
+
+@item
+@code{gcs_features_enabled} shows the features currently enabled via the
+prctl or ptrace system calls.  It is represented as if it were a 64-bit
+register with a custom flags type.
+
+@item
+@code{gcs_features_locked} shows the features currently locked via the
+prctl or ptrace system calls.  It is represented as if it were a 64-bit
+register with a custom flags type.
+
+@end itemize
+
+The custom flags type allows GDB to print a human-friendly
+representation of the contents of @code{gcs_features_enabled} and
+@code{gcs_features_locked} and should contain:
+
+@itemize @minus
+
+@item
+@code{PR_SHADOW_STACK_ENABLE}
+
+@item
+@code{PR_SHADOW_STACK_WRITE}
+
+@item
+@code{PR_SHADOW_STACK_PUSH}
+
+@end itemize
+
+For further information, see the
+@uref{https://www.kernel.org/doc/html/latest/arch/arm64/gcs.html,ignored,
+documentation} in the Linux kernel.
+
+Extra registers are allowed in these features, but they will not affect
+@value{GDBN}.
+
 @node ARC Features
 @subsection ARC Features
 @cindex target descriptions, ARC Features