adp.h

ARM入门的好帮手.包含了从简单到相对较复杂的程序.

/* -*-C-*-
 *
 * $Revision: 1.15.2.3 $
 *   $Author: rivimey $
 *     $Date: 1998/01/28 12:30:10 $
 *
 * Copyright (c) 1996 Advanced RISC Machines Limited.
 * All Rights Reserved.
 *
 *
 * INTRODUCTION
 * ------------
 * The early RDP message definitions were held in an ARM Ltd "armdbg"
 * source file. Since the relevant header files were not exported
 * publicly as part of an ARM Ltd core tools release, it was a problem
 * for developers manipulating the target side of the protocol.
 *
 * For Angel, this new (ANSI 'C' clean) header file defines the ADP
 * protocol. The header should be useable by both host and target
 * systems, thus avoiding problems that can arise from duplicate
 * definitions. Care has been taken in the construction of this header
 * file to avoid any host/target differences.
 *
 * MESSAGE FORMAT
 * --------------
 * Format of the "data" section of debug and boot agent messages. This is
 * the standard ADP (Angel Debug Protocol) message format:
 *
 *  unsigned32 reason     - Main debug reason code.
 *  unsigned32 debugID    - Information describing host debug world;
 *                        - private to host and used in any target initiated
 *                          messages.
 *  unsigned32 OSinfo1    \ Target OS information to identify process/thread
 *  unsigned32 OSinfo2    / memory/world, etc. These two fields are target
 *                          defined.
 *  byte       args[n]    - Data for message "reason" code.
 *
 * NOTE: The message format is the same for single threaded debugging,
 * except that the "OSinfo" fields should be -1 (0xFFFFFFFF). Even
 * single-threaded debugging *MAY* have different host specified
 * debugID values, so the Angel debug system will preserve the "debugID"
 * information for replies, and the relevant asynchronous target-to-host
 * messages. The "debugID" is defined by the host-end of the
 * protocol, and is used by the host to ensure that messages are
 * routed to the correct handler program/veneer.
 *
 * The reason there are two target specified "OSinfo" words is because
 * thread identifiers may not be unique when processes/tasks have
 * private virtual address spaces. It allows more flexibility when
 * supporting multi-threaded or O/S aware debugging.
 *
 * NOTE: The reason that there is no "size" information, is that the
 * message IDs themselves encode the format of any arguments. Also it
  * would be a duplication of information used by the physical
 * transport layer (which is distinct from this logical message
 * layer). Any routing of messages through programs, hosts,
 * etc. should be performed at the physical layer, or the boundaries
 * between physical layers. i.e. packet received on socket in host,
 * and transferred to serial packet for passing on down the line.
 *
 * NOTE: Pointers aren't passed in messages because they are dangerous in
 * a multi-threaded environment.
 *
 * ADP REASON CODE
 * ---------------
 * The message reason codes contain some information that ties them to
 * the channel and direction that the message will be used with. This
 * will ensure that even if the message "#define name" is not
 * completely descriptive, the message reason code is.
 *
 *      b31    = direction. 0=Host-to-Target; 1=Target-to-Host;
 *      b30-28 = debug agent multi-threaded control (see below)
 *      b27-24 = reserved. should be zero.
 *      b23-16 = channelid. The fixed Angel channel number
 *               (see "channels.h").
 *      b15-0  = message reason code.
 *
 * It is unfortunate that to aid the error-checking capabilities of
 * the Angel communications we have changed the message numbers from
 * the original ARM Ltd RDP. However this also has benefits, in that
 * the Angel work is meant to be a clean break.
 *
 * However, it isn't so bad since even though the numbers are
 * different, the majority of the reason codes have exactly the same
 * functionality as the original RDP messages.
 *
 * NOTES
 * -----
 * It would be ideal to use "rpcgen" (or some equivalent) to
 * automatically maintain compatibility between the target and host
 * ends of the protocol. However, ARM Ltd expressed that the message
 * handling should be hand-coded, to avoid dependance on external
 * tools.
 *
 * All other channels have undefined data formats and are purely
 * application defined. The C library "_sys_" support will provide a
 * veneer to perform message block operations as required.
 *
 * It is IMPLIED that all of the ADP messages will fit within the
 * buffer DATASIZE. This has a minimum value, calculated from
 * BUFFERMINSIZE.
 *
 * All messages are passed and received to the channel system in little
 * endian order (ie. use little endian order when writing a word as
 * a sequence of bytes within a message).
 *
 * A reply / acknowledgement to an ADP message is always sent and has the
 * same reason code as the original except that the TtoH / HtoT bit is
 * reversed.  This makes it simple to check that the reply really
 * is a reply to the message which was just sent!  [Boot Channel messages
 * also require that this protocol is used].
 */

