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

Update documentation and arduino debug options #8837

Merged
merged 22 commits into from
Mar 29, 2023

Conversation

mhightower83
Copy link
Contributor

@mhightower83 mhightower83 commented Jan 29, 2023

Add a section in FAQ for Improving Exception Decoder Results
Add a description for the Debug Optimization menu to ideoptions.rst
Added some connecting links between related topics.

Update to boards.txt.py to generate boards.txt with a Debug Optimization menu.
platform.txt has optimization defaults set by build.debug_optim=-Os
The Debug Optimization menu selection overrides that.
Then an -O option in build.opt takes priority over those.

No changes to platformio-build.py.

Status: ready
edited to sync with the current state of the PR

Describe how to improve Exception Decoder results.

Updated build option details.
@jjsuwa-sys3175
Copy link
Contributor

Hmm, maybe the compiler should disable both leaf function handling and sibling call optimization by default when '-Og' is specified. Because the GCC manual entry for that option says first:

Optimize debugging experience. '-Og' should be the optimization level of choice for the standard edit-compile-debug cycle, offering a reasonable level of optimization while maintaining fast compilation and a good debugging experience.

@d-a-v
Copy link
Collaborator

d-a-v commented Jan 30, 2023

With -Og instead of -Os (without other debugging option), tried with the FSBrowser example, I get

  • +600 Bytes in IRAM text
  • +24KB in flash

With -Os -fno-optimize-sibling-calls I get

  • +18 bytes in IRAM text
  • +500 bytes in flash

Is -Og preferred when debug option on Serial are enabled ?
Or is -fno-optimize-sibling-calls sufficient and document instead how to enable -Og in the gdb help section ?

#
# debug
#
for define in env["CCFLAGS"]:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

definitions are in cppdefines
could use the flattened ones, or loop env[...] but note of possible types (tuple or string)

@jjsuwa-sys3175
Copy link
Contributor

@d-a-v :

Is -Og preferred when debug option on Serial are enabled ?
Or is -fno-optimize-sibling-calls sufficient and document instead how to enable -Og in the gdb help section ?

Well, just thought that using '-Og' would generally make debugging less disturbing.

From GCC manual again:

-Og

  • Optimize debugging experience.
    '-Og' should be the optimization level of choice for the standard edit-compile-debug cycle, offering a reasonable level of optimization while maintaining fast compilation and a good debugging experience.
    It is a better choice than '-O0' for producing debuggable code because some compiler passes that collect debug information are disabled at '-O0'.
    Like '-O0', '-Og' completely disables a number of optimization passes so that individual options controlling them have no effect.
    Otherwise '-Og' enables all '-O1' optimization flags except for those that may interfere with debugging:
    • -fbranch-count-reg -fdelayed-branch -fdse -fif-conversion -fif-conversion2 -finline-functions-called-once -fmove-loop-invariants -fssa-phiopt -ftree-bit-ccp -ftree-dse -ftree-pta -ftree-sra

@mhightower83
Copy link
Contributor Author

With other compilers, I have used you get a better matchup between code addresses and the source code when you build with debug option. Would that be true here with -Og?

@jjsuwa-sys3175
Copy link
Contributor

I haven't compared the output with 'other compilers'... but I can say that with '-Og' GCC disables some optimizations that make debugging difficult (both machine-independent and dependent, eg. 'constant synthesis' in Xtensa)
'-Og' basically implies '-O1', so optimization options not included in '-O1', such as '-foptimize-sibling-calls', are disabled, but register saving of leaf functions still can be omitted (there is no option to control this separately).
Fortunately, forcing all functions to save register A0 on '-Og' can be easily implemented with a few lines of patch to the Xtensa port.

@mhightower83
Copy link
Contributor Author

Fortunately, forcing all functions to save register A0 on '-Og' can be easily implemented with a few lines of patch to the Xtensa port.

Sounds good to me; however, I have to defer to others for such a change. @d-a-v @earlephilhower

Updated platform.txt - positioned -Os such that it can be overridden by `build.opt`.

Add suggestion of using `-Og` which may improve the Decoder's line number correlation
with the problem in the source code.

Untested adjustments to platformio-build.py
Previously `-O3` in the example had no effect. It was overridden by later flags.
Reording the `-Os` allowed changing optimization to  work. Somehow this triggered
a new warning "Stream.h:50:7: warning: 'f.Stream::_startMillis' may be used
uninitialized in this function". Replaced `-O3` with `-Og`.
@d-a-v
Copy link
Collaborator

d-a-v commented Jan 31, 2023

I am personally looking forward for such improvement with the debugging experience.
However, I think that -Og by default when serial log is enabled makes a too large change (similar to what enabling IPv6 brings and this is one of the main reason why is it not enabled by default).
What can be proposed is to add two more debugging port options with the following:

diff --git a/tools/boards.txt.py b/tools/boards.txt.py
index 89380d20..52300a11 100755
--- a/tools/boards.txt.py
+++ b/tools/boards.txt.py
@@ -1353,11 +1353,15 @@ def all_debug ():
     options += [ listsingle ]
     debugmenu = collections.OrderedDict([
             ( '.menu.dbg.Disabled', 'Disabled' ),
-            ( '.menu.dbg.Disabled.build.debug_port', '' ),
+            ( '.menu.dbg.Disabled.build.debug_port', '-Os' ),
             ( '.menu.dbg.Serial', 'Serial' ),
-            ( '.menu.dbg.Serial.build.debug_port', '-DDEBUG_ESP_PORT=Serial' ),
+            ( '.menu.dbg.Serial.build.debug_port', '-DDEBUG_ESP_PORT=Serial -Os -fno-optimize-sibling-calls' ),
             ( '.menu.dbg.Serial1', 'Serial1' ),
-            ( '.menu.dbg.Serial1.build.debug_port', '-DDEBUG_ESP_PORT=Serial1' ),
+            ( '.menu.dbg.Serial1.build.debug_port', '-DDEBUG_ESP_PORT=Serial1 -Os -fno-optimize-sibling-calls' ),
+            ( '.menu.dbg.Serial-dbg', 'Serial (full debug)' ),
+            ( '.menu.dbg.Serial-dbg.build.debug_port', '-DDEBUG_ESP_PORT=Serial -Og' ),
+            ( '.menu.dbg.Serial1-dbg', 'Serial1 (full debug)' ),
+            ( '.menu.dbg.Serial1-dbg.build.debug_port', '-DDEBUG_ESP_PORT=Serial1 -Og' ),
             ( '.menu.lvl.None____', 'None' ),
             ( '.menu.lvl.None____.build.debug_level', '' ),
         ])

Giving this Arduino IDE 1.8 menu:
image

additionally: options -Os from three lines in platform.txt have to be removed

With these changes, we have
-Os by default
-Os -fno-optimize-sibling-calls when one of the serial ports is selected
-Og when one of the serial ports w/full debug option is selected

additionnally: platformio-build.py would have yet to be updated too

platform.txt Outdated Show resolved Hide resolved
@d-a-v d-a-v changed the title Update documentation Update documentation and arduino debug options Feb 5, 2023
@mhightower83
Copy link
Contributor Author

// Without "-fno-ipa-pure-const", a complete caller list is not on the stack for decoding.
#pragma GCC optimize("Og,no-ipa-pure-const")

// Or this set for -Os
//#pragma GCC optimize("Os,no-inline,no-optimize-sibling-calls,no-ipa-pure-const")

void hideaway() {
    asm volatile ("" ::: "a0", "memory");
    while(true);
}

void setup() {
  Serial.begin(115200);
  delay(200);  
  Serial.printf("\r\n\r\nNow waiting forever ...\r\n");
  hideaway();
}
void loop() {}

I don't have a lot of experience with the new optimization options to know if this would be a commonly useful option or just a wack-a-mole one-off. Unless someone has some insight into this flag, I am inclined to not change the PR. I think as experience is gained with changing optimization for improved decoding, the refinement list will expand. Maybe later add an Optimum-Plus with all the extras flags that prove useful.

@d-a-v d-a-v added the alpha included in alpha release label Feb 8, 2023
@d-a-v d-a-v merged commit d3c102e into esp8266:master Mar 29, 2023
@mhightower83 mhightower83 deleted the pr-doc-debug branch March 30, 2023 18:25
hasenradball pushed a commit to hasenradball/Arduino that referenced this pull request Nov 18, 2024
* Update documentation

Describe how to improve Exception Decoder results.

Updated build option details.

* Added d-a-v's code. And updated description and debug macro.

* Update doc

Updated platform.txt - positioned -Os such that it can be overridden by `build.opt`.

Add suggestion of using `-Og` which may improve the Decoder's line number correlation
with the problem in the source code.

Untested adjustments to platformio-build.py

* Fixed code formatting

* Fixed example

Previously `-O3` in the example had no effect. It was overridden by later flags.
Reording the `-Os` allowed changing optimization to  work. Somehow this triggered
a new warning "Stream.h:50:7: warning: 'f.Stream::_startMillis' may be used
uninitialized in this function". Replaced `-O3` with `-Og`.

* Proposed "Debug port" menu change
Preserves a pathway for `build.opt` override.

* Update boards.txt.py and docs - WIP

* Improve organization of optimization content.
Use "Debug Optimization" for menu name.
The menu item defines the initial optimization.
platform.txt - optimization parameter can be overridden by build.opt.

* Add fallback value for build.debug_optim to platform.txt

* update text and undo changes to platformio-build.py

* tweak text

* Added ':orphan:' mark to a06-global-build-options.rst

* Update doc. Added link in page index to 'Improving Exception Decoder Results'

* Update text to reference PR#8868 improvements for leaf function.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
alpha included in alpha release
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants