angel_reasons.h

realview22.rar

/* -*-C-*-
 *
 * $Revision: 1.1.10.2 $
 *   $Author: lmacgreg $
 *     $Date: 2001/08/24 12:57:49 $
 *
 * Copyright (c) 1996 Advanced RISC Machines Limited.
 * Copyright (C) 2000 - 2001 ARM Ltd.  All rights reserved.
 * All Rights Reserved.
 */
#ifndef angel_reasons_h
#define angel_reasons_h

#include "angel_chandefs.h"


#if defined(__cplusplus) && !defined(CLX_CPP_LINKAGE)
extern "C" {
#endif
/******************************************************************
 *
 * 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:
 */

/* 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)
#define ADP_ANGELVSN_UNKYPE_SHIFT   (24)

/* Currently only 8 bits are used in the word: */
/* ADP protocol supported by target [Reference (2)] */
#define ADP_ANGELVSN_ADP_MASK       (0x000000FF)
#define ADP_ANGELVSN_ADP_SHIFT      (0)

/* ARM Architecture info: [Reference (3)] */
/* ARM Architecture Verson of target CPU */
#define ADP_ARM_ARCH_VSN_MASK       (0x000000FF)
#define ADP_ARM_ARCH_VSN_SHIFT      (0)
/* Does the processor support the Thumb Instruction Set */
#define ADP_ARM_ARCH_THUMB          (0x80000000)
/* Does the processor support Long Multiplies */
#define ADP_ARM_ARCH_LONGMUL        (0x40000000)
/* All other flags are current undefined, and should be zero. */

/* The following flags describe the feature set of the processor: */
/* Set if cpu supports little-endian model [Reference (4)] */
#define ADP_CPU_LE              (1 << 0)
/* Set if cpu supports big-endian model */
#define ADP_CPU_BE              (1 << 1)
/* Set if processor has a cache */
#define ADP_CPU_CACHE           (1 << 2)
/* Set if processor has a MMU */
#define ADP_CPU_MMU             (1 << 3)
/* All other flags are current undefined, and should be zero. */

/* The following flags reflect current Target hardware status: */
/* [Reference (5)] */
/* 0 = no MMU or MMU off; 1 = MMU on */
#define ADP_CPU_MMUOn           (1 << 29)
/* 0 = no cache or cache off; 1 = cache on */
#define ADP_CPU_CacheOn         (1 << 30)
/* 0 = little-endian; 1 = big-endian */
#define ADP_CPU_BigEndian       (1U << 31)
/* All other flags are current undefined, and should be zero. */


#ifdef LINK_RECOVERY

#define ADP_TargetResetIndication       ADPREASON(CI_TBOOT, 1)
/*
 * If parameter negotiation is enabled at the target, it configures itself
 * to various likely parameter settings and sends this message at each
 * configuration.  The message describes the default settings, and after
 * sending at each configuration the target sets itself to the defaults
 * it has just broadcast, to await either an ack on TBOOT or a request
 * or reset indication on HBOOT.
 *
 * If the host receives this message successfully, it should reset to the
 * indicated parameters and send a reply.
 *
 * Message arguments:
 *      word    status                   (always 0, makes body same as
 *                                        ADP_ParamNegotiate response)
 *      word    n-parameters
 *      n-parameters * {
 *              word    ADP_Parameter
 *              word    parameter-value
 *      }
 *
 * Reply:
 *      -       empty acknowledgement
 */

#endif /* def LINK_RECOVERY */

typedef enum ADP_Boot_Ack {
    AB_NORMAL_ACK,              /* will comply, immediate booted message */
    AB_LATE_ACK,                /* will comply, late startup */
    AB_ERROR                    /* cannot comply */
} ADP_Boot_Ack;

/* If the host sets neither of these in the word sent on a Reset / Reboot
 * then it doesn;t care about the endianess of the target
 */
#define ADP_BootHostFeature_LittleEnd 0x80000000
#define ADP_BootHostFeature_BigEnd    0x40000000

#define ADP_Reboot      ADPREASON(CI_HBOOT,2)
/* This message is sent when the host wants the target system to be
 * completely reset, back to the boot monitor Angel. This is the
 * method of the host forcing a cold-reboot.
 * Note that an acknowledgement message will be sent immediately and
 * that this must be sent before the target can reset.
 *
 * The parameter to this function is a bitset of host supported
 * features. (in fact the same as ADP_Reset below.  This can be used by
 * the target system to avoid using debug channel bandwidth raising
 * messages that will be ignored by the host.
 *
 * Parameters:
 *      word    host supported features (see above)
 *
 * Reply:
 *      word    status, one of enum ADP_Boot_Ack above.
 *
 * Currently there are no such features defined, so the word indicating
 * host supported features should be set to 0.
 */



#define ADP_Reset       ADPREASON(CI_HBOOT,3)
/* This message is a request from the host, which should eventually
 * result in the "ADP_Booted" message being sent by the target.
 * Note that an acknowledgement message will be sent immediately and
 * that this must be sent before the target can reset.
 * This reset message is *ALWAYS* treated as a warm boot, with the target
 * preserving as much state as possible.
 *
 * The parameter to this function is a bitset of host supported
 * features. This can be used by the target system to avoid using
 * debug channel bandwitdth raising messages that will be ignored by
 * the host.
 *
 * Parameters:
 *      word    host supported features (see above)
 *
 * Reply:
 *      word    status, one of enum ADP_Boot_Ack above.
 *
 * Currently there are no such features defined, so the word indicating
 * host supported features should be set to 0.
 */


#ifdef LINK_RECOVERY

#define ADP_HostResetIndication         ADPREASON(CI_HBOOT, 4)
/*
 * This is as for ADP_TargetResetIndication, but is sent by the host when
 * it first starts up in case the target is listening at a non-default
 * setting.  Having sent at various configurations, the host then listens
 * at the defaults it has just broadcast, to await either an ack on HBOOT
 * or a reset indication on TBOOT.
 *
 * For arguments and reply, see ADP_TargetResetIndication.
 */

#endif /* def LINK_RECOVERY */


#define ADP_ParamNegotiate              ADPREASON(CI_HBOOT, 5)
/*
 * The host sends this messages to negotiate new parameters with the target.
 * For each parameter the host specifies a range of possibilities, starting
 * with the most favoured.  All possible combinations of parameters
 * must be valid.
 *
 * If the target can operate at a combination of the offered parameters,
 * it will reply with the parameters it is willing to use.  AFTER sending
 * the reply, the target switches to this combination.  On receiving the
 * reply, the host will switch to the new combination and send a LinkCheck
 * message (see below).
 *