[openocd.git] / src / target / arm11_dbgtap.c

/***************************************************************************
 *   Copyright (C) 2008 digenius technology GmbH.                          *
 *                                                                         *
 *   This program is free software; you can redistribute it and/or modify  *
 *   it under the terms of the GNU General Public License as published by  *
 *   the Free Software Foundation; either version 2 of the License, or     *
 *   (at your option) any later version.                                   *
 *                                                                         *
 *   This program is distributed in the hope that it will be useful,       *
 *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
 *   GNU General Public License for more details.                          *
 *                                                                         *
 *   You should have received a copy of the GNU General Public License     *
 *   along with this program; if not, write to the                         *
 *   Free Software Foundation, Inc.,                                       *
 *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
 ***************************************************************************/

#ifdef HAVE_CONFIG_H
#include "config.h"
#endif

#include "arm11.h"
#include "jtag.h"
#include "log.h"

#include <stdlib.h>
#include <string.h>

#if 0
#define JTAG_DEBUG(expr ...) \
        do { \
            log_printf (LOG_DEBUG, __FILE__, __LINE__, __FUNCTION__, expr); \
        } while(0)
#else
#define JTAG_DEBUG(expr ...) \
        do {} while(0)
#endif

/** Code de-clutter: Construct scan_field_t to write out a value
 *
 * \param arm11         Target state variable.
 * \param num_bits      Length of the data field
 * \param out_data      pointer to the data that will be sent out
 *                      <em>(data is read when it is added to the JTAG queue)</em>
 * \param in_data       pointer to the memory that will receive data that was clocked in
 *                      <em>(data is written when the JTAG queue is executed)</em>
 * \param field target data structure that will be initialized
 */
void arm11_setup_field(arm11_common_t * arm11, int num_bits, void * out_data, void * in_data, scan_field_t * field)
{
    field->device               = arm11->jtag_info.chain_pos;
    field->num_bits             = num_bits;
    field->out_mask             = NULL;
    field->in_check_mask        = NULL;
    field->in_check_value       = NULL;
    field->in_handler           = NULL;
    field->in_handler_priv      = NULL;

    field->out_value            = out_data;
    field->in_value             = in_data;
}


/** Write JTAG instruction register
 *
 * \param arm11 Target state variable.
 * \param instr An ARM11 DBGTAP instruction. Use enum #arm11_instructions.
 * \param state Pass the final TAP state or -1 for the default value (Pause-IR).
 *
 * \remarks This adds to the JTAG command queue but does \em not execute it.
 */
void arm11_add_IR(arm11_common_t * arm11, u8 instr, enum tap_state state)
{
    jtag_device_t *device = jtag_get_device(arm11->jtag_info.chain_pos);

    if (buf_get_u32(device->cur_instr, 0, 5) == instr)
    {
        JTAG_DEBUG("IR <= 0x%02x SKIPPED", instr);
        return;
    }

    JTAG_DEBUG("IR <= 0x%02x", instr);

    scan_field_t field;

    arm11_setup_field(arm11, 5, &instr, NULL, &field);

    jtag_add_ir_scan_vc(1, &field, state == -1 ? TAP_PI : state);
}

/** Verify shifted out data from Scan Chain Register (SCREG)
 *  Used as parameter to scan_field_t::in_handler in
 *  arm11_add_debug_SCAN_N().
 *
 */
static int arm11_in_handler_SCAN_N(u8 *in_value, void *priv, struct scan_field_s *field)
{
    /** \todo TODO: clarify why this isnt properly masked in jtag.c jtag_read_buffer() */
    u8 v = *in_value & 0x1F;

    if (v != 0x10)
    {
        ERROR("'arm11 target' JTAG communication error SCREG SCAN OUT 0x%02x (expected 0x10)", v);
        exit(-1);
    }

    JTAG_DEBUG("SCREG SCAN OUT 0x%02x", v);
    return ERROR_OK;
}

/** Select and write to Scan Chain Register (SCREG)
 * 
 * This function sets the instruction register to SCAN_N and writes
 * the data register with the selected chain number.
 *
 * http://infocenter.arm.com/help/topic/com.arm.doc.ddi0301f/Cacbjhfg.html
 *
 * \param arm11     Target state variable.
 * \param chain     Scan chain that will be selected.
 * \param state     Pass the final TAP state or -1 for the default
 *                  value (Pause-DR).
 *
 * The chain takes effect when Update-DR is passed (usually when subsequently
 * the INTEXT/EXTEST instructions are written).
 *
 * \warning (Obsolete) Using this twice in a row will \em fail. The first call will end
 *          in Pause-DR. The second call, due to the IR caching, will not
 *          go through Capture-DR when shifting in the new scan chain number.
 *          As a result the verification in arm11_in_handler_SCAN_N() must
 *          fail.
 *
 * \remarks This adds to the JTAG command queue but does \em not execute it.
 */

void arm11_add_debug_SCAN_N(arm11_common_t * arm11, u8 chain, enum tap_state state)
{
    JTAG_DEBUG("SCREG <= 0x%02x", chain);

    arm11_add_IR(arm11, ARM11_SCAN_N, -1);

    scan_field_t                field;

    arm11_setup_field(arm11, 5, &chain, NULL, &field);

    field.in_handler = arm11_in_handler_SCAN_N;

    jtag_add_dr_scan_vc(1, &field, state == -1 ? TAP_PD : state);
}

/** Write an instruction into the ITR register
 * 
 * \param arm11 Target state variable.
 * \param inst  An ARM11 processor instruction/opcode.
 * \param flag  Optional parameter to retrieve the InstCompl flag
 *              (this will be written when the JTAG chain is executed). 
 * \param state Pass the final TAP state or -1 for the default
 *              value (Run-Test/Idle).
 *
 * \remarks By default this ends with Run-Test/Idle state
 * and causes the instruction to be executed. If
 * a subsequent write to DTR is needed before
 * executing the instruction then TAP_PD should be
 * passed to \p state.
 *
 * \remarks This adds to the JTAG command queue but does \em not execute it.
 */
void arm11_add_debug_INST(arm11_common_t * arm11, u32 inst, u8 * flag, enum tap_state state)
{
    JTAG_DEBUG("INST <= 0x%08x", inst);

    scan_field_t                itr[2];

    arm11_setup_field(arm11, 32,    &inst,      NULL, itr + 0);
    arm11_setup_field(arm11, 1,     NULL,       flag, itr + 1);

    jtag_add_dr_scan_vc(asizeof(itr), itr, state == -1 ? TAP_RTI : state);
}

/** Read the Debug Status and Control Register (DSCR)
 *
 * same as CP14 c1
 *
 * \param arm11 Target state variable.
 * \return DSCR content
 * 
 * \remarks This is a stand-alone function that executes the JTAG command queue.
 */
u32 arm11_read_DSCR(arm11_common_t * arm11)
{
    arm11_add_debug_SCAN_N(arm11, 0x01, -1);

    arm11_add_IR(arm11, ARM11_INTEST, -1);

    u32                 dscr;
    scan_field_t        chain1_field;

    arm11_setup_field(arm11, 32, NULL, &dscr, &chain1_field);

    jtag_add_dr_scan_vc(1, &chain1_field, TAP_PD);

    jtag_execute_queue();

    if (arm11->last_dscr != dscr)
        JTAG_DEBUG("DSCR  = %08x (OLD %08x)", dscr, arm11->last_dscr);

    arm11->last_dscr = dscr;

    return dscr;
}

/** Write the Debug Status and Control Register (DSCR)
 *
 * same as CP14 c1
 *
 * \param arm11 Target state variable.
 * \param dscr DSCR content
 * 
 * \remarks This is a stand-alone function that executes the JTAG command queue.
 */
void arm11_write_DSCR(arm11_common_t * arm11, u32 dscr)
{
    arm11_add_debug_SCAN_N(arm11, 0x01, -1);

    arm11_add_IR(arm11, ARM11_EXTEST, -1);

    scan_field_t                    chain1_field;

    arm11_setup_field(arm11, 32, &dscr, NULL, &chain1_field);

    jtag_add_dr_scan_vc(1, &chain1_field, TAP_PD);

    jtag_execute_queue();

    JTAG_DEBUG("DSCR <= %08x (OLD %08x)", dscr, arm11->last_dscr);

    arm11->last_dscr = dscr;
}



/** Get the debug reason from Debug Status and Control Register (DSCR)
 *
 * \param dscr DSCR value to analyze
 * \return Debug reason
 * 
 */
enum target_debug_reason arm11_get_DSCR_debug_reason(u32 dscr)
{
    switch (dscr & ARM11_DSCR_METHOD_OF_DEBUG_ENTRY_MASK)
    {
    case ARM11_DSCR_METHOD_OF_DEBUG_ENTRY_HALT:                 return DBG_REASON_DBGRQ;
    case ARM11_DSCR_METHOD_OF_DEBUG_ENTRY_BREAKPOINT:           return DBG_REASON_BREAKPOINT;
    case ARM11_DSCR_METHOD_OF_DEBUG_ENTRY_WATCHPOINT:           return DBG_REASON_WATCHPOINT;
    case ARM11_DSCR_METHOD_OF_DEBUG_ENTRY_BKPT_INSTRUCTION:     return DBG_REASON_BREAKPOINT;
    case ARM11_DSCR_METHOD_OF_DEBUG_ENTRY_EDBGRQ:               return DBG_REASON_DBGRQ;
    case ARM11_DSCR_METHOD_OF_DEBUG_ENTRY_VECTOR_CATCH:         return DBG_REASON_BREAKPOINT;

    default:
        return DBG_REASON_DBGRQ;
    }
};



/** Prepare the stage for ITR/DTR operations
 * from the arm11_run_instr... group of functions.
 *
 * Put arm11_run_instr_data_prepare() and arm11_run_instr_data_finish()
 * around a block of arm11_run_instr_... calls.
 *
 * Select scan chain 5 to allow quick access to DTR. When scan
 * chain 4 is needed to put in a register the ITRSel instruction
 * shortcut is used instead of actually changing the Scan_N
 * register.
 *
 * \param arm11 Target state variable.
 *
 */
void arm11_run_instr_data_prepare(arm11_common_t * arm11)
{
    arm11_add_debug_SCAN_N(arm11, 0x05, -1);
}

/** Cleanup after ITR/DTR operations
 * from the arm11_run_instr... group of functions
 *
 * Put arm11_run_instr_data_prepare() and arm11_run_instr_data_finish()
 * around a block of arm11_run_instr_... calls.
 *
 * Any RTI can lead to an instruction execution when
 * scan chains 4 or 5 are selected and the IR holds
 * INTEST or EXTEST. So we must disable that before
 * any following activities lead to an RTI.
 *
 * \param arm11 Target state variable.
 *
 */
void arm11_run_instr_data_finish(arm11_common_t * arm11)
{
    arm11_add_debug_SCAN_N(arm11, 0x00, -1);
}


/** Execute one or multiple instructions via ITR
 *
 * \pre arm11_run_instr_data_prepare() /  arm11_run_instr_data_finish() block
 *
 * \param arm11         Target state variable.
 * \param opcode        Pointer to sequence of ARM opcodes
 * \param count         Number of opcodes to execute
 *
 */
void arm11_run_instr_no_data(arm11_common_t * arm11, u32 * opcode, size_t count)
{
    arm11_add_IR(arm11, ARM11_ITRSEL, -1);

    while (count--)
    {
        arm11_add_debug_INST(arm11, *opcode++, NULL, TAP_RTI);

        while (1)
        {
            u8 flag;

            arm11_add_debug_INST(arm11, 0, &flag, count ? TAP_RTI : TAP_PD);

            jtag_execute_queue();

            if (flag)
                break;
        }
    }
}

/** Execute one instruction via ITR
 *
 * \pre arm11_run_instr_data_prepare() /  arm11_run_instr_data_finish() block
 *
 * \param arm11         Target state variable.
 * \param opcode        ARM opcode
 *
 */
void arm11_run_instr_no_data1(arm11_common_t * arm11, u32 opcode)
{
    arm11_run_instr_no_data(arm11, &opcode, 1);
}


/** Execute one instruction via ITR repeatedly while
 *  passing data to the core via DTR on each execution.
 *
 *  The executed instruction \em must read data from DTR.
 *
 * \pre arm11_run_instr_data_prepare() /  arm11_run_instr_data_finish() block
 *
 * \param arm11         Target state variable.
 * \param opcode        ARM opcode
 * \param data          Pointer to the data words to be passed to the core
 * \param count         Number of data words and instruction repetitions
 *
 */
void arm11_run_instr_data_to_core(arm11_common_t * arm11, u32 opcode, u32 * data, size_t count)
{
    arm11_add_IR(arm11, ARM11_ITRSEL, -1);

    arm11_add_debug_INST(arm11, opcode, NULL, TAP_PD);

    arm11_add_IR(arm11, ARM11_EXTEST, -1);

    scan_field_t        chain5_fields[3];

    u32                 Data;
    u8                  Ready;
    u8                  nRetry;

    arm11_setup_field(arm11, 32,    &Data,  NULL,       chain5_fields + 0);
    arm11_setup_field(arm11,  1,    NULL,   &Ready,     chain5_fields + 1);
    arm11_setup_field(arm11,  1,    NULL,   &nRetry,    chain5_fields + 2);

    while (count--)
    {
        do
        {
            Data            = *data;

            jtag_add_dr_scan_vc(asizeof(chain5_fields), chain5_fields, TAP_RTI);
            jtag_execute_queue();

            JTAG_DEBUG("DTR  Ready %d  nRetry %d", Ready, nRetry);
        }
        while (!Ready);

        data++;
    }

    arm11_add_IR(arm11, ARM11_INTEST, -1);

    do
    {
        Data        = 0;

        jtag_add_dr_scan_vc(asizeof(chain5_fields), chain5_fields, TAP_PD);
        jtag_execute_queue();

        JTAG_DEBUG("DTR  Data %08x  Ready %d  nRetry %d", Data, Ready, nRetry);
    }
    while (!Ready);


}

/** Execute an instruction via ITR while handing data into the core via DTR.
 *
 *  The executed instruction \em must read data from DTR.
 *
 * \pre arm11_run_instr_data_prepare() /  arm11_run_instr_data_finish() block
 *
 * \param arm11         Target state variable.
 * \param opcode        ARM opcode
 * \param data          Data word to be passed to the core via DTR
 *
 */
void arm11_run_instr_data_to_core1(arm11_common_t * arm11, u32 opcode, u32 data)
{
    arm11_run_instr_data_to_core(arm11, opcode, &data, 1);
}


/** Execute one instruction via ITR repeatedly while
 *  reading data from the core via DTR on each execution.
 *
 *  The executed instruction \em must write data to DTR.
 *
 * \pre arm11_run_instr_data_prepare() /  arm11_run_instr_data_finish() block
 *
 * \param arm11         Target state variable.
 * \param opcode        ARM opcode
 * \param data          Pointer to an array that receives the data words from the core
 * \param count         Number of data words and instruction repetitions
 *
 */
void arm11_run_instr_data_from_core(arm11_common_t * arm11, u32 opcode, u32 * data, size_t count)
{
    arm11_add_IR(arm11, ARM11_ITRSEL, -1);

    arm11_add_debug_INST(arm11, opcode, NULL, TAP_RTI);

    arm11_add_IR(arm11, ARM11_INTEST, -1);

    scan_field_t        chain5_fields[3];

    u32                 Data;
    u8                  Ready;
    u8                  nRetry;

    arm11_setup_field(arm11, 32,    NULL,       &Data,      chain5_fields + 0);
    arm11_setup_field(arm11,  1,    NULL,       &Ready,     chain5_fields + 1);
    arm11_setup_field(arm11,  1,    NULL,       &nRetry,    chain5_fields + 2);

    while (count--)
    {
        do
        {
            jtag_add_dr_scan_vc(asizeof(chain5_fields), chain5_fields, count ? TAP_RTI : TAP_PD);
            jtag_execute_queue();

            JTAG_DEBUG("DTR  Data %08x  Ready %d  nRetry %d", Data, Ready, nRetry);
        }
        while (!Ready);

        *data++ = Data;
    }
}

/** Execute one instruction via ITR
 *  then load r0 into DTR and read DTR from core.
 *
 *  The first executed instruction (\p opcode) should write data to r0.
 *
 * \pre arm11_run_instr_data_prepare() /  arm11_run_instr_data_finish() block
 *
 * \param arm11         Target state variable.
 * \param opcode        ARM opcode to write r0 with the value of interest
 * \param data          Pointer to a data word that receives the value from r0 after \p opcode was executed.
 *
 */
