Rockbox includes a buffered log to disk feature that allows recording of errors or other debug output to a memory buffer. During disk spin up, this buffer is flushed to disk. This means that crashes that occur before a disk spin up will delete any unwritten log contents, but avoids any loss of battery life associated with the feature. Consequently, logging to disk is supported on all rockbox builds, including stable releases (from 3.12 onward).
The logging system has 3 levels:
ERRORF(...) /*serious errors or problems*/
WARNF(...) /*matters of concern*/
NOTEF(...) /*useful for debug only*/
By default, only ERRORF statements pass through the preprocessor on release and development builds. Additional levels can be enabled at compile time for development purposes.
Each level works exactly like DEBUGF/LOGF except they pass data into a buffer (currently between 1-8KB depending on available memory) that is periodically flushed to disk. When writing code, you should make any error messages that users may be concerned about use ERRORF, while WARNF should be used for less serious concerns. Finally, NOTEF is intended to work like DEBUGF/LOGF currently does, and will probably be merged with DEBUGF at some point in the future.
The goal here should be to give ordinary users a way to figure out why something failed, and also a way to provide us with clues when they report difficult to reproduce bugs. Think carefully about how important a message is. If it is likely to be followed by a crash or failure to do some expected action (play file, run plugin function, build database, load theme) it should probably be an ERRORF. If a message is likely to be non-fatal or lead to a condition the code can otherwise handle gracefully, its probably better to use WARNF to avoid cluttering log files.
- 03 Jul 2013
Copyright © by the contributing authors.