# Navigation

This module assumes you know how to launch `termmines` in Ghidra using GDB, and know where to find the basic Debugger GUI components.
It also assumes you are familiar with the concepts of breakpoints and machine state in Ghidra.
If not, please refer to the previous modules.

This module will address the following features in more depth:

* The Trace tabs &mdash; in the Dynamic Listing window
* The Threads window
* The Stack window
* The Time window

## Coordinates

The term *location* is already established in Ghidra to refer to the current program and current address.
There are more elements to a "location" in a dynamic session, so we add additional elements to form the concept of your current *coordinates*.
All of these elements can affect the information displayed in other windows, especially those dealing with machine state.

* The current *trace*.
  A trace database is where all of the Debugger windows (except Connections and Terminal) gather their information.
  It is the analog of the program database, but for dynamic analysis.
* The current *thread*.
  A thread is a unit of execution, either a processor core or a platform-defined virtual thread.
  Each thread has its own register context.
  In Ghidra, this means each has its own instance of the processor specification's "register" space.
* The current *frame*.
  A frame is a call record on the stack.
  For example, `main` may call `getc`, which may in turn call `read`.
  If you wish to examine the state of `main`, you would navigate 2 frames up the stack.
  Because functions often save registers to the stack, the back-end debugger may "unwind" the stack and present the restored registers.
* The current *time*.
  In general, time refers to the current snapshot.
  Whenever the target becomes suspended, Ghidra creates a snapshot in the current trace.
  If you wish to examine the machine state at a previous time, you would navigate to an earlier snapshot.
  "Time" may also include steps of emulation, but that is covered in the [Emulation](B2-Emulation.md) module.

In general, there is a window dedicated to navigating each element of your current coordinates.
If you do not have an active session already, launch `termmines`.

## Trace Tabs

The Dynamic Listing window has a row of tabs at the very top.
This is a list of open traces, i.e., of targets you are debugging.
You can also open old traces to examine a target's machine state *post mortem*.
In general, you should only have one trace open at a time, but there are use cases where you might have multiple.
For example, you could debug both the client and server of a network application.
To switch to another trace, single-click its tab.

When you switch traces, every Debugger window that depends on the current trace will update.
That's every window except Connections and Terminal.
(Each connection has its own Terminal windows.)
The Breakpoints window may change slightly, depending on its configuration, because it is designed to present all breakpoints in the session.

## Threads

![Threads window](images/Navigation_ThreadsInCallRand.png)

The Threads window displays a list of all threads ever observed in the target.
This includes threads which have been terminated.
Unfortunately, `termmines` is a single-threaded application, so you will only see one row.
If there were more, you could switch to a different thread by double-clicking it in the table.
The columns are:

* The **Name** column gives the name of the thread.
  This may include the back-end debugger's thread id, the target platform's system thread id, and/or the back-end debugger's display text for the thread.
* The **PC** column gives the program counter of the thread.
* The **Function** column gives the function from a mapped program database containing the program counter.
* The **State** column gives the state of the thread.
  This may be one of ALIVE, RUNNING, STOPPED, TERMINATED, or UNKNOWN.
* The **Plot** column plots the threads' life spans in a chart.

**NOTE**: Most of the time, switching threads will also change what thread is being controlled by the Control actions in the global toolbar.
This may vary subtly, depending on the action and the target.
For example, the ![resume](images/resume.png) Resume button will usually allow all threads to execute; whereas the ![step into](images/stepinto.png) Step Into button will usually step only the current thread.
If the target's thread scheduler cannot schedule your current thread, the behavior is not clearly defined:
It may step a different thread, it may cause the target to block until the thread can be scheduled, or it may do something else.

When you switch threads, everything that depends on the current thread may change, in particular the Stack window and any machine-state window that involves register values.
The Registers window will display the values for the new thread, the Watches window will re-evaluate all expressions, and the Dynamic Listing and Memory views may seek to different addresses, depending on their location tracking configurations.

## Stack

Ensure your breakpoint on `rand` is enabled, and resume until you hit it.

![Stack window](images/Navigation_StackInCallRand.png)

The stack window displays a list of all the frames for the current thread.
Each thread has its own execution stack, so the frame element is actually dependent on the thread element.
The call records are listed from innermost to outermost.
Here, `main` has called an unnamed function, which has in turn called `rand`.
The columns are:

* The **Level** column gives the frame number.
  This is the number of calls that must be unwound from the current machine state to reach the frame.
* The **PC** column gives the address of the next instruction in that frame.
  The PC of frame 0 is the value of the PC register.
  Then, the PC of frame 1 is the return address of frame 0, and so on.
* The **Function** column gives the name of the function containing the PC mapped to its static program database, if available.
* The **Module** column gives the name of the module containing the PC.

Double-click the row with the unnamed function (frame 1) to switch to it.
When you switch frames, any machine-state window that involves register values may change.
**NOTE**: Some back-end debuggers do not recover register values when unwinding stack frames.
For those targets, some windows may display stale meaningless values in frames other than 0.

### Exercise: Name the Function

Your Dynamic and Static Listings should now be in the unknown function.
If you have not already done so, reverse engineer this function and give it a name.

## Time

Re-launch `termmines`, ensure both of your breakpoints at `srand` and `rand` are enabled, and resume until you hit `rand`, then step out.
Now, switch to the Time window.

![Time window](images/Navigation_TimeAfterCallSRandCallRand.png)

It displays a list of all the snapshots for the current trace.
In general, every pause generates a snapsho