Persistentdata for beginners: Comms Debug Utility

Comms Debug Utility (CDU) provides efficient and reliable logging of messages to a log file or serial port.

It was developed as an improved version of file logger but due to the risk of breaking existing flogger clients it was delivered as a new component. The original designers named the component “Comms Debug Utility” to distinguish it from file logger and to highlight its intended usage as an internal API for the Symbian Software Networking team. In common with file logger, the API was used by code in other packages and it is effectively a public API now.

CDU supports a several destinations for log messages: log file, RDebug, serial port 1, serial port 2, and the Windows debug port (for the emulator). You can configure where the log messages are written to and which components are enabled in the commsdbg.ini file. The CDU server searches for this file on start-up in the \logs and \resource directories. When logging to file, the output is written to C:\logs\log.txt.

A recent submission introduced a migration path to the forthcoming Open System Trace framework. You can now specify that the CDU log is written using OSTv2 format to enable interleaved traces to continue to be captured whilst packages move to OST.

Comms Debug Utility API

The API is defined in comms-infras/commsdebugutility.h. It defines the same class as file logger (RFileLogger) plus a set of macros to simplify the addition and removal of logging from release builds. Client code should link to comsdbgutil.lib.

CDU is mostly source compatible with file logger. All file logger APIs are supported, but there are behaviour changes which may need source changes to fix. For example, the logging directory and log file name could be up to 100 characters in file logger but CDU has a maximum of 16 characters and will truncate longer strings.

CDU is not data compatible with file logger. It writes the log to a single file only, whereas file logger writes to several log files. The advantage of writing to a single destination is that log messages from different components are interleaved (i.e. showing different layers of a communications stack) so it is easier to diagnose issues.

CommsDebugUtility is not binary compatible with file logger as the RFileLogger object has changed in size and no longer derives from RSessionBase.

Further resources

Coming up next…
Trace Framework and UTrace will be the last components in the Persistentdata for beginners series.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s


%d bloggers like this: