/************************************************************************************
* This is the public header file for the Debug module. 
*
* Author(s): BPPED1
*
* (c) Copyright 2004, Freescale, Inc.  All rights reserved.
*
* Freescale Confidential Proprietary
* Digianswer Confidential
*
* No part of this document must be reproduced in any form - including copied,
* transcribed, printed or by any electronic means - without specific written
* permission from Freescale.
*
* Last Inspected:
* Last Tested:
*
* Source Safe revision history (Do not edit manually) 
*   $Date: 10-03-04 12:34 $
*   $Author: Bpped1 $
*   $Revision: 9 $
*   $Workfile: Debug.h $
************************************************************************************/

/************************************************************************************
DEBUG FEATURE DESCRIPTION

TOC:
1. Intoducation
2. Printing Text.
 2.1 Windows Console
 2.2 Serial Port
 2.3 LCD panel
3. Asserts
 2.1 Simulator asserts
 2.2 Asserts with BDM debugger
 2.3 Asserts with LCD panel
4. LED's
5. Buzzer

1. INTRODUCTION
The Debug functionality is used for various tasks such as outputting debug text,
and asserting on unexpected behaviour. The following sections will describe each
of the available debug features, and their possible configurations. The features
are configured by conditional compiler directives defined in Target.h, and this
header file.

2. PRINTING TEXT --------------------------------------------------------------
The main function for printing text is Dbg_Print. It is a downscaled version of
printf. I.e. it does only offer very basic formatting. The %s, and %d format
specifiers are available. Only the %s specifier takes a length parameter such
as %08s. The length must consist of two digits if it is included in the string.
A minimum number of chars specified by the length parameter is printed, and
spaces are appended if the sub-string is shorter than the minimum length.

In order to use Dbg_Print(), ENABLE_DPRINTF must be defined in Debug.h.

Other functions are also available for outputting text (please see the comments,
and description at the function declarations):
Dbg_PutStr - Print a string
Dbg_PutHexNum - Print a hexadecimal number.

The following sub-sections describe the possible output methods currently
supported for printing text. The methods are mutually exclusive, and it is not
defined what will happen if selecting two or more methods at the same time.

2.1 WINDOWS CONSOLE
If ENABLE_DPRINTF is defined, and the code is compiled for WinSim, the Dbg_Print
function will as default print to the Console using putchar() from <stdio.h>.
Nothing needs to be defined in order to redirect the output to the console, but
DBG_PRINT_TO_CONSOLE may be defined to clarify the intentions of the developer. 

2.2 SERIAL PORT
In order to redirect the Debug output to the serial port, a special cable, and
VHDL code for the SPI logger is required. The Debug output is written one byte
at a time to 8 GPIO's (8bit parallel), and converted to a serial stream @115200bps
by the modified SPI logger. The serial stream is looped back to the demo boards
COM2 port.

To redirect the printer output to the serial port DBG_PRINT_TO_COMPORT must be
defined. Please note that the output over the serial port may be slow, and thus
impair performance if called from timing sensitive code.

2.3 LCD PANEL
The LCD panel is a little limited for printing text because it only supports two
lines of text with 16 chars in each line. However, this may be sufficient for
simple debugging purposes. The Dbg_Print function will toggle the line in the
LCD display if it comes across a '\n' in the string. Otherwise, it will stay in
the current line, and everything after 16 characters is not visible. Though, a
'\n' that occurs after 16 chars of text has been printed will still toggle the
lines.

To redirect the printer output to the LCD panel DBG_PRINT_TO_LCDDISP must be
defined. Please note that the output to the LCD panel is quite slow, and thus
impair performance if called from timing sensitive code.

3. ASSERTS --------------------------------------------------------------------
Asserts can be used in two ways. Either the assert will halt the code, or the
assert will just notify the software developer that some (unexpected) event has
occured. In order to use asserts at all, ENABLE_ASSERTS must be defined in the
global header file Target.h. This header file also contains the switches for
enabling/disabling asserts for various modules. Currently the following switches
are available: PHY_ASSERT, MAC_ASSERT, SEQ_ASSERT, MEM_ASSERT, and SMAPI_ASSERT
(See Target.h for the list of switches. The list may be out of sync with this text).
These switches will halt the code on an assert condition. If the swithes are
appended with _INFO (e.g. MAC_ASSERT_INFO), then the assert will not halt the
code but only generate some sort of notification of the assert condition.

There are two options for asserts that halt the code. The first option will only
work if the demo board has a BDM debugger connected. This will set a bit in the
HCS08 CPU which enables the use of SW breakpoints. If ENABLE_ASSERT_BREAKPOINT is
defined in Target.h then the asserts will utilize the SW breakpoints.

The second option is relevant if no BDM debugger is connected. In this case the
ENABLE_ASSERT_BREAKPOINT switch must not be defined. Instead of the SW breakpoint,
an infinite loop is used for trapping the code in the assert function.

2.1 SIMULATOR ASSERTS
No options are available for the WinSim asserts. The assert function of the Visual
Studio development environment is used. The WinSim asserts are always enabled.

2.2 ASSERTS WITH SERIAL PORT
If ENABLE_ASSERT_TEXTUAL is defined in Target.h, and DBG_PRINT_TO_COMPORT in this
Debug.h, the line number and filename of the assert is printed to the serial port.

2.3 ASSERTS WITH LCD PANEL
If ENABLE_ASSERT_TEXTUAL, and DBG_PRINT_TO_LCDDISP is defined in Target.h, the line
number and filename of the assert is printed to the LCD panel. It's possible to
save a bit of code space by defining ENABLE_LCD instead of DBG_PRINT_TO_LCDDISP if
the LCD panel is only used for asserts, and not general Dbg_Print output.

4. LED'S ----------------------------------------------------------------------
Use SetLeds() with gLedOn_c/gLedOff_c, and gLed1_c, gLed2_c, gLed3_c, gLed4_c,
or gLedAll_c to turn on or off the various LEDs. ORed Combinations are possible.
ENABLE_LEDS must be defined to control the LEDs.

5. BUZZER ---------------------------------------------------------------------
The buzzer can be enabled by defining ENABLE_BUZZER. Also define ENABLE_ASSERT_BUZZER
to generate a short blip on asserts. The buzzer will generate a permanent tone by
calling the function BuzzerControl() with the parameter gBuzzerOn_c. To turn the
buzzer off, the function must be called with the parameter gBuzzerOff_c. In order
to generate a tone with a short duration, BuzzerControl() can be called with the
parameter gBuzzerBlip_c. This parameter will block the code execution for the
duration of the tone.

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


#ifndef _DEBUG_H_
#define _DEBUG_H_

#include "NwkMacInterface.h"


/************************************************************************************
*************************************************************************************
* Public macros
*************************************************************************************
************************************************************************************/