void arm11_run_instr_data_from_core_via_r0(arm11_common_t * arm11, u32 opcode, u32 * data)
{
    arm11_run_instr_no_data1(arm11, opcode);

    /* MCR p14,0,R0,c0,c5,0 (move r0 -> wDTR -> local var) */
    arm11_run_instr_data_from_core(arm11, 0xEE000E15, data, 1);
}

/** Load data into core via DTR then move it to r0 then
 *  execute one instruction via ITR
 *
 *  The final executed instruction (\p opcode) should read data from r0.
 *
 * \pre arm11_run_instr_data_prepare() /  arm11_run_instr_data_finish() block
 *
 * \param arm11         Target state variable.
 * \param opcode        ARM opcode to read r0 act upon it
 * \param data          Data word that will be written to r0 before \p opcode is executed
 *
 */
void arm11_run_instr_data_to_core_via_r0(arm11_common_t * arm11, u32 opcode, u32 data)
{
    /* MRC p14,0,r0,c0,c5,0 */
    arm11_run_instr_data_to_core1(arm11, 0xEE100E15, data);

    arm11_run_instr_no_data1(arm11, opcode);
}


void arm11_sc7_run(arm11_common_t * arm11, arm11_sc7_action_t * actions, size_t count)
{
    arm11_add_debug_SCAN_N(arm11, 0x07, -1);

    arm11_add_IR(arm11, ARM11_EXTEST, -1);

    scan_field_t        chain7_fields[3];

    u8          nRW;
    u32         DataOut;
    u8          AddressOut;
    u8          Ready;
    u32         DataIn;
    u8          AddressIn;

    arm11_setup_field(arm11,  1, &nRW,          &Ready,         chain7_fields + 0);
    arm11_setup_field(arm11, 32, &DataOut,      &DataIn,        chain7_fields + 1);
    arm11_setup_field(arm11,  7, &AddressOut,   &AddressIn,     chain7_fields + 2);

    {size_t i;
    for (i = 0; i < count + 1; i++)
    {
        if (i < count)
        {
            nRW         = actions[i].write ? 1 : 0;
            DataOut     = actions[i].value;
            AddressOut  = actions[i].address;
        }
        else
        {
            nRW         = 0;
            DataOut     = 0;
            AddressOut  = 0;
        }

        do
        {
            JTAG_DEBUG("SC7 <= Address %02x  Data %08x    nRW %d", AddressOut, DataOut, nRW);

            jtag_add_dr_scan_vc(asizeof(chain7_fields), chain7_fields, TAP_PD);
            jtag_execute_queue();

            JTAG_DEBUG("SC7 => Address %02x  Data %08x  Ready %d", AddressIn, DataIn, Ready);
        }
        while (!Ready); /* 'nRW' is 'Ready' on read out */

        if (i > 0)
        {
            if (actions[i - 1].address != AddressIn)
            {
                WARNING("Scan chain 7 shifted out unexpected address");
            }

            if (!actions[i - 1].write)
            {
                actions[i - 1].value = DataIn;
            }
            else
            {
                if (actions[i - 1].value != DataIn)
                {
                    WARNING("Scan chain 7 shifted out unexpected data");
                }
            }
        }
    }}

    {size_t i;
    for (i = 0; i < count; i++)
    {
        JTAG_DEBUG("SC7 %02d: %02x %s %08x", i, actions[i].address, actions[i].write ? "<=" : "=>", actions[i].value);
    }}
}

void arm11_sc7_clear_bw(arm11_common_t * arm11)
{
    size_t actions = arm11->brp + arm11->wrp;

    arm11_sc7_action_t          clear_bw[actions];

    {size_t i;
    for (i = 0; i < actions; i++)
    {
        clear_bw[i].write       = true;
        clear_bw[i].value       = 0;
        clear_bw[i].address     =
            i < arm11->brp ?
                ARM11_SC7_BCR0 + i :
                ARM11_SC7_WCR0 + i - arm11->brp;
    }}

    arm11_sc7_run(arm11, clear_bw, actions);
}