Subversion Repositories openrisc

/* jtag.c -- JTAG modeling

   Copyright (C) 2008 Embecosm Limited

   Contributor Jeremy Bennett <jeremy.bennett@embecosm.com>

   This file is part of Or1ksim, the OpenRISC 1000 Architectural Simulator.

   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 3 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, see <http://www.gnu.org/licenses/>.  */

/* This program is commented throughout in a fashion suitable for processing

   with Doxygen. */

/* Autoconf and/or portability configuration */

#include "config.h"

#include "port.h"

/* System includes */

#include <stdlib.h>

#include <unistd.h>

#include <stddef.h>

#include <stdint.h>

#include <string.h>

/* Package includes */

#include "sim-config.h"

#include "sprs.h"

#include "debug-unit.h"

#include "spr-defs.h"

#include "jtag.h"

#include "abstract.h"

#include "toplevel-support.h"

/*---------------------------------------------------------------------------*/

/*!Calculate an ongoing 32-bit CRC for a value

   Utility function. This is for a CRC, where the value is presented in normal

   order (i.e its most significant bit is at the most significant positions,

   it has not been reversed for incorporating ina JTAG register).

   The function can be used for values with more than 64 bits, but will treat

   the supplied value as the most-significant 64 bits, with all other bits

   zero. In practice this is only of use when shifting in a large number of

   zeros.

   The CRC used is the IEEE 802.3 32-bit CRC using the polynomial:

   x^32 + x^26 + x^23 +x^22 +x^16 + x^12 + x^11 + x^10 + x^8 + x^7 + x^5 +

   x^4 + x^2 + x^1 + 1

   In this implementation, the CRC is initialized to all ones (outside this

   function), to catch leading zeros.

   The function is designed to be used in a continuing calculation if

   desired. It takes a partially computed CRC and shifts in the appropriate

   new bits for the value supplied. For a new calculation, this value should

   be 0xffffffff.

  @param[in] value     The number whose CRC is wanted (MSB first)

  @param[in] num_bits  The number of bits to use from value

  @param[in] crc_in    The value of the CRC computed so far

  @return  The updated CRC value                                             */

/*---------------------------------------------------------------------------*/

static uint32_t

crc32 (uint64_t  value,

       int       num_bits,

       uint32_t  crc_in)

{

  static const uint32_t  CRC32_POLY = 0x04c11db7;

  /* Incorporate the bits, MS bit first. */

  int  i;

  for (i = num_bits - 1; i >= 0; i--)

    {

      uint32_t  d = (1 == ((value >> i) & 1))   ? 0xfffffff : 0x0000000;

      uint32_t  t = (1 == ((crc_in >> 31) & 1)) ? 0xfffffff : 0x0000000;

      crc_in <<= 1;

      crc_in  ^= (d ^ t) & CRC32_POLY;

    }

  return  crc_in;

}       /* crc32 () */

/*---------------------------------------------------------------------------*/

/*!Reverse up to 64 bits in a word

   Utility function. Uses the "reverse" algorithm from the University of

   Kentucky Aggregate Magic Algorithms.

   @param[in] val      The long word to reverse

   @param[in] numBits  Number of bits to reverse

   @return  The reversed word.                                               */

/*---------------------------------------------------------------------------*/

static uint64_t

reverse_bits (uint64_t  val,

              int       numBits)

{

  val = (((val & 0xaaaaaaaaaaaaaaaaULL) >>  1) |

         ((val & 0x5555555555555555ULL) <<  1));

  val = (((val & 0xccccccccccccccccULL) >>  2) |

         ((val & 0x3333333333333333ULL) <<  2));

  val = (((val & 0xf0f0f0f0f0f0f0f0ULL) >>  4) |

         ((val & 0x0f0f0f0f0f0f0f0fULL) <<  4));

  val = (((val & 0xff00ff00ff00ff00ULL) >>  8) |

         ((val & 0x00ff00ff00ff00ffULL) <<  8));

  val = (((val & 0xffff0000ffff0000ULL) >> 16) |

         ((val & 0x0000ffff0000ffffULL) << 16));

  val = ((val >> 32) | (val << 32));

  return  val >> (64 - numBits);        /* Only the bits we want */

}       /* reverse_bits () */

/*---------------------------------------------------------------------------*/

/*!Reverse a byte

   Utility function. Uses the "reverse" algorithm from the University of

   Kentucky Aggregate Magic Algorithms.

   @param[in] byte  The byte to reverse

   @return  The reversed byte.                                               */

/*---------------------------------------------------------------------------*/

static uint8_t

reverse_byte (uint8_t  byte)

{

  byte = (((byte & 0xaa) >> 1) | ((byte & 0x55) << 1));

  byte = (((byte & 0xcc) >> 2) | ((byte & 0x33) << 2));

  return ((byte >> 4) | (byte << 4));

}       /* reverse_byte () */

/*---------------------------------------------------------------------------*/

/*!Construct a response register to shift out.

   The generic format is:

          +-------+--------+---------+---------+

          |       |        |         |         |

   TDI -> |  CRC  | Status |  XX..XX |  00..00 | -> TDO

          |       |        |         |         |

          +-------+--------+---------+---------+

              32       4    "ignored"   "zero"

             bits    bits      bits      bits

   Fields are always shifted in MS bit first, so must be reversed. The CRC is

   on the 4 status bits. Only the "zero" bits are zeroed. This allows for

   other fields to be specified in the "ignored" bits region, which are

   guaranteed to be left untouched.

   @param[out] jreg       The buffer for the constructed register

   @param[in]  status     The status bits

   @param[in]  crc_in     CRC computed so far (set to 0xffffffff if none)

   @param[in]  ign_bits   The number of bits to ignore

   @param[in]  zero_bits  The number of bits to zero                         */

/*---------------------------------------------------------------------------*/

static void

construct_response (unsigned char *jreg,

                    uint8_t        status,

                    uint32_t       crc_in,

                    unsigned int   ign_bits,

                    unsigned int   zero_bits)

{

  /* Construct the outgoing CRC */

  uint32_t  crc_out = crc32 (status, 4, crc_in);

  /* Reversed versions of fields ready for insertion */

  uint8_t   status_r  = reverse_bits (status, 4);

  uint32_t  crc_out_r = reverse_bits (crc_out, 32);

  /* Construct the response register */

  unsigned int  zero_bytes = zero_bits / 8;

  unsigned int  zero_off   = zero_bits % 8;

  /* Clear the zero bits */

  if (zero_bytes > 0)

    {

      memset (jreg, 0, zero_bytes);

    }

  jreg[zero_bytes] >>= zero_off;

  jreg[zero_bytes] <<= zero_off;

  /* Determine how much to skip in total */

  unsigned int  skip_bytes = (ign_bits + zero_bits) / 8;

  unsigned int  bit_off    = (ign_bits + zero_bits) % 8;

  /* Simplify by dealing separately with two cases:

     - the bit offset is less than or equal to 4, so the status goes in the

       first free byte, with some CRC.

     - the bit offset is greater than 4 but less than 8, so the status goes in

       the first and second free bytes.

     For completeness we deal with what should be the impossible case of

     bit_off > 7. */

  if (bit_off <= 4)

    {

      /* Note that this works even if bit_off == 4, since there will be no CRC

         remaining to OR into the first byte. */

      jreg[skip_bytes]     |=  ((status_r & 0xf) << bit_off) |

                              ((crc_out_r << (4 + bit_off)) & 0xff);

      jreg[skip_bytes + 1]  =  (crc_out_r >> ( 4 - bit_off)) & 0xff;

      jreg[skip_bytes + 2]  =  (crc_out_r >> (12 - bit_off)) & 0xff;

      jreg[skip_bytes + 3]  =  (crc_out_r >> (20 - bit_off)) & 0xff;

      jreg[skip_bytes + 4]  =  (crc_out_r >> (28 - bit_off)) & 0xff;

    }

  else if (bit_off < 8)

    {

      jreg[skip_bytes]     |=   status_r << bit_off;

      jreg[skip_bytes + 1]  =  (status_r >> (8 - bit_off)) |

                              ((crc_out_r << (bit_off - 4)) & 0xff);

      jreg[skip_bytes + 2]  =  (crc_out_r >> (12 - bit_off)) & 0xff;

      jreg[skip_bytes + 3]  =  (crc_out_r >> (20 - bit_off)) & 0xff;

      jreg[skip_bytes + 4]  =  (crc_out_r >> (28 - bit_off)) & 0xff;

      jreg[skip_bytes + 5]  =  (crc_out_r >> (36 - bit_off)) & 0xff;

    }

  else

    {

      fprintf (stderr, "*** ABORT ***: construct_response: impossible bit "

               "offset: %u.\n", bit_off);

      abort ();

    }

}       /* construct_response () */

