Note: The memory debugging parameters are now set in the registry rather than the INI file.  See Q3588. 

Citect has extensive built in memory debugging system used to trace problems with memory. This debugging system allows you to view all the memory allocations as well as the data in those allocations in the Citect kernel. It will also detect memory leaks and memory overwrite errors.

WARNING: The memory debugging system should only be enabled when you are searching for a problem as it can produce side effects on your running system. These side effects include, excessive CPU loading, extra memory consumption, fake error messages and even General Protection Violations (GPF). You should make sure after commissioning that all the memory debugging is disabled.

The [DEBUG]Memory parameter is only supported on 32 bit versions of Citect. The 16 bit versions of Citect use the [MEMORY]Segment parameter for similar functionally.

For 32 Bit Citect the Memory debugging system can be used by setting the [Debug]Memory parameter to one or more of the following modes (ie. OR together). If any of the modes are set then a debug heap will be used. For each allocation a stack trace of where the memory was allocated from is kept. Also, overwrite buffers are provided which are checked to flag memory overwrites. In all modes elements are checked for corruption when they are freed.

Memory=1 Check the Debug Heap periodically. The rate is determined by [Memory]HeapCheckRate (in seconds) and defaults to 5 seconds.

Memory=2 Check on exit for memory which has not been freed

Memory=4 Check the entire Debug heap during each allocation and free. This could cause sluggish response.

Memory=8 Delay the freeing of memory. When called to free memory the memory is marked as free but not actually freed

Memory=16 Use Virtual pages for each allocation with an OS protected virtual page after. The memory given is placed just before the protected page so that any overwrite will cause an exception. This mode uses a LOT of virtual memory as each allocation takes up at least 8K. It is useful for tracking overwrites just as they happen but is very very slow due to the paging that takes place. Use with extreme care as this may also cause Citect to crash (especially the configuration environment). NOTE also that this mode does not guarantee a double word aligned pointer for a non quadrile size. However this can be forced by setting the parameter [Memory]ForceVirtualAlign=1. This will ensure a double word aligned address in this mode by bumping the size requested up to a multiple of 4 (which may go against the use of this mode).

Reporting is done to SYSLOG.DAT and by default an error message is also shown. The Error message can be turned off by setting [Memory]ReportErrors=0. A debug breakpoint exception will be raised on an error if [Debug]CrashOnError=1. The size of the overwrite buffer is controlled by [Memory]MemoryBufferSize and defaults to 16. However this is ignored and set to zero in mode 16. The size of the stack trace is controlled by [Memory]MemoryStackTrace and defaults to 8.

To view the memory in the Citect kernel enter PAGE MEMORY at the kernel command line. The top of the window shows the following statistics:

Current Allocs: The current number of allocations in the debug memory heap.

Current Size: The current size in bytes of all the memory allocations in the debug heap.

Maximum Allocs: The maximum number of allocations ever in the debug heap.

Maximum Size: The maximum size in bytes of all the memory in the debug heap.

The current statistics should change as you display new pages and Citect does it's work. But if you have a leak then all these numbers should be increasing.

Below the statistics are rows of individual memory allocations. The following columns are displayed:

Alloc: The number of the allocation, starting at 1 increasing to the CurrentAllocs.

Size: The size in bytes of the memory allocation.

Free: 0 if the memory is in use or 1, if the memory is free.

CallStackTrace Hex dump of the call stack uses to allocate the memory. This is used to trace the location of the memory leak.

If you press 'v' you get a verbose display of the memory allocation. This shows the lead and trail memory overwrite buffers (which are used to detect corruption) as well as the data in the actual memory allocation.

When not in verbose mode you can scroll the list of allocations with the cursor up/down keys. Pressing SHIFT and the cursor keys, will scroll by one page. Using SHIFT down cursor and the keyboard auto repeat allows you to quickly scroll to the end of the debug memory heap where all the action is. Memory is always added to the bottom of the list so new allocations will appear there. If you check the kernel options, always on top, scroll to the end of the debug heap and then change pages in Citect, you should see lots of action happening in the help. That statics will update and you will see lots of new memory allocations.