Update Ravenscar documentation

This documents some recent Ravenscar changes, and further documents
the known limitation where stepping through the runtime initialization
code does not work properly.

gdb/doc/ChangeLog
2020-08-07  Tom Tromey  <tromey@adacore.com>

	* gdb.texinfo (Ravenscar Profile): Add examples.
	Document runtime initialization limitation.

diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog
index 7d17b01c37471250db339f250c788af3daf4cf95..cddcdaab2c8fde6205ddeb247491c8ef6cdbd0fc 100644 (file)
--- a/gdb/doc/ChangeLog
+++ b/gdb/doc/ChangeLog
@@ -1,3 +1,8 @@
+2020-08-07  Tom Tromey  <tromey@adacore.com>
+
+       * gdb.texinfo (Ravenscar Profile): Add examples.
+       Document runtime initialization limitation.
+
 2020-08-04  Jose E. Marchesi  <jose.marchesi@oracle.com>
 
        * gdb.texinfo (Contributors): Add information for the eBPF

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 09317fa0bd03b62ebcace4e14c9235a24b8b5f85..77013648b2f3e8aca1f34994c8066de746fd9fb2 100644 (file)
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -18320,6 +18320,34 @@ using the Ravenscar Profile.
 
 @end table
 
+@cindex Ravenscar thread
+When Ravenscar task-switching is enabled, Ravenscar tasks are
+announced by @value{GDBN} as if they were threads:
+
+@smallexample
+(gdb) continue
+[New Ravenscar Thread 0x2b8f0]
+@end smallexample
+
+Both Ravenscar tasks and the underlying CPU threads will show up in
+the output of @code{info threads}:
+
+@smallexample
+(gdb) info threads
+  Id   Target Id                  Frame
+  1    Thread 1 (CPU#0 [running]) simple () at simple.adb:10
+  2    Thread 2 (CPU#1 [running]) 0x0000000000003d34 in __gnat_initialize_cpu_devices ()
+  3    Thread 3 (CPU#2 [running]) 0x0000000000003d28 in __gnat_initialize_cpu_devices ()
+  4    Thread 4 (CPU#3 [halted ]) 0x000000000000c6ec in system.task_primitives.operations.idle ()
+* 5    Ravenscar Thread 0x2b8f0   simple () at simple.adb:10
+  6    Ravenscar Thread 0x2f150   0x000000000000c6ec in system.task_primitives.operations.idle ()
+@end smallexample
+
+One known limitation of the Ravenscar support in @value{GDBN} is that
+it isn't currently possible to single-step through the runtime
+initialization sequence.  If you need to debug this code, you should
+use @code{set ravenscar task-switching off}.
+
 @node Ada Settings
 @subsubsection Ada Settings
 @cindex Ada settings