/*---------------------------------------------------------------------------*/

/*!Select a module for debug

   Process a module selection register. The format is:

          +---------+-------+--------+---+

          |         |       |        |   |

   TDI -> | Ignored |  CRC  | Module | 1 | -> TDO

          |         |       |   ID   |   |

          +---------+-------+--------+---+

              36        32       4

             bits      bits    bits

   The returned register has the format:

          +-------+--------+---------+

          |       |        |         |

   TDI -> |  CRC  | Status |  00..00 | -> TDO

          |       |        |         |

          +-------+--------+---------+

              32       4        37

             bits    bits      bits

   Fields are always shifted in MS bit first, so must be reversed. The CRC in

   is computed on the first 5 bits, the CRC out on the 4 status bits.

   This is a register of a fixed size, which we verify initially.

   @param[in,out] jreg      The register to shift in, and the register shifted

                            back out.

   @param[in]     num_bits  The number of bits supplied.

   @return  The number of cycles the shift took, which in turn is the number

            of bits in the register                                          */

/*---------------------------------------------------------------------------*/

static void

select_module (unsigned char *jreg,

               int            num_bits)

{

  /* Validate register size, which is fixed */

  const int  REG_BITS = 36 + 32 + 4 + 1;

  if (REG_BITS != num_bits)

    {

      fprintf (stderr,

               "ERROR: JTAG module select %d bits, when %d bits expected.\n",

              num_bits, REG_BITS);

      return;

    }

  /* Break out the fields */

  uint8_t   mod_id = reverse_bits ((jreg[0] >> 1) & 0xf, 4);

  uint32_t  crc_in = reverse_bits (((uint32_t ) (jreg[0] & 0xe0) >>  5) |

                                   ((uint32_t )  jreg[1]         <<  3) |

                                   ((uint32_t )  jreg[2]         << 11) |

                                   ((uint32_t )  jreg[3]         << 19) |

                                   ((uint32_t ) (jreg[4] & 0x1f) << 27), 32);

  /* Compute the expected CRC */

  uint32_t  crc_computed;

  crc_computed = crc32 (1,      1, 0xffffffff);

  crc_computed = crc32 (mod_id, 4, crc_computed);

  /* Status flags */

  enum jtag_status  status = JS_OK;

  /* Validate the CRC */

  if (crc_computed == crc_in)

    {

      /* Is it a valid module? */

      switch (mod_id)

        {

        case JM_WISHBONE:

        case JM_CPU0:

        case JM_CPU1:

          /* All valid. Record the module */

          runtime.debug.mod_id = mod_id;

          break;

        default:

          /* Bad module: record the error. Set the module to JM_UNDEFINED,

             which will trigger more errors in the future, rather than

             leaving the module unchanged, which might allow such errors to

             slip by undetected. */

          status |= JS_MODULE_MISSING;

          runtime.debug.mod_id = JM_UNDEFINED;

          break;

        }

    }

  else

    {

      /* CRC Mismatch: record the error */

      status |= JS_CRC_IN_ERROR;

    }

  /* Construct the outgoing register and return the JTAG cycles taken (the

     register length) */

  return  construct_response (jreg, status, 0xffffffff, 0, 37);

}       /* select_module */

/*---------------------------------------------------------------------------*/

