Software Behaviour in a Debug Environment

diff -r 43e37759235e -r 51a74ef9ed63 Symbian3/SDK/Source/GUID-0AC0CBBA-87AD-5F94-8F0D-D13654ABB631.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-0AC0CBBA-87AD-5F94-8F0D-D13654ABB631.dita Wed Mar 31 11:11:55 2010 +0100 @@ -0,0 +1,13 @@ + + + + + +Software Behaviour in a Debug EnvironmentTo aid debugging the Comms software is designed to behave differently for release and debug binary files if certain configuration parameters are set.

The following is a list of some of the behavioural changes:

Errors may panic in debug builds - Release builds do not panic for most error conditions since panicking results in the loss of the service due to thread termination. If the thread is a SystemCritical the device reboots when the thread is panicked. Debug builds often panic when an error is detected. For example, if the debug version of the software detects an error in a configuration file it panics the thread to draw attention to the mismatched configuration. In a release build the software uses a default configuration to work around the problem. Other such events include failed internal consistency checks, failed internal connections between components, and cleanup failures.
TestMode parameter controls thread panic behaviour - The TestMode parameter is available in the c32start.ini file located in <drive>\private\101f7988. If the parameter is absent or set to 0, the Rootserver does nothing. If the parameter is set to 1 (TestMode=1), the Rootserver overrides and disables the SystemCritical setting for its threads. As a result, when any Rootserver thread terminates, it does not cause the device to reboot. This parameter was designed to be used during testing of cases which involve shutting down the Comms servers. The SystemCritical setting is configured in the CMI files, for more information see CMI files - thread configuration.
Servers can be shutdown to help detect memory leaks - For more information see Detecting Memory Leaks
Serial ports may require further configuration - The process of testing, debugging and logging may require extra serial ports, so existing serial-port clients such as Bluetooth and C32 clients might be affected if there is contention. For more information about configuring comms serial ports see Configuring Comms. For more information on configuring the RDebug port see Writing trace code using RDebug::Print.
Commdb/Commsdat - The Comms Database contains the largest number of parameters to configure the Comms system. For more information see Comms Database.

Note: Check the Comms Database configuration used to ensure that there are no mistaked in the configuration.

Detecting Comms memory leaks

The multi-threaded nature of much of the Comms software complicates the detection of memory leaks. This is because for some of the Comms software memory leaks can only be detected once all the handles are closed, a condition usually only reached during shutdown. As most Comms servers never shutdown, because doing so would reboot the device, the leaks in Comms software and plug-in software such as CSYs and NIFs can go unnoticed. Detecting these leaks requires a special shutdown command for the Comms servers in association with the TestMode parameter and then the inspection of the logged output for any leak information.

During shutdown, memory leaks are logged using the "LOG RSModule + Leak " CDU tags so make sure these are enabled before shutdown.

When a potential memory leak is found the separate Hooklogger tool, which runs on MS Windows™, is used to track the memory leak. The process is as follows:

Setup the Hooklogger application and attach its hooks to the kernel binary files
Start the Hooklogger application and instruct it to capture memory allocations
Performing the server shutdown and wait for it to complete
Find the addresses of the leaked memory cells in the log file by checking all logging which was tagged with "RSModule "
Search the Hooklogger captured data for each leaked cell
Hooklogger's data will indicate where the leaked cell was allocated in the source code

For more information on Hooklogger, see the separate topic Memory leak detection.

For more information about ESock's shutdown procedure see section 6.3 Unloading ESOCK of ESOCK "How-to".

For more information about the use of heap checking to detect and debug memory leaks within the server and its plug-in CSY s see the C32 Heap Check Migration Document. There is no document which describes shutting down the C32 Serial Server, but C32's shutdown was modelled on ESock's shutdown so the principles are the same and the scripts are named te_c32_test_unloadc32*.script in the folder ..\ser-comms\c32\Test\TE_C32\util\scriptfiles\.

\ No newline at end of file