Software Behaviour in a Debug Environment

To 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.

  • 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.

  • 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 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\.