/*!Read WishBone data

   Read memory from WishBone. The WRITE_COMMAND address is updated to reflect

   the completed read if successful.

   The data follows an initial 37 bits corresponding to the incoming command

   and CRC. We use the smaller of the data size in the original WRITE_COMMAND

   and the size of the data in the GO_COMMAND_WRITE packet, so we can handle

   over/under-run.

   The result is the CRC of the data read. The status flag is supplied as a

   pointer, since this can also be updated if there is a problem reading the

   data.

   @note The size of the data is one greater than the length specified in the

         original WRITE_COMMAND.

   @todo For now we always read a byte a time. In the future, we ought to use

         16 and 32-bit accesses for greater efficiency.

   @todo  The algorithm for ensuring we only set the bits of interest in the

          register is inefficient. We should instead clear the whole area

          before starting.

   @param[out] jreg        The JTAG register buffer where data is to be

                           stored.

   @param[in]  jreg_bytes   The number of bytes expected in the JTAG register

                           (may be different to that in the prior READ/WRITE

                           if we have over- or under-run).

   @param[in]  status_ptr  Pointer to the status register.

   @return  The CRC of the data read                                         */

/*---------------------------------------------------------------------------*/

static uint32_t

wishbone_read (unsigned char     *jreg,

               unsigned long int  jreg_bytes,

               enum jtag_status  *status_ptr)

{

  const unsigned int  BIT_OFF  = 37 % 8;        /* Skip initial fields */

  const unsigned int  BYTE_OFF = 37 / 8;

  /* Transfer each byte in turn, computing the CRC as we go. We must supply

     jreg_bytes. If there is overrun, we use zero for the remaining bytes. */

  uint32_t           crc_out  = 0xffffffff;

  unsigned long int  i;

  for (i = 0; i < jreg_bytes; i++)

    {

      unsigned char  byte = 0;

      /* Get a byte if available */

      if (i < runtime.debug.size)

        {

          /* Error if we can't access this byte */

          if (NULL == verify_memoryarea (runtime.debug.addr + i))

            {

              *status_ptr |= JS_WISHBONE_ERROR;

            }

          else

            {

              /* Get the data with no cache or VM translation */

              byte = eval_direct8 (runtime.debug.addr + i, 0, 0);

            }

        }

      /* Update the CRC, reverse, then store the byte in the register, without

         trampling adjacent bits. Simplified version when the bit offset is

         zero. */

      crc_out = crc32 (byte, 8, crc_out);

      byte    = reverse_byte (byte);

      /* Clear the bits (only) we are setting */

      jreg[BYTE_OFF + i]     <<= 8 - BIT_OFF;

      jreg[BYTE_OFF + i]     >>= 8 - BIT_OFF;

      jreg[BYTE_OFF + i + 1] >>= BIT_OFF;

      jreg[BYTE_OFF + i + 1] <<= BIT_OFF;

      /* OR in the bits */

      jreg[BYTE_OFF + i]     |= (byte <<      BIT_OFF)  & 0xff;

      jreg[BYTE_OFF + i + 1] |= (byte >> (8 - BIT_OFF)) & 0xff;

    }

  /* Only advance if there we no errors (including over/under-run. */

  if (JS_OK == *status_ptr)

    {

      runtime.debug.addr += runtime.debug.size;

    }

  return  crc_out;

}       /* wishbone_read () */

/*---------------------------------------------------------------------------*/

/*!Read SPR data

   Read memory from a SPR. The WRITE_COMMAND address is updated to reflect the

   completed read if successful.

   The data follows an initial 37 bits corresponding to the incoming command

   and CRC. We use the smaller of the data size in the original WRITE_COMMAND

   and the size of the data in the GO_COMMAND_WRITE packet, so we can handle

   over/under-run.

   The result is the CRC of the data read.

   Unlike with Wishbone, there is no concept of any errors possible when

   reading an SPR.

   @todo The algorithm for ensuring we only set the bits of interest in the

         register is inefficient. We should instead clear the whole area

         before starting.

   @note The address is treated as a word address of the SPR.

   @note The debug unit is documented as being explicitly Big Endian. However

         that seems to be a poor basis for modeling, and more to do with the

         debug unit only ever being used with big-endian architectures. We

         transfer the bytes in the endianness of the OR1K.

   @param[out] jreg       The JTAG register buffer where data is to be stored.

   @param[in]  jreg_bytes   The number of bytes expected in the JTAG register

                           (may be different to that in the prior READ/WRITE

                           if we have over- or under-run).

   @param[in]  status_ptr  Pointer to the status register.

   @return  The CRC of the data read                                         */

