/*

* Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies).

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of "Eclipse Public License v1.0"

* which accompanies this distribution, and is available

* at the URL "http://www.eclipse.org/legal/epl-v10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description: 

*

*/

#ifndef __MSGCMD_H__

#define __MSGCMD_H__

#include "dstypes.h"

/*

** This is the maximum number of fields that will be encountered

** in a message, including the header field(s).

*/

#define DS_MAXMESSAGEFIELDCOUNT	15

/*

** Some items are declared here only for debug purposes (e.g., 

** string names for messages and fields).  The following macros

** allow these items to be removed when debugging is disabled,

** eliminating otherwise wasted data space.

*/

#ifndef DEBUG_MSGCMD

	#error "DEBUG_MSGCMD must be defined to either 0 or 1"

#endif

#if DEBUG_MSGCMD

	#define __debug_only_parm( x )		x,

	#define __debug_only_field( x )		x;

#else

	#define __debug_only_parm( x )

	#define	__debug_only_field( x )

#endif

/*

** Descriptor for a message field.

*/

typedef struct TrkMsgFieldDesc

{

	__debug_only_field( char *name )	/* Field name - for debugging */

	int length;							/* Length of the field in bytes */

} TrkMsgFieldDesc;

/*

** Use this macro to initialize TrkMsgFieldDesc variables.

*/

#define __trk_msg_field( name, length )	{ __debug_only_parm( name ) length }

/*

** Descriptor for a message.  Each message consists of a header followed

** by additional fields.  Note that length, count, and farray should

** only account for the additional fields.  For example: if the header

** has 1 field and the message has 3 additional fields (4 total), count

** should be 3.

**

** Only fixed-length numeric fields should be included in the descriptor.

** Variable-length portions of a message, such as memory data, are

** typically handled by code that is specific to the message type.

** They are outside the scope of the general-purpose routines which use

** these descriptors.

*/

//#if __MWERKS__

#if 0	/* SCM: MIPS compiler defect generates bad code in this case */

	#define __TrkMsgFieldMax

#else

	#define __TrkMsgFieldMax	DS_MAXMESSAGEFIELDCOUNT

#endif /* #if __MWERKS__ */

typedef struct TrkMsgDesc

{

	__debug_only_field( char *name )	/* Message name - for debugging */

	const struct TrkMsgDesc	*header;	/* Descriptor for header/previous fragment */

	int 				length;			/* Length of the message in bytes */

	unsigned int 		count;			/* Number of fields in the message */

	TrkMsgFieldDesc 	farray[__TrkMsgFieldMax];/* Descriptors for the message fields */

} TrkMsgDesc;

#ifdef TRK_MSGCMD_INIT

	#define DESCDECLNC			

	#define DESCDECL			const

#else

	#define DESCDECLNC			extern

	#define DESCDECL			extern const

#endif

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

/*

 *	Commands

 *

 *	constant definitions of commands sent from host to target

 *

 *	L1 = Level 1 CWDS (required)

 *	L2 = Level 2 CWDS (extended board-level debugger)

 *	L3 = Level 3 CWDS (OS-level debugger)

 */

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

#define DS_PROTOCOL_MIN			1	/* L1 */

#define DS_PROTOCOL_BOARD		2	/* L2 */

#define DS_PROTOCOL_RTOS		3	/* L3 */

#if (!defined( DS_PROTOCOL )) || (DS_PROTOCOL == 0)

	#pragma error "Protocol level must be defined"

#endif

/*

** The current protocol version.

*/

#define DS_PROTOCOL_MAJOR_VERSION_3	3

#define DS_PROTOCOL_MINOR_VERSION_0 0

#define DS_PROTOCOL_MINOR_VERSION_1 1

#define DS_PROTOCOL_MINOR_VERSION_2 2

#define DS_PROTOCOL_MINOR_VERSION_3 3

#define DS_PROTOCOL_MINOR_VERSION_4 4

#define DS_PROTOCOL_MINOR_VERSION_5 5

#define DS_PROTOCOL_MINOR_VERSION_6 6

#define DS_PROTOCOL_MAJOR_VERSION	DS_PROTOCOL_MAJOR_VERSION_3

#define DS_PROTOCOL_MINOR_VERSION   DS_PROTOCOL_MINOR_VERSION_6

#define DS_PROTOCOL_VERSION_STRING	version_str( DS_PROTOCOL_MAJOR_VERSION, \

												 DS_PROTOCOL_MINOR_VERSION )

/*

** Named constants for significant protocol revisions can be added

** here (the existing definitions should not be changed).

*/

/* Sequence IDs were introduced in version 2.0 */

#define DS_PROTOCOL_MAJOR_VERSION_SEQUENCEIDS	2

#define DS_PROTOCOL_MINOR_VERSION_SEQUENCEIDS	0

/* Multi-channel communication, ethernet, & other comm enhancements in 3.0 */

#define DS_PROTOCOL_MAJOR_VERSION_MULTICHANNEL	3

#define DS_PROTOCOL_MINOR_VERSION_MULTICHANNEL	0

#if __MWERKS__

#pragma mark  MessageCommandID command value list

#endif /* __MWERKS__ */

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

/*

 *	MessageCommandID command value list

 */

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

typedef enum MessageCommandID

{

	/* meta commands, minimum feature set */

	kDSPing						= 0x00,		/*					*/

	kDSConnect					= 0x01,		/*	L1	L2	L3		*/

	kDSDisconnect				= 0x02,		/*			L3		*/

	kDSReset					= 0x03,		/*		L2	L3		*/

	kDSVersions					= 0x04,		/*	L1	L2	L3		*/

	kDSSupportMask              = 0x05,     /*  L1	L2	L3      */

	kDSCPUType					= 0x06,		/*		L2	L3		*/

	kDSConfigTransport			= 0x07,		/*		L2	L3		*/

	kDSVersions2				= 0x08,		/*	L1	L2	L3		*/

	kDSHostVersions				= 0x09,

	/* state commands */

	kDSReadMemory				= 0x10,		/*	L1	L2	L3		*/

	kDSWriteMemory				= 0x11,		/*	L1	L2	L3		*/

	kDSReadRegisters			= 0x12,		/*	L1	L2	L3		*/

	kDSWriteRegisters			= 0x13,		/*	L1	L2	L3		*/

	kDSFillMemory				= 0x14,		/*					*/

	kDSCopyMemory				= 0x15,		/*					*/

	kDSFlushCache				= 0x16,		/*					*/

	/* execution commands */

	kDSContinue					= 0x18,		/*	L1	L2	L3		*/

	kDSStep						= 0x19,		/*		L2	L3		*/

	kDSStop						= 0x1a,		/*		L2	L3		*/

	kDSSetBreak					= 0x1b,		/*		L2	L3		*/

	kDSClearBreak				= 0x1c,		/*		L2	L3		*/

	kDSDownload					= 0x1d,		/*					*/

	kDSModifyBreakThread		= 0x1e,		/*			L3		*/

	/* Note: kDSSetWatch & kDSClearWatch are obsolete and have been removed */

	/* host->target IO management */

	kDSNotifyFileInput			= 0x20,		/*		L2	L3		*/

	kDSBlockFileIo				= 0x21,		/*		L2	L3		*/

	/* host->target OS commands */

	kDSOSCreateItem				= 0x40,		/*			L3		*/

	kDSOSDeleteItem				= 0x41,		/*			L3		*/

	kDSOSReadInfo				= 0x42,		/*			L3		*/

	kDSOSWriteInfo				= 0x43,		/*			L3		*/

	kDSOSWriteFile				= 0x48,		/*			L3		*/

	kDSOSReadFile				= 0x49,		/*			L3		*/

	kDSOSOpenFile				= 0x4a,		/*			L3		*/

	kDSOSCloseFile				= 0x4b,		/*			L3		*/

	kDSOSPositionFile			= 0x4c,		/*			L3		*/

	kDSOSInstallFile			= 0x4d,		/*			L3		*/

	kDSOSInstallFile2			= 0x4e,		/*			L3		*/

	kDSOSPhoneSWVersion         = 0x4f,		/*			L3		*/

	kDSOSPhoneName              = 0x50,		/*			L3		*/

	kDSVersions3				= 0x51,		/*	L1	L2	L3		*/

	/*

	 * 0x70 - 0x7F reserved for host->target target-specific commands

	 */

	/* replies */

	kDSReplyACK					= 0x80,		/*	L1	L2	L3		*/

	kDSReplyNAK					= 0xFF,		/*	L1	L2	L3		*/

	/*

	 * target->host notification

	 */

	kDSNotifyStopped			= 0x90,		/*	L1	L2	L3		*/

	kDSNotifyException			= 0x91,		/*  OBSOLETE!       */

		/* kDSNotifyException (0x91) is included for historical */

		/* reasons only; DON'T IMPLEMENT IN NEW DEBUG NUB CODE! */

	kDSNotifyInternalError		= 0x92,		/*					*/

//not used, remove?	kDSNotifyBreak				= 0x93,		/*		L2	L3		*/

	kDSNotifyStopped2			= 0x94,		/*			L3		*/

	/*

	 * target->host OS notification

	 */

	kDSOSNotifyCreated			= 0xa0,		/*			L3		*/

	kDSOSNotifyDeleted			= 0xa1,		/*			L3		*/

	kDSOSNotifyProcessorStarted	= 0xa2,		/*          L3      */

	kDSOSNotifyProcessorStandby	= 0xa6,		/*			L3		*/

	kDSOSNotifyProcessorReset	= 0xa7,		/*			L3		*/

	/*

	 * target->host support commands

	 */

	kDSWriteFile				= 0xD0,		/*		L2	L3		*/

	kDSReadFile					= 0xD1,		/*		L2	L3		*/

	kDSOpenFile					= 0xD2,		/*		L2	L3		*/

	kDSCloseFile				= 0xD3,		/*		L2	L3		*/

	kDSPositionFile				= 0xD4		/*		L2	L3		*/

	/*

	 * 0xE0 - 0xEF reserved for target->host target-specific commands

	 */

} MessageCommandID;

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

/*

 *

 *	Formatted data for messages sent between host and target.

 *

 *	Primitive Scalar Types:

 *

 *		Only use hard data types with fixed sizes:

 *		ui8		8-bit unsigned integer

 *		ui16	16-bit unsigned integer

 *		ui32	32-bit unsigned integer

 *		ui8 []	array of bytes

 *		char[]	array of characters (C string)

 *		etc.

 *	

 *	Endian:

 *

 *		Messages are sent in big-endian format.

 *

 *		Example layouts:

 *

 *   Type Value                  Big Endian                    Little Endian

 * -------------------- ---------------------------     ---------------------------

 *    ui8 0x12          [0x12]                          [0x12]

 *   ui16 0x1234        [0x12] [0x34]					[0x34] [0x12]

 *   ui32 0x12345678    [0x12] [0x34] [0x56] [0x78]     [0x78] [0x56] [0x34] [0x12]

 *  ui8[] 0x12 0x34     [0x12] [0x34]                   [0x12] [0x34]

 * ui16[] 0x1234 0x5678 [0x12] [0x34] [0x56] [0x78]     [0x34] [0x12] [0x78] [0x56]

 * ui32[] 0x12345678    [0x12] [0x34] [0x56] [0x78]     [0x78] [0x56] [0x34] [0x12]

 *        0x9ABCDEF0    [0x9A] [0xBC] [0xDE] [0xF0]     [0xF0] [0xDE] [0xBC] [0x9A]

 * char[] "Abcd 234"    [0x41] [0x62] [0x63] [0x64]     [0x41] [0x62] [0x63] [0x64]

 *                      [0x20] [0x32] [0x33] [0x34]     [0x20] [0x32] [0x33] [0x34]

 *

 *	Alignment:

 *		

 *    Messages have no alignment restrictions.  For transmission efficiency,

 *    alignment padding is not recommended in messages.

 */

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

#if __MWERKS__

#pragma mark  -

#pragma mark Message Formats

#endif /* __MWERKS__ */

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

/*

 *	M E S S A G E  F O R M A T S

 */

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

#if __MWERKS__

#pragma mark  Message Header (common)

#endif /* __MWERKS__ */

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

/*

 *	Message Header (new format):

 *

 *		ui8		command				- (1) MessageCommandID

 *		ui8		sequenceId			- (1) sequence ID of message

 *									  <2> total

 *	- OR - (old format):

 *

 *		ui8		command				- (1) MessageCommandID

 *									  <1> total

 *

 *	All messages, including replies begin with this header.  Some may consist

 *	of nothing else (e.g., the Reset message).  Others contain additional

 *	information following the header.

 *

 *	Currently MetroTRK only supports sending 1 message at a time, which

 *	means that the sender must wait for a reply to each message before

 *	sending the next message.  For this case, the sequence IDs follow

 *	these rules:

 *		- For non-reply messages, the sequence ID should be 1 larger

 *		  than the sequence ID of the previous message from the same

 *		  sender, or 0x01 if the previous value was 0xFF.  The host

 *		  and target sequence ID's are independent.

 *		  A sequence ID of 0 is a special case.  It is always valid

 *		  and resets the sequence so that the next expected ID is 1

 *        for both the host and target.

 *		- For ACK reply messages, the sequence ID should equal the

 *		  sequence ID of the message to which it is replying.

 *		- For NAK reply messages, if the error code is 

 *		  kDSReplySequenceMissing then the sequence ID should be the

 *		  next value that was expected by the receiver.  For

 *		  any other error code, the sequence ID is indeterminate.

 *		- If a received, non-reply sequence ID is the same as the 

 *		  previous received sequence ID, the receiver should re-send

 *		  the reply to the previous message *without* re-processing

 *		  the message.  It is important for certain messages (e.g., file

 *		  writes) that duplicates not be re-processed.

 *		- If a received, non-reply sequence ID is not equal to the

 *		  previous received sequence ID, the next expected ID, or 0,

 *		  the receiver should send a NAK reply with the

 *		  kDSReplySequenceMissing error code and discard the

 *		  received message.

 *

 *	The sequenceId field is new in version 2.0 of the protocol.  For

 *	backwards compatibility, descriptors are included for both the new

 *	and the old header formats.  The new format will be used by default,

 *	but it can be changed at runtime.  The old format can also be forced

 *	at build time by defining the following in target.h:

 *		#define TRK_MSG_SEQUENCE_IDS		0

 *

 */

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

#define TRK_MSG_HEADER_LENGTH		(gTrkMsgHeader.length)

#define TRK_MSG_HEADER_COUNT		2				/* 2 field in header */

/*

** For L1 and L2, sequence IDs are disabled by default.  For L3 they are

** enabled by default.  Individual targets can override this setting by

** defining TRK_MSG_SEQUENCE_IDS in target.h.

*/

#ifndef TRK_MSG_SEQUENCE_IDS

	#if DS_PROTOCOL < DS_PROTOCOL_RTOS

		#define TRK_MSG_SEQUENCE_IDS		0

	#else

		#define TRK_MSG_SEQUENCE_IDS		1

	#endif

#endif

/* The current header descriptor as of protocol version 2.0 */

#define TRK_MSG_HEADER_20_INIT \

{ \

	__debug_only_parm( "Header" ) \

	NULL,										/* previous fragment/header */ \

	2,											/* # of bytes */ \

	TRK_MSG_HEADER_COUNT,						/* # of fields */ \

	{						/* field descriptors: */ \

		__trk_msg_field( "command", 1 ), \

		__trk_msg_field( "sequence ID", 1 ) \

	} \

}

DESCDECL TrkMsgDesc gTrkMsgHeader20

#ifdef TRK_MSGCMD_INIT

= TRK_MSG_HEADER_20_INIT

#endif /* #ifdef TRK_MSGCMD_INIT */

;

/* The old header descriptor prior to protocol version 2.0 */

#define TRK_MSG_HEADER_PRE_20_INIT \

