Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documenting emulator debugging process with GDB #1415

Merged

Conversation

Projects
None yet
2 participants
@noureddine-as
Copy link
Contributor

commented May 10, 2018

This documents the process of debugging RISC-V programs running on the Emulator using the GNU debugger and OpenOCD in a similar manner as https://github.com/riscv/riscv-isa-sim#debugging-with-gdb .

#1339

Added emulator debugging with GDB documentation
This documents the process of debugging RISC-V programs against the GNU debugger with OpenOCD.
#1339

@mwachs5 mwachs5 self-requested a review May 10, 2018

@mwachs5

This comment has been minimized.

Copy link
Contributor

commented May 10, 2018

Thanks! I took a quick glance over and it looks good, I'll take a closer look shortly.

README.md Outdated
@@ -447,6 +448,181 @@ you can create your own Configuration(s) and compose them with Config's ++ opera

Then you can build as usual with CONFIG=MyConfig.

## <a name="debug"></a> Debugging with GDB

### 1) Generating the RBB emulator

This comment has been minimized.

Copy link
@mwachs5

mwachs5 May 11, 2018

Contributor

Can you update this to:

Generating the Remote Bit-Bang (RBB) Emulator

This comment has been minimized.

Copy link
@noureddine-as

noureddine-as May 11, 2018

Author Contributor

Done

README.md Outdated

### 1) Generating the RBB emulator

The objective of this section is to use GNU debugger to debug programs RISC-V programs running on the emulator in the same fashion as in [Spike](https://github.com/riscv/riscv-isa-sim#debugging-with-gdb).

This comment has been minimized.

Copy link
@mwachs5

mwachs5 May 11, 2018

Contributor

programs RISC-V programs (typo)

This comment has been minimized.

Copy link
@noureddine-as

noureddine-as May 11, 2018

Author Contributor

Done

@mwachs5
Copy link
Contributor

left a comment

Looks good, just some typo and rewording requests as noted in the Review

README.md Outdated

The objective of this section is to use GNU debugger to debug programs RISC-V programs running on the emulator in the same fashion as in [Spike](https://github.com/riscv/riscv-isa-sim#debugging-with-gdb).

For that we need to build a Remote Bit Bang enabled emulator, this could be any of the listed configurations in `rocket-chip/src/main/scala/system/Configs.scala`. Basically all we need is to extend our configuration with JtagDTMSystem that will deal with program loading and interface with the debugger. In the following example we added this extention to the DefaultConfig one.

This comment has been minimized.

Copy link
@mwachs5

mwachs5 May 11, 2018

Contributor

edited version:

For that we need to add a Remote Bit-Bang client to the emulator. We can do so by extending our Config with JtagDTMSystem, which will add a DebugTransportModuleJTAG to the DUT and connect a SimJTAG module in the Test Harness. This will allow OpenOCD to interface with the emulator, and GDB can interface with OpenOCD. In the following example we added this Config extension to the DefaultConfig:

This comment has been minimized.

Copy link
@noureddine-as

noureddine-as May 11, 2018

Author Contributor

Done

README.md Outdated

We can then launch the emulator with

./emulator-freechips.rocketchip.system-DefaultConfigRBB +jtag_rbb_enable=1 --rbb-port=9823 helloworld

This comment has been minimized.

Copy link
@mwachs5

mwachs5 May 11, 2018

Contributor

There is no real point to the helloworld argument to the emulator, because you load it later through the debugger. What happens if you leave it off?

This comment has been minimized.

Copy link
@mwachs5

mwachs5 May 11, 2018

Contributor

You should note that if you leave off the --rbb-port argument, a random port will be assigned.

This comment has been minimized.

Copy link
@noureddine-as

noureddine-as May 11, 2018

Author Contributor

Actually without the program argument, the emulator simply shows the help message.

This comment has been minimized.

Copy link
@noureddine-as

noureddine-as May 11, 2018

Author Contributor

Default RBB if no -rbb-port note added.

This comment has been minimized.

Copy link
@mwachs5

mwachs5 May 11, 2018

Contributor

Actually without the program argument, the emulator simply shows the help message.

Good to know. Maybe we should add a note here that it's not going to load your program, or that that argument doesn't matter, or use the term "dummy" ( I believe the latter is what the Debug Regressions actually do). Because it doesn't matter what you put there, since FESVR isn't attached it's not going to load that program.

This comment has been minimized.

Copy link
@noureddine-as

noureddine-as May 11, 2018

Author Contributor

Okay. I prefer to let the helloworld there so that new people don't get confused when they don't use RBB or something, but notified the fact that it is loaded from GDB (in contrast with Spike) and that's it's a dummy arg. Thanks for clarification.

README.md Outdated

### 4) Launch OpenOCD

We first need to ensure the OpenOCD has been generated. Generally it is in `$(RISCV)/bin/openocd`. We then define a configuration file that is going to define the RBB port we will use, which is in our case `9823`.

This comment has been minimized.

Copy link
@mwachs5

mwachs5 May 11, 2018

Contributor

Edited version:

You will need a RISC-V Enabled OpenOCD binary. This is installed with riscv-tools in $(RISCV)/bin/openocd, or can be compiled manually from riscv-openocd. OpenOCD requires a configuration file, in which we define the RBB port we will use, which is in our case 9823.

This comment has been minimized.

Copy link
@noureddine-as

noureddine-as May 11, 2018

Author Contributor

Done

README.md Outdated
Then we launch OpenOCD in another terminal using the command
$ openocd -f ./cemulator.cfg

This comment has been minimized.

Copy link
@mwachs5

mwachs5 May 11, 2018

Contributor

please use the full path $(RISCV)/bin/openocd. This is a common mistake.

This comment has been minimized.

Copy link
@mwachs5

mwachs5 May 11, 2018

Contributor

You can also suggest adding the -d flag for debug info

This comment has been minimized.

Copy link
@noureddine-as

noureddine-as May 11, 2018

Author Contributor

Done.

README.md Outdated
### 5) Launch GDB
Launch GDB in another terminal using

This comment has been minimized.

Copy link
@mwachs5

mwachs5 May 11, 2018

Contributor

Launch GDB in another terminal and point to the elf file you would like to load & run with the debugger (in this example, helloworld):

This comment has been minimized.

Copy link
@noureddine-as

noureddine-as May 11, 2018

Author Contributor

Done.

README.md Outdated
Reading symbols from ./proj1.out...done.
(gdb)
Compared to Spike, the C Emulator is very slow, so several problems are encountered due to timeouts between issuing commands and response from the emulator. Thats why we should increase the `remotetimeout`.

This comment has been minimized.

Copy link
@mwachs5

mwachs5 May 11, 2018

Contributor

Edited version:

Compared to Spike, the C Emulator is very slow, so several problems may be encountered due to timeouts between issuing commands and response from the emulator. To solve this problem, we increase the timeout with the GDB remotetimeout command.

This comment has been minimized.

Copy link
@mwachs5

mwachs5 May 11, 2018

Contributor

Also you could provide a link to the GDB documentation of this command.

This comment has been minimized.

Copy link
@noureddine-as

noureddine-as May 11, 2018

Author Contributor

Done + useful links added.

README.md Outdated
Compared to Spike, the C Emulator is very slow, so several problems are encountered due to timeouts between issuing commands and response from the emulator. Thats why we should increase the `remotetimeout`.
After that we load our program by performing a `load` command.

This comment has been minimized.

Copy link
@mwachs5

mwachs5 May 11, 2018

Contributor

You may want to note "This automatically sets the $pc to the _start symbol in our .elf file.

This comment has been minimized.

Copy link
@noureddine-as

noureddine-as May 11, 2018

Author Contributor

Added.

README.md Outdated
Now we can proceed as with Spike, debugging works in a similar way:
(gdb) target remote localhost:3333

This comment has been minimized.

Copy link
@mwachs5

mwachs5 May 11, 2018

Contributor

you don't need to target remote localhost again, you did that step above.

This comment has been minimized.

Copy link
@mwachs5

mwachs5 May 11, 2018

Contributor

Actually I'm not sure how you got from the previous step to this one. You're missing a "c" or "set breakpoint" or something.

This comment has been minimized.

Copy link
@noureddine-as

noureddine-as May 11, 2018

Author Contributor

Yeah, I actually just copied that again, sorry. Adjusted now.

(gdb) print text
$5 = "Instruction sets want to be free!"
(gdb)

This comment has been minimized.

Copy link
@mwachs5

mwachs5 May 11, 2018

Contributor

I think you should add a note either here or at the beginning that will note what to do to make it waveform-enabled (building the -debug emulator target)

This comment has been minimized.

Copy link
@noureddine-as

noureddine-as May 11, 2018

Author Contributor

Added in 1).

  • Pointed out the fact that VCD waveforms can be voluminous depending on program size.
  • I'll add a section for executable stripping may be? I guess it affects the execution time, do you agree @mwachs5 ?.

This comment has been minimized.

Copy link
@mwachs5

mwachs5 May 11, 2018

Contributor

Well, the program size and duration. I don't think it's really that relevant, people already know that VCD waveforms can be big and scale with runtime, so I woudl probably remove both those notes.

This comment has been minimized.

Copy link
@noureddine-as

noureddine-as May 11, 2018

Author Contributor

You're right experienced people could already know this. But when it comes to beginners discovering all these tools, it is not the case. An example is a friend who tried to boot BBL (that has now several MiB of size) and he thought it just doesn't work, but he found out that it just takes hours to run. In these cases gaining more space means gaining hours of waiting.
Anyway, I didn't test it personally. Is it the case normally?

This comment has been minimized.

Copy link
@mwachs5

mwachs5 May 11, 2018

Contributor

I mean, the larger program -> longer runtime is sort of orthogonal to longer runtime -> larger VCD file. So if you want to point out that it's going to be very slow to load a large program this way, I would separate it from the note that the generated waveforms with the -debug version of emulator may be large.

This comment has been minimized.

Copy link
@noureddine-as

noureddine-as May 12, 2018

Author Contributor

I understand your point of view and I agree.
As you said VCD size increase is trivial. Though, I pointed out the relation {larger program -> longer runtime} and how to reduce it as well as how to test the program on the emulator event after beginning debugging.
Again, I know these are basic ideas, but documenting can save new people some time to understand what's going on.
Thanks a lot.

This comment has been minimized.

Copy link
@noureddine-as

noureddine-as May 15, 2018

Author Contributor

I guess it's okay now. Any other recommendations @mwachs5 ?

@noureddine-as

This comment has been minimized.

Copy link
Contributor Author

commented May 11, 2018

Thanks for your reviews @mwachs5, I'll get back very soon to perform modifications.

noureddine-as added some commits May 11, 2018

Review 1 by Megan.
review 1
testing programs on emulator + reducing size ideas
+ Pointed out that {more size --> more execution time} and a solution.
+ Separated simple programs execution and testing (step 2) of program debugging (step 3): To illustrate the fact that custom programs can be run on the emulator too not only the benchmarks.
README.md Outdated

$ ./emulator-freechips.rocketchip.system-DefaultConfig +verbose helloworld 2>&1 | spike-dasm

Please note that execution time of the program on the emulator depends on executable size. Stripping the .elf executable will unsurprisingly make it run faster. For this you can use `$RISCV/bin/riscv64-unknown-elf-strip` tool to reduce the size. This is good for accelerating execution but not for debugging. Keep in mind that the HTIF communication interface between our system and the emulator relies on `tohost` and `fromhost` symbols to communicate. This is why you may get the following error when you try to run a totally stripped executable on the emulator:

This comment has been minimized.

Copy link
@mwachs5

mwachs5 May 15, 2018

Contributor

Now this note (about the size and stripping) exist in two places. Maybe you should remove the first one and keep this one?

This comment has been minimized.

Copy link
@mwachs5

mwachs5 May 15, 2018

Contributor

Also, minor nit, it's not really the execution time of the program, but the time it takes the emulator to load your program that depends on the size. Minor rewording would be:

Please note that the time it takes the emulator to load your program depends on executable size. Stripping the .elf executable will unsurprisingly make it run faster. For this you can use $RISCV/bin/riscv64-unknown-elf-strip tool to reduce the size. This is good for accelerating your simulation but not for debugging. Keep in mind that the HTIF communication interface between our system and the emulator relies on tohost and fromhost symbols to communicate. This is why you may get the following error when you try to run a totally stripped executable on the emulator:

This comment has been minimized.

Copy link
@mwachs5

mwachs5 May 15, 2018

Contributor

Actually, I re-read your justification for the two notes above, so if you want to keep the other note about VCD waveform size that's fine.

This comment has been minimized.

Copy link
@noureddine-as

noureddine-as May 15, 2018

Author Contributor

Thanks Megan. I rearranged the idea in the 'Compiling and executing' part. I also deleted redundancies. Added also an example of using the -debug version.
I guess the text is now more coherent.
Thank you for the reviews. Glad to participate :)

@mwachs5

This comment has been minimized.

Copy link
Contributor

commented May 15, 2018

Looks good! If you make the two suggested changes I will happily merge.

Modifications
Added an example command of VCD output + log file generation
Rearranged VCD size idea into the part where I talk about executing/testing
Cleaned redundancies
@mwachs5
Copy link
Contributor

left a comment

I'll merge once it passes Travis. Thanks!

@noureddine-as

This comment has been minimized.

Copy link
Contributor Author

commented May 15, 2018

Thank you Megan!

Best reagards.

@noureddine-as

This comment has been minimized.

Copy link
Contributor Author

commented May 16, 2018

@mwachs5 I see that Travis checks have failed this time, what happened? I didn't modify any other things besides README !

https://travis-ci.org/freechipsproject/rocket-chip/builds/379406404?utm_source=github_status&utm_medium=notification

@mwachs5

This comment has been minimized.

Copy link
Contributor

commented May 16, 2018

It was some sort of Travis timeout, perhaps the server was overloaded. I'll just restart the regression.

@mwachs5 mwachs5 merged commit 3306967 into freechipsproject:master May 16, 2018

1 check passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details

@wsong83 wsong83 referenced this pull request May 21, 2018

Merged

bi-weekly 2018-05-25 #77

16 of 18 tasks complete
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.