#ifndef angel_adp_h
#define angel_adp_h

#include "chandefs.h"


/*
 * Buffer minimum sizes
 */

/* the minimum target internal size */
#define ADP_BUFFER_MIN_SIZE (256)

/* a word is always reserved for internal use in the target */
#define ADP_BUFFER_MAX_INTERNAL (sizeof(word))

/* the minimum available data portion */
#define ADP_BUFFER_MIN_DATASIZE \
    (ADP_BUFFER_MIN_SIZE - ADP_BUFFER_MAX_INTERNAL - CHAN_HEADER_SIZE)

/*
 * the space taken up by the standard ADP header
 * (reason, debugID, OSinfo1, OSinfo2)
 */
#define ADP_DEFAULT_HEADER_SIZE (4*sizeof(word))


/* 8bit ADP version identification */
#define ADPVSN  (0x03)
/* This value can be used to identify the protocol version supported
 * by target or host systems. This version number should only be
 * changed if the protocol undergoes a non-backward compatible
 * change. It should *NOT* be used to reflect extensions to the
 * protocol. Such extensions can be added to the existing protocol
 * version by allocating new reason codes, and by extending the
 * ADP_Info message to identify new features.
 */

/* The following value is used in the OSinfo fields for
 * single-threaded messages, or where the host wants to alter the
 * global CPU state. NOTE: The "debugID" field should always be
 * defined by the host, and returned in target initiated messages. The
 * only exception to this rule is the ADP_Booted message at the
 * start-of-day.
 */
#define ADP_HandleUnknown (-1)

/******************************************************************
 *
 * ADP reason code subfields
 *
 */

/* The following bits are used to describe the basic direction of
 * messages. This allows some extra checking of message validity to be
 * performed, as well as providing a description of the message that
 * may not be available in the "cpp" macro:
 */
#define HtoT    ((unsigned)0 << 31)     /* Host-to-Target message */
#define TtoH    ((unsigned)1 << 31)     /* Target-to-Host message */

/* The following bits are used to control how the target system
 * executes whilst processing messages. This allows for O/S specific
 * host-based debug programs to interrogate system structures whilst
 * ensuring that the access is atomic within the constraints imposed
 * by the target O/S.
 *
 * NOTE: That only the channel is inserted into the reason code
 * automatically.  Thus both direction and multi thread control bits
 * must be added by the host / target.
 */
/* Disable FIQ whilst processing message */
#define DisableFIQ              (1 << 30)
/* Disable IRQ whilst processing message */
#define DisableIRQ              (1 << 29)
/* Disable O/S pre-emption whilst processing message */
#define DisablePreemption       (1 << 28)

/* The channel identification number is held in the reason code as a
 * check:
 */
#define ADPCHANNEL(b)   (((b) & 0xFF) << 16)

/* The following macro constructs the reason code number, from the
 * various fields - note that the direction is NOT inlcuded since
 * this depends on whether the Host or Target system is including
 * this file!
 */
#define ADPREASON(c,r)        (ADPCHANNEL(c) | ((r) & 0xFFFF))

/* This macros is used when constructing manifests for sub-reason
 * codes. At the moment it is identical to the main reason macro. If
 * desired we could add a new bit that explicitly identifies the value
 * as a sub-reason code, where the corresponding bit in the main
 * message ID would be zero.
 */
#define ADPSUBREASON(c,r)     (ADPCHANNEL(c) | ((r) & 0xFFFF))

/* All other undefined bits are reserved, and should be zero. */



/*****************************************************************
 *
 * channel_BOOT messages
 *
 */