/*---------------------------------------------------------------------------*/

static uint32_t

spr_read (unsigned char     *jreg,

          unsigned long int  jreg_bytes,

          enum jtag_status  *status_ptr)

{

  const unsigned int  BIT_OFF  = 37 % 8;        /* Skip initial fields */

  const unsigned int  BYTE_OFF = 37 / 8;

  /* Store the SPR in the register, without trampling adjacent bits, computing

     the CRC as we go. We have to fill all the JTAG register bytes. If there

     is overrun, we pack in zeros. */

  uint32_t           spr      = mfspr (runtime.debug.addr);

  uint32_t           crc_out  = 0xffffffff;

  unsigned long int  i;

  for (i = 0; i < jreg_bytes; i++)

    {

      unsigned char  byte = 0;

      /* Get the byte from the SPR if available, otherwise use zero */

      if (i < 4)

        {

#ifdef OR32_BIG_ENDIAN

          byte = (spr >> 8 * i) & 0xff;

#else /* !OR32_BIG_ENDIAN */

          byte = (spr >> (24 - (8 * i))) & 0xff;

#endif /* OR32_BIG_ENDIAN */

        }

      /* Update the CRC */

      crc_out = crc32 (byte, 8, crc_out);

      /* Reverse, then store the byte in the register, without trampling

         adjacent bits. */

      byte = reverse_byte (byte);

      /* Clear the bits (only) we are setting */

      jreg[BYTE_OFF + i]     <<= 8 - BIT_OFF;

      jreg[BYTE_OFF + i]     >>= 8 - BIT_OFF;

      jreg[BYTE_OFF + i + 1] >>= BIT_OFF;

      jreg[BYTE_OFF + i + 1] <<= BIT_OFF;

      /* OR in the bits */

      jreg[BYTE_OFF + i]     |= (byte <<      BIT_OFF)  & 0xff;

      jreg[BYTE_OFF + i + 1] |= (byte >> (8 - BIT_OFF)) & 0xff;

    }

  /* Only advance if there we no errors (including over/under-run). */

  if (JS_OK == *status_ptr)

    {

      runtime.debug.addr++;

    }

  return  crc_out;

}       /* spr_read () */

/*---------------------------------------------------------------------------*/

/*!Set up null data.

   When there is an error in GO_COMMAND_READ, the data fields must be

   populated and the CRC set up, to ensure a correct return.

   The data follows an initial 37 bits corresponding to the incoming command

   and CRC. We use the smaller of the data size in the original WRITE_COMMAND

   and the size of the data in the GO_COMMAND_WRITE packet, so we can handle

   over/under-run.

   @param[out] jreg       The JTAG register buffer where data is to be stored.

   @param[in]  jreg_bytes   The number of bytes expected in the JTAG register

                           (may be different to that in the prior READ/WRITE

                           if we have over- or under-run).

   @return  The CRC of the data read                                         */

/*---------------------------------------------------------------------------*/

static uint32_t

null_read (unsigned char     *jreg,

           unsigned long int  jreg_bytes)

{

  const unsigned int  BIT_OFF  = 37 % 8;        /* Skip initial fields */

  const unsigned int  BYTE_OFF = 37 / 8;

  /* Store each null byte in turn, computing the CRC as we go */

  uint32_t           crc_out  = 0xffffffff;

  unsigned long int  i;

  for (i = 0; i < jreg_bytes; i++)

    {

      crc_out = crc32 (0, 8, crc_out);   /* Compute the CRC for null byte */

      /* Store null byte in the register, without trampling adjacent

         bits. */

      jreg[BYTE_OFF + i]     <<= 8 - BIT_OFF;

      jreg[BYTE_OFF + i]     >>= 8 - BIT_OFF;

      jreg[BYTE_OFF + i + 1] >>= BIT_OFF;

      jreg[BYTE_OFF + i + 1] <<= BIT_OFF;

    }

  return  crc_out;

}       /* null_read () */

/*---------------------------------------------------------------------------*/