{ \

	__debug_only_parm( "Header" ) \

	NULL,										/* previous fragment/header */ \

	1,											/* # of bytes */ \

	TRK_MSG_HEADER_COUNT,						/* # of fields */ \

	{						/* field descriptors: */ \

		__trk_msg_field( "command", 1 ), \

		__trk_msg_field( "sequence ID (N/A)", 0 )		/* placeholder to make indices consistent */ \

	} \

}

DESCDECL TrkMsgDesc gTrkMsgHeaderPre20

#ifdef TRK_MSGCMD_INIT

= TRK_MSG_HEADER_PRE_20_INIT

#endif /* #ifdef TRK_MSGCMD_INIT */

;

/* Use new header by default - can be changed at runtime. */

DESCDECLNC TrkMsgDesc gTrkMsgHeader

#ifdef TRK_MSGCMD_INIT

	#if TRK_MSG_SEQUENCE_IDS

		= TRK_MSG_HEADER_20_INIT;

	#else

		= TRK_MSG_HEADER_PRE_20_INIT

	#endif

#endif /* #ifdef TRK_MSGCMD_INIT */

;

/* "Index" of fields. */

#define TRK_MSG_COMMAND_INDEX	0

#define TRK_MSG_SID_INDEX		1

#if __MWERKS__

#pragma mark  Reply Header (common)

#endif /* __MWERKS__ */

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

/*

 *	Reply Message Header

 *

 *		....	<Message Header>	  ... (see gTrkMsgHeader)

 *		ui8		error				- (1) CWDS error value

 *									  <1 + header> total

 *

 *	The command for a reply message must be either kDSReplyACK or kDSReplyNAK.

 *

 *	A NAK reply indicates that an invalid message or portion of a message

 *  was received.  The error value will specify the problem.

 *

 *	An ACK with an error value other than kDSReplyNoError indicates that 

 *	the message was valid but could not be processed for some reason (e.g.,

 *	invalid memory ranges, bad parameters, etc.).  The error value will

 *	specify the problem.

 *

 *	Some command replies include additional information that is specific to

 *  the command.  This additional information is included ONLY if the 

 *  reply is an ACK with kDSReplyNoError.

 */

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

#define TRK_MSG_REPLY_HEADER_LENGTH	(1 + TRK_MSG_HEADER_LENGTH)	/* 1 addl bytes  */

#define TRK_MSG_REPLY_HEADER_COUNT	(1 + TRK_MSG_HEADER_COUNT)	/* 1 addl fields */

DESCDECL TrkMsgDesc gTrkMsgReplyHeader

#ifdef TRK_MSGCMD_INIT

= {

	__debug_only_parm( "Reply Header" )

	&gTrkMsgHeader,								/* previous fragment/header */

	1,											/* # of addl bytes */

	1,											/* # of addl fields */

	{						/* addl field descriptors: */

		__trk_msg_field( "error", 1 )

	}

}

#endif /* #ifdef TRK_MSGCMD_INIT */

;

/* "Index" of fields.  Take # of header fields into account. */

#define TRK_MSG_REPLY_ERROR_INDEX			(0 + TRK_MSG_HEADER_COUNT)

/* Retain these for compatibility with older code */

#define DS_MIN_MSG_LENGTH					TRK_MSG_HEADER_LENGTH

#define DS_MIN_REPLY_LENGTH					TRK_MSG_REPLY_HEADER_LENGTH

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

/*

 *	Required Send and Reply Messsages

 */

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

#if __MWERKS__

#pragma mark  Ping

#endif /* __MWERKS__ */

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

/*

 *	kDSPing

 *

 *	Send:

 *

 *		....	<Message Header>	  ... (see gTrkMsgHeader)

 *									  <header> total

 *	Reply:

 *

 *		....	<Reply Header>		  ... (see gTrkMsgReplyHeader)

 *									  <header> total

 *	

 *	Can be sent by the host at any time.  Simply replies with an

 *	ACK.  Currently not supported.

 */

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

#define DS_MIN_MSG_PING_LENGTH				DS_MIN_MSG_LENGTH

#define DS_MIN_REPLY_PING_LENGTH			DS_MIN_REPLY_LENGTH

#if __MWERKS__

#pragma mark  Connect

#endif /* __MWERKS__ */

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