[RFA,8/8] Update Ravenscar documentation
Commit Message
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
> 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.
@@ -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