ncdebug.h

CE下 NET2778 NDIS Drivers, 在每个平台上都可以使用

/******************************************************************************

Copyright (C) 2004, NetChip Technology, Inc. (http://www.netchip.com)

THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, 
EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED 
WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR PURPOSE.

NCDEBUG.H

NetChip device firmware debugging support:

'Debug' is a collection of firmware debugging aids. These functions can be
invaluable for debugging your USB device. As provided, they work on 
the NetChip PCI-RDK. They may require changes for your platform.

******************************************************************************/

///////////////////////////////////////////////////////////////////////////////
#ifndef NCDEBUG_H
#define NCDEBUG_H

///////////////////////////////////////////////////////////////////////////////
#if _NCDEBUG || _NCHISTO

///////////////////////////////////////////////////////////////////////////////
// Volume levels for history logging and printing
//  - History and print have separate volume thresholds
#define VOLUME_NONE             0   // No printing or history logs no matter *what*
#define VOLUME_MINIMUM          1   // Minimum volume: set thresholds here to see serious or fatal errors
#define VOLUME_LOW              2   // Low volume: Set print threshold here to see messages without being overwhelmed
#define VOLUME_MEDIUM           3   // Medium volume
#define VOLUME_HIGH             4   // High volume: Set history threshold here to log events without being too overwhelmed
#define VOLUME_MAXIMUM          5   // Maximum volume: Set thresholds here to see all possible messages and logs

// Default volume levels for printing and history logging
//  - Generally, we want print volume lower than history volume
#define DEFAULT_PRINT           VOLUME_LOW
#define DEFAULT_HISTORY         VOLUME_HIGH

///////////////////////////////////////////////////////////////////////////////
// Global print volume
//  - Applies to NetChip printf macro
//  - Value ranges from VOLUME_NONE to VOLUME_MAXIMUM
extern UINT gPrintVolume;

///////////////////////////////////////////////////////////////////////////////
extern PCHAR VolumeMsg[];

#endif

///////////////////////////////////////////////////////////////////////////////
#if _NCHISTO    // Log historical events
// Note: History is managed separately from other debugging aids. This allows
// adding history trace logging to free builds if needed.
//  - Be careful not to release builds that have history logging included!

#define HISTO(v, t, a1, a2, a3) History(v, t, (ULONG)(a1), (ULONG)(a2), (ULONG)(a3))
#define HISTORY_ENTRIES 1000    // Number of historical events in log (a ring buffer)
#define HistoPrintFormat        "        %-4.4s  %8.8x  %8.8x  %8.8x\n" // Text, Arg1, Arg2, Arg3

typedef struct _HISTORY_ENTRY
{   // Each historical entry looks like this:
    ULONG Text;                 // Identifying symbol (e.g. "Intr", "TxEn", "Susp")
    ULONG Arg1;
    ULONG Arg2;
    ULONG Arg3;
} HISTORY_ENTRY, * PHISTORY_ENTRY;

extern HISTORY_ENTRY HistoBuf[HISTORY_ENTRIES];
extern ULONG HistoryCount;
extern UINT gHistoryVolume;

///////////////////////////////////////////////////////////////////////////////
void
History(
    UINT HistoLevel,
    PCHAR Msg,
    ULONG Arg1, 
    ULONG Arg2, 
    ULONG Arg3
    );

///////////////////////////////////////////////////////////////////////////////
void
ShowHistory(
    void
    );

///////////////////////////////////////////////////////////////////////////////
void
HistoryFlush(
    void
    );

#else   // _NCHISTO (FALSE)

#define HISTO(v, t, a1, a2, a3) // Macro evaluates to nothing
#define ShowHistory()
#endif  // _NCHISTO

///////////////////////////////////////////////////////////////////////////////
// 'Static' declaration
//  - In release builds, a file's private functions are hidden from other files
//    by using the 'static' keyword. During development however, the static keyword
//    can prevent function entry points from appearing in map files and browsers. For
//    debugging convenience, 'static' is not applied.
#if _NCDEBUG
#define STATIC
#else
#define STATIC static
#endif

#if _NCDEBUG
///////////////////////////////////////////////////////////////////////////////
// Debug messages and printing (printf()) support
///////////////////////////////////////////////////////////////////////////////

///////////////////////////////////////////////////////////////////////////////
// Compiles any statement!
#define NCDEBUG(_x_) _x_

///////////////////////////////////////////////////////////////////////////////
// Return an endpoint character ('0', 'A', 'B', ... from an endpoint number)
//  - Useful when calling printf()
#define NC_ENDPOINT(Ep) ((Ep)==EP0)?'0':(Ep) + ('A' - 1)

///////////////////////////////////////////////////////////////////////////////

// Macro to conditionally compile our own printf statements

// WinCE Note:  Adapting NCPRINTF to WinCE is tough because the WinCE debug
// macros only take Unicode.  It's not easy to convert the NCPRINTF calls to use 
// Unicode strings
#define NCPRINTFCOND(_vol, _cond, _x_)      // Macro evaluates to nothing
#define NCPRINTF(_vol, _x_)					// Macro evaluates to nothing


///////////////////////////////////////////////////////////////////////////////
// Handy "Index to String" message conversions:
extern PCHAR EpTypeString[];                // BULK, ISOCH, ...
extern PCHAR EpDirString[];                 // OUT, IN
extern PCHAR DeviceEventString[];           // VBUS, reset, ...