/* The BOOT agent only supports a few messages. They are used purely
 * to control the "start-of-day" connection to a host program. All
 * Angel systems with host communications *MUST* provide the BOOT
 * agent, even if they don't have support for either the single- or
 * multi-threaded debug agents.
 *
 * The way the BOOT channel will be used on startup will be as follows:
 *
 * a) Target board is powered up before host debugger is invoked
 *
 * After switching on the target and initialisation is completed the
 * target will send an ADP_Booted or ADP_Reset message.  The debugger
 * has not been started yet so this message will not be received.  In
 * a serial world this makes it important that any buffers on the host
 * side are flushed during initialisation of the debugger, and in an
 * Ethernet world it makes it important that the target can cope with the
 * message not being received.
 *
 * Eventually the Debugger will be started up and will send an
 * ADP_Reboot or ADP_Reset request.  The target will respond to this with
 * an ADP_Reboot or ADP_Reset acknowldege and will then reboot, finally
 * sending an ADP_Rebooted when it has done all it needs to do (very little
 * in the case of ADP_Reset, but completely rebooting in the case of
 * ADP_Reboot).  Note that it is important that an ADP_Rebooted message is
 * sent so that the Debugger does not attempt to send any data after it has
 * made a request to ADP_Reboot and before it receives an ADP_Rebooted, as
 * data can be lost be the target during this time.
 *
 * The target and host are now ready to start a debug session.
 *
 * b) Target board is powered up after host debugger is invoked
 *
 * The debugger will send an ADP_Reboot or ADP_Reset request, but will
 * receive no reply until the target is powered up.
 *
 * When the target is powered up then it will send an ADP_Rebooted
 * message to the debugger.  The debugger should accept this message
 * even though it has received no ADP_Reboot or ADP_Reset acknowldege message
 * from the target.
 *
 * The target and host are now ready to start a debug session.
 *
 *
 * If at any point during the bootup sequence and ADP messages are
 * sent down the S_DBG channel then they should be responded to with a
 * RDI_NotInitialised error. [This should never happen however].
 *
 * An ADP_Boot or ADP Rebooted message should be accepted at
 * any point, since it is possible for a catastrophe to occur (such as
 * disconnecteing the host and target during a debug message) which
 * requires that one or other end be reset.
 *
 */

/*
 * A list of parameter types - for now just baud rate
 */
typedef enum ADP_Parameter {
    AP_PARAMS_START = 0xC000,
    AP_BAUD_RATE = AP_PARAMS_START,
    /* extra parameters go in here */
#ifdef TEST_PARAMS
    AP_CAFE_MENU,               /* extra just for testing */
#endif
    AP_PARAMS_END
} ADP_Parameter;

/* #define AP_NUM_PARAMS (AP_PARAMS_END - AP_PARAMS_START) */

/* Currently, 1 is needed by baud setup. I have set it to 4 for future */
/* compatibility.                                                      */
#define AP_NUM_PARAMS    4

/*
 * Parameter types should have associated semantics which can be represented
 * within one word per parameter, or an associated enum for choices.
 *
 * AP_BAUD_RATE: the word contains the exact baud rate, eg. 9600, 38400.
 */

/* this is not strictly necessary, but it's an example */
typedef enum ADP_BaudRate {
    AB_1200  =  1200,
    AB_2400  =  2400,
    AB_4800  =  4800,
    AB_9600  =  9600,
    AB_19200 = 19200,
    AB_38400 = 38400,
    AB_57600 = 57600,
    AB_115200 = 115200,
    AB_230400 = 230400
} ADP_BaudRate;

#define AB_NUM_BAUD_RATES 9     /* this is more useful, for sizing arrays */

/* This must be set to the max number of options per parameter type      */
/* Currently, 9 are needed by baud rates. I have set it to 12 for future */
/* compatibility.                                                        */
#define AP_MAX_OPTIONS  12


#define ADP_Booted      ADPREASON(CI_TBOOT,0)
/* This message is sent by the target after the Angel system has been
 * initialised.  This message also contains information describing the
 * Angel world. The information can then be used to check that the
 * target debug agent and source debugger are compatible.
 *
 * Message arguments:
 *      word    Angel message default buffer size.
 *      word    Angel message large buffer size (may be same as default)
 *      word    Angel version ; inc. type (e.g. boot ROM) See (1)
 *      word    ADP version.  See (2)
 *      word    ARM Architecture info See (3)
 *      word    ARM CPU information ; including target endianness. See (4)
 *      word    Target hardware status. See (5)
 *      word    Number of bytes in banner message
 *      bytes   Startup banner message (single-threaded readable
 *              descriptive text - NOT NULL terminated).
 *
 * Reply:
 *      word    status
 *
 *      'status' returns RDIError_NoError for success, and otherwise
 *      indicates an error.
 */

/* Angel version word [Reference(1)] : */
/* Angel version number is a 16bit BCD value */
#define ADP_ANGELVSN_MASK           (0x0000FFFF)
#define ADP_ANGELVSN_SHIFT          (0)

/* Type of Angel system */
#define ADP_ANGELVSN_TYPE_MASK      (0x00FF0000)
#define ADP_ANGELVSN_TYPE_SHIFT     (16)

typedef enum {
 ADP_AngelType_bootROM, /* Simple ROM system providing download capability */
 ADP_AngelType_appROM,  /* ROM based application */
 ADP_AngelType_appDLOAD,/* Downloaded Angel based application */
 ADP_AngelType_Last     /* Unknown type. This typedef can be extended */
                        /* but if the host and target vsns differ */
                        /* Then one will spot that it dies not understand */
} ADP_Angel_Types ;     /* this field and can whinge appropriately */

/* First unknown ADP_AngelType */
#define ADP_ANGELVSN_UNKTYPE_MASK   (0xFF000000)