/*!Carry out a read from WishBone or SPR

   Process a GO_COMMAND register for read. The format is:

          +-------------+-------+---------+---+

          |             |       |    GO   |   |

   TDI -> |   Ignored   |  CRC  | COMMAND | 0 | -> TDO

          |             |       |  (0x0)  |   |

          +-------------+-------+---------+---+

           36 + 8 * size    32       4

               bits        bits    bits

   The returned register has the format:

          +-------+--------+------------+---------+

          |       |        |            |         |

   TDI -> |  CRC  | Status |    Data    |  00..00 | -> TDO

          |       |        |            |         |

          +-------+--------+------------+---------+

              32       4      8 * size       37

             bits    bits       bits        bits

   Fields are always shifted in MS bit first, so must be reversed. The CRC in

   is computed on the first 5 bits, the CRC out on the 4 + 8 * size status and

   data bits.

   @note The size of the data is one greater than the length specified in the

         original WRITE_COMMAND.

   @param[in,out] jreg      The register to shift in, and the register shifted

                            back out.

   @param[in]     num_bits  The number of bits supplied.                     */

/*---------------------------------------------------------------------------*/

static void

go_command_read (unsigned char *jreg,

                 int            num_bits)

{

  /* Check the length is consistent with the prior WRITE_COMMAND. If not we

     have overrun or underrun and flag accordingly. */

  const int          REG_BITS = 36 + 8 * runtime.debug.size + 32 + 4 + 1;

  unsigned long int  jreg_bytes;

  enum jtag_status   status;

  if (REG_BITS == num_bits)

    {

      jreg_bytes = runtime.debug.size;

      status    = JS_OK;

    }

  else

    {

      /* Size will round down for safety */

      jreg_bytes = (runtime.debug.size * 8 + num_bits - REG_BITS) / 8;

      status    = JS_OVER_UNDERRUN;

    }

  /* Break out the fields */

  uint32_t  crc_in   = reverse_bits (((uint32_t) (jreg[0] & 0xe0) >>  5) |

                                     ((uint32_t)  jreg[1]         <<  3) |

                                     ((uint32_t)  jreg[2]         << 11) |

                                     ((uint32_t)  jreg[3]         << 19) |

                                     ((uint32_t) (jreg[4] & 0x1f) << 27), 32);

  /* Compute the expected CRC */

  uint32_t  crc_computed;

  crc_computed = crc32 (0,                1, 0xffffffff);

  crc_computed = crc32 (JCMD_GO_COMMAND,  4, crc_computed);

  /* CRC to go out */

  uint32_t  crc_out = 0;

  /* Validate the CRC */

  if (crc_computed == crc_in)

    {

      /* Read the data. Module errors will have been detected earlier, so we

         do nothing more here. */

      switch (runtime.debug.mod_id)

        {

        case JM_WISHBONE:

          crc_out = wishbone_read (jreg, jreg_bytes, &status);

          break;

        case JM_CPU0:

          crc_out = spr_read (jreg, jreg_bytes, &status);

          break;

        default:

          crc_out = null_read (jreg, jreg_bytes);

          break;

        }

    }

  else

    {

      /* Mismatch: record the error */

      status |= JS_CRC_IN_ERROR;

    }

  /* Construct the outgoing register, skipping the data read and returning the

     number of JTAG cycles taken (the register length). */

  construct_response (jreg, status, crc_out, 8UL * jreg_bytes, 37);

}       /* go_command_read () */

/*---------------------------------------------------------------------------*/

/*!Write WishBone data

   Write memory to WishBone. The WRITE_COMMAND address is updated to reflect

   the completed write if successful.

   The data follows an initial 5 bits specifying the command. We use the

   smaller of the data size in the original WRITE_COMMAND and the size of the

   data in the GO_COMMAND_WRITE packet, so we can handle over/under-run.

   @note The size of the data is one greater than the length specified in the

         original WRITE_COMMAND.

   @todo For now we always write a byte a time. In the future, we ought to use

         16 and 32-bit accesses for greater efficiency and to correctly model

         the use of different access types.

   @param[in]  jreg        The JTAG register buffer where data is found.

   @param[in]  jreg_bytes   The number of bytes expected in the JTAG register

                           (may be different to that in the prior READ/WRITE

                           if we have over- or under-run).