#else
#define NCDEBUG(_x_)                        // Macro evaluates to nothing
#define NCPRINTFCOND(_vol, _cond, _x_)      // Macro evaluates to nothing
#define NCPRINTF(_vol, _x_)                 // Macro evaluates to nothing

#endif  // _NCDEBUG


///////////////////////////////////////////////////////////////////////////////
// Asserts and faults
///////////////////////////////////////////////////////////////////////////////
#undef ASSERT
#if _NCDEBUG

#ifdef USING_WINDOWS_ASSERT
#define ASSERT(exp) assert(exp)
#else

#if _NC_RDK_AND_WINDOWS
///////////////////////////////////////////////////////////////////////////////
// Assert options for RDK running under Windows
//  - TRUE: Apply hard assert: Hard assert causes an "INT 3" to break into the
//    debugger immediately (or, if there's no debugger, the app crashes!)
//  - FALSE: Apply soft assert: Disable interrupts so activity stops, but the app
//    keeps running (so some sort of post-mortem work can be done, such as show History)
#if FALSE
// Drop into debugger (if debugger is there, otherwise app crashes!)
#define NC_ASSERT_METHOD _asm INT 3
#else
// Disable interrupts
//  - This method works better if there's no debugger!
#define NC_ASSERT_METHOD System_InterruptController(NCSYS_INTERRUPT_DISABLE);
#endif

///////////////////////////////////////////////////////////////////////////////
#define ASSERT(exp) if(!(exp)){HISTO(VOLUME_MINIMUM, "ASRT", __LINE__, 0xffffffff, 0xffffffff); \
    printf("ASSERT: "\
    __FILE__ ", Line %d:\n  ("#exp") failed!\n", __LINE__); \
    NC_ASSERT_METHOD }
#else

#if _NC_CEPC
#define ASSERT(exp) if(!(exp)){HISTO(VOLUME_MINIMUM, "ASRT", __LINE__, 0xffffffff, 0xffffffff); \
    }

#else

// Assert, but don't halt process
//  - This assert should work on any platform, but it won't halt the process!
//  - Restructuring to halt target CPU or break into debugger may be appropriate
#define ASSERT(exp) if(!(exp)){HISTO(VOLUME_MINIMUM, "ASRT", __LINE__, 0xffffffff, 0xffffffff); \
    printf("ASSERT: "\
    __FILE__ ", Line %d:\n  ("#exp") failed!\n", __LINE__);}

#endif

#endif

#endif

///////////////////////////////////////////////////////////////////////////////
#define NCFAULT() {HISTO(VOLUME_MINIMUM, "FALT", __LINE__, 0xffffffff, 0xffffffff); \
    printf("FAULT: "\
    __FILE__ ", Line %d:\n", __LINE__); }

///////////////////////////////////////////////////////////////////////////////
#else   // _NCDEBUG

#define ASSERT(exp)     // Macro evaluates to nothing
#define NCFAULT()       // Macro evaluates to nothing

///////////////////////////////////////////////////////////////////////////////
#endif  // _NCDEBUG

#if _NCDEBUG
///////////////////////////////////////////////////////////////////////////////
// Display memory
///////////////////////////////////////////////////////////////////////////////

///////////////////////////////////////////////////////////////////////////////
enum NCDEBUG_WORDSIZE 
{
    WORDSIZE_BYTE = 1,  // Byte (1 byte)
    WORDSIZE_WORD = 2,  // Word (2 bytes)
    WORDSIZE_LONG = 4   // Long (4 bytes)
};

///////////////////////////////////////////////////////////////////////////////
void
NcDisplayMemory(
    UINT Volume,
    PVOID Ptr, 
    UINT Count, 
    enum NCDEBUG_WORDSIZE WordSize  // Byte, Word, Ulong
    );

///////////////////////////////////////////////////////////////////////////////
#define _NC_DISPLAY_MEMORY(v, p, c, s) //NcDisplayMemory(v, p, c, s)

///////////////////////////////////////////////////////////////////////////////
#else   // NCDEBUG_H

///////////////////////////////////////////////////////////////////////////////
#define _NC_DISPLAY_MEMORY(v, p, c, s)      // Macro resolves to nothing

///////////////////////////////////////////////////////////////////////////////
#endif // NCDEBUG_H


#if _NCDEBUG
///////////////////////////////////////////////////////////////////////////////
// Fill an endpoint buffer with 'friendly' (human-readable) content
///////////////////////////////////////////////////////////////////////////////
void
FriendlyFillBuffer(
    PNC_ENDPOINT_OBJECT Endpoint
    );

///////////////////////////////////////////////////////////////////////////////
#define _NC_FRIENDLY_FILL_BUFFER(e) FriendlyFillBuffer(e)

///////////////////////////////////////////////////////////////////////////////
#else   // NCDEBUG_H
// "Friendly fill" not avaiable is release build
#define _NC_FRIENDLY_FILL_BUFFER(e)     // Macro resolves to nothing

///////////////////////////////////////////////////////////////////////////////
#endif

///////////////////////////////////////////////////////////////////////////////
#endif  // NCDEBUG_H

///////////////////////////////////////////////////////////////////////////////
//  End of file
///////////////////////////////////////////////////////////////////////////////