/**
 * VxWorks Memory Pool Check                                   V1.00, 14.6.2002
 * -------------------------                           (c) Rene H. Straub, 2002
 * 
 * This software checks a VxWorks memory pool for consistency. It allows
 * to find to buffer overwrites which often corrupt the VxWorks memory list. 
 * I wrote this software while looking for a nasty bug in our software. By
 * using this code I finally was able to isolate and find the bug within
 * some hours (after 4 days of debugging). I hope you will find this code
 * as useful as I did.
 *
 * Principles of Operation:
 *  Each VxWorks memory pool contains a double linked list of free memory nodes. 
 *  Each node represents one block of free memory. Blocksizes can range from 16 
 *  bytes to some megabytes.
 *  Each free node is also a starting point to the list of allocated memory.
 *  In contrast to the free node list, this is a single linked list. 
 * 
 *  The memory check function walks through the free memory list and for each 
 *  node, checks the allocated memory it manages.
 *  All pointers are checked versus the memory boundaries you specified in the 
 *  call to memCheckSetup(). Next and previous node pointers are checked 
 *  for consistency. 
 *  If any of these tests fail a message is displayed and the error counter
 *  is increased. If errors have been found the function halts the current task,
 *  at the end of the test.
 *
 * Application Notes:
 *  1. Locate the file "/h/private/mempartlibp.h" and change the #include 
 *     statement in this file accordingly.
 *  2. Compile and link the memory check implementation to your project.
 *  3. Call memCheckSetup() once, specifying the memory pool you'd like to check.
 *     You can specify 0 to select the default memory pool. Also specify the
 *     memory range this pool covers.
 *  4. Call memCheck() from within your code. If you are looking for a bug you
 *     will most likely place calls to memCheck() around the erraneous code.
 *     Otherwise you'll have to decide on your own, where a check is useful.
 *  
 *  For a quick test of the functions call memCheckTest(). If everything works
 *  as expected, it should report an error in the memory list.
 *
 *
 * Important:
 *  1. In order to check a memory pool, the pool must be locked to prevent
 *     other tasks from modifying the memory list. The memCheck() function takes
 *     the sempahore of the pool at the start of the test and releases it at
 *     the end. While the test is running no memory can be allocated or freed
 *     in this pool by other tasks. So you better not call this in a time-critical 
 *     situation.
 *  2. Don't call this method from an ISR.
 *  3. In order not to fall in endless loops the code aborts if too many
 *     memory blocks are detected. If your code allocated a lot of memory blocks
 *     you might need to adapt the defines MAX_FREE_NODES and MAX_ALLOC_BLOCKS.
 *
 * Supported targets:
 *  This code has been successfully used on the following platforms.
 *  - VxWorks 5.4, Motorola Power PC
 *
 * Warranty:
 *  This software is provided as-is. There is no warranty whatsoever. You use 
 *  this software at your own risk. 
 *  In no way shall the author be made responsible for any damage caused by the
 *  use of this software.
 *
 * Copyright and Terms Of Use:
 *  You may use and redistribute this software as long as the original
 *  copyright statement remains intact. You are free to modify the code.
 *  Please let me know if you find this software useful, or if you found
 *  improvements (or bugs).
 * 
 * @author   : Rene Straub, rene.straub@yetnet.ch
 * @date     : 14.6.2002
 * @version  : 1.00
 **/

//--- includes ----------------------------------------------------------------

#ifdef __cplusplus
extern "C" {
#endif

// Need to access some VxWorks internals...
#include </rtos_vob/h/private/mempartlibp.h>    // select your path ...

#include <tasklib.h>


//--- defines -----------------------------------------------------------------

// A handy macro to call the memory check
#define MEM_CHECK()   memCheck(__FILE__, __LINE__)

// Debug level (specify 0 for normal use, use 1 and 2 for debugging only)
#define SHOW_LEVEL_ERROLY    0           // 0: Errors only.
                                  // 1: Errors, free nodes and summary
                                  // 2: All messages (be warned this may
                                  //    produce thousands of messages !)
#define SHOW_LEVEL_ERRFRR    1           
#define SHOW_LEVEL_ERRALL    2           

//--- prototypes --------------------------------------------------------------

/**
 * Configures the check function.
 * Call this function once before calling memCheck(). If you want to check more
 * than one memory partition, you must call memCheckSetup() again before using 
 * another partition.
 *
 * @param   partition     In. VxWorks memory partition. If 0 the default
 *                            partition is used.
 * @param   lowAddr       In. Lowest valid address in this memory partition.
 * @param   highAddr      In. Highest valid address in this memory partition.
 * @see     memCheck()
 **/
extern void memCheckSetup(PART_ID partition, void* lowAddr, void* highAddr);

/**
 * Checks VxWorks memory list.
 * If the memory list is ok, the function returns without an error. Otherwise
 * a debug message is printed and the calling task is suspended.
 *
 * @param   pszFile       In. File name, from where test is called.
 * @param   line          In. Line number, from where test is called.
 * @see     memCheckSetup()
 **/
extern void memCheck(const char* pszFile, unsigned line);

/**
 * Tests memory check function (only for debugging)
 *
 * This function intentionally corrupts a memory-node and then calls the check
 * function to find the corrupt memory node. 
 * If everything works well, the function will report an error and stop the 
 * calling task.
 * @note: This function is only for debugging, never use it in a real project.
 **/ 
extern void memCheckTest(void);



#ifdef __cplusplus
} /* end extern "C" */
#endif