diff mbox

[RFA,8/8] Update Ravenscar documentation

Message ID 20190326144404.6670-9-tromey@adacore.com
State New, archived
Headers

Commit Message

Tom Tromey March 26, 2019, 2:44 p.m. UTC 
  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
2019-03-26  Tom Tromey  <tromey@adacore.com>

	* gdb.texinfo (Ravenscar Profile): Add examples.
	Document runtime initialization limitation.
---
 gdb/doc/ChangeLog   |  5 +++++
 gdb/doc/gdb.texinfo | 27 +++++++++++++++++++++++++++
 2 files changed, 32 insertions(+)

Comments

Eli Zaretskii March 26, 2019, 4:07 p.m. UTC | #1 
> From: Tom Tromey <tromey@adacore.com>
> Cc: Tom Tromey <tromey@adacore.com>
> Date: Tue, 26 Mar 2019 08:44:04 -0600
> 
> 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
> 2019-03-26  Tom Tromey  <tromey@adacore.com>
> 
> 	* gdb.texinfo (Ravenscar Profile): Add examples.
> 	Document runtime initialization limitation.

This is okay, but I think we should have an index entry for this text,
something like

  @cindex Ravenscar thread

I'm thinking about a user who sees that "[New Ravenscar Thread
0x2b8f0]" announcement and wonders what is that about.

Thanks.
diff mbox

Patch

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 4c1d5e8294f..4d7f510f300 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -17298,6 +17298,33 @@  using the Ravenscar Profile.
 
 @end table
 
+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