/**** Debug configuation options BEGIN ****/

#ifdef PLATFORM_WINDOWS
  // Define output method for Dbg functions. Only define one at a time.

  // Console: Default if compiling for simulator. Is overridden by build environment.
  // Has no real effect but clarifying the intentions of the developer. Will auto-
  // define ENABLE_DPRINTF.
//#define DBG_PRINT_TO_CONSOLE 1

#else  // PLATFORM_GB60
  // Comport: Can be used if special cabling is used to connect the demo board to a
  // sniffer. The sniffer will then redirect the debug output to the COM2 port on the
  // demo board. Port settings are 115200, 8N1, RTS/CTS-FC. Auto-defines ENABLE_DPRINTF.
//#define DBG_PRINT_TO_COMPORT

  // Print to LCD dispaly on demo board. Only two lines of text with each 16 characters.
  // A '\n' will change which line the text is displayed in. If the length of a line of
  // text exceeds 16 characters, only the 16 first are printed. However, a terminating
  // '\n' will still cause a line change. Will auto-define ENABLE_LCD, and ENABLE_DPRINTF.
//#define DBG_PRINT_TO_LCDDISP

#define DBG_NUM_LINES_LCD 2

//#define ENABLE_LCD           // Enable LCD panel
//#define ENABLE_BUZZER        // Enable buzzer function BuzzerControl()
//#define ENABLE_ASSERT_BUZZER // Buzz the buzzer if bugz.
//#define ENABLE_LEDS          // Enable LEDs function SetLeds()

  // Enable this to make the Dbg_SetPortA0() macro set/clr Port A bit 0.
  // can be used for e.g. measuring the time between events using a scope.
//#define DBG_TOGGLE_PORTA0 1

#endif // PLATFORM_WINDOWS

//#define ENABLE_DPRINTF   // Main switch for Debug Print functionality.
//#define DBG_MLME_NWK_LOG // Print out message types between NWK and MLME
//#define DBG_MLME_MEM_LOG // Print out message types between MEM and MLME
//#define DBG_LOG_MAX      // Print all parameters of messages between NWK and MLME

/***** Debug configuation options END *****/