Documentation | Draft: Add section "Debugging" to RTEMS documentation (!43)

[Christian Mauderer (@c-mauderer)]

Merge request https://gitlab.rtems.org/rtems/docs/rtems-docs/-/merge_requests/43 was reviewed by Christian Mauderer

--
  
Christian Mauderer started a new discussion on user/debugging/.vscode/settings.json: https://gitlab.rtems.org/rtems/docs/rtems-docs/-/merge_requests/43#note_111213

 > +    "html.format.wrapLineLength": 80,
 > +    "rewrap.autoWrap.enabled": true
 > +}

Please don't add editor-specific configurations.

--
  
Christian Mauderer started a new discussion on user/debugging/gdb.rst: https://gitlab.rtems.org/rtems/docs/rtems-docs/-/merge_requests/43#note_111214

 > +To add support for auto-loading pretty-printing scripts for GDB in RTEMS, a
 > +small section containing a Python script is added to all executable files. This
 > +section is responsible for registering the pretty-printers provided by GCC & all

Is there some reason for the `&` or is it just meant as an `and`? I'm not a native speaker so maybe it's quite common to write it like that. But it's something I would need a moment to think about while reading. From my point of view, that's usually not good for a manual.

--
  
Christian Mauderer started a new discussion on user/debugging/gdb.rst: https://gitlab.rtems.org/rtems/docs/rtems-docs/-/merge_requests/43#note_111215

 > +        use it at your own discretion and only load trusted executables in GDB.
 > +
 > +#. *Short term*

I think I would move the *Short term* to the first point and call it *Suggested safe method*. Instead of *Long term* I would use *Lazy unsafe method*. Just to make it clear that the RTEMS project is not recommending the unsafe method.

--
  
Christian Mauderer started a new discussion on user/debugging/gdb.rst: https://gitlab.rtems.org/rtems/docs/rtems-docs/-/merge_requests/43#note_111216

 > +
 > +        (gdb) load
 > +        (gdb) b main

Are you sure, you want to use the short form ``b`` instead of the long (but better readable) ``break``?

--
  
Christian Mauderer started a new discussion on user/debugging/gdb.rst: https://gitlab.rtems.org/rtems/docs/rtems-docs/-/merge_requests/43#note_111217

 > +
 > +OpenOCD is a JTAG debugging package that interfaces to a wide of JTAG pods. JTAG
 > +is a low level high speed serial interface modern processors provide as a means

Maybe it's because I'm not a native speaker but somehow that sentence feels odd. Shouldn't it be something like
```
... low level high speed serial interface provided by modern processors as a means ...
```
Beneath that: I think I would use ``most`` instead of ``modern``. I don't think I have seen much processors that don't provide a JTAG (or a derived version of it).

--
  
Christian Mauderer started a new discussion on user/debugging/gdb.rst: https://gitlab.rtems.org/rtems/docs/rtems-docs/-/merge_requests/43#note_111218

 > +
 > +Debugging with GDB & QEMU
 > +-------------

More general note regarding that chapter: I think it's partially copied from ``10.6 Debugging`` of the current manual, right? If yes: Can you please remove the sections that are replaced by that? I don't like having the same information twice in a manual. Beneath that, it's possible that ``git`` detects that and marks the text as moved instead of added.

--
  
Christian Mauderer started a new discussion on user/debugging/index.rst: https://gitlab.rtems.org/rtems/docs/rtems-docs/-/merge_requests/43#note_111219

 > +
 > +#. Set breakpoints to pause execution at specific points
 > +

Do you need the empty lines? Has it side-effects like starting a new enumeration after each empty line?




-- 
View it on GitLab: https://gitlab.rtems.org/rtems/docs/rtems-docs/-/merge_requests/43
You're receiving this email because of your account on gitlab.rtems.org.


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rtems.org/pipermail/bugs/attachments/20240818/5e24dd14/attachment-0001.htm>