sam-t2/sam/devices/common/regdef/include/Map.h

/*
* ========== Copyright Header Begin ==========================================
*
* OpenSPARC T2 Processor File: Map.h
* Copyright (c) 2006 Sun Microsystems, Inc.  All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES.
*
* The above named program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public
* License version 2 as published by the Free Software Foundation.
*
* The above named 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 work; if not, write to the Free Software
* Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA.
*
* ========== Copyright Header End ============================================
*/
#ifndef __Map_h
#define __Map_h

#include <stdlib.h>
#include <assert.h>
#include <string>
#include "Datatype.h"
using namespace std;

/** @file Map.h
 *  Map.h defines classes for implementing an efficient address map.
 *
 *  @sa Map_Module
 */

/** @defgroup Map_Module The Map Module
 *  The Map module defines classes for implementing an efficient address
 *  map. The map has a very simple interface, though the
 *  implementation is intended to be fast and space-efficient, even for
 *  large sparse maps. The implementation uses template classes so that
 *  the Map class is independent of the datatype of the objects contained
 *  in the address space.
 *
 *  This class is very useful for mapping an address
 *  to a Register. In fact, it is specialized to the case where the
 *  address refers to an 8-byte-aligned, 8-byte-sized piece of memory.
 *  Ideally this restriction should be generalized.
 *
 *  @{
 */

// MAP_TOTAL_BITS is 43 to allow a map to cover whole 43-bit JBUS address

static const uint MAP_LEVEL0_BITS = 10; // most significant bits
static const uint MAP_LEVEL1_BITS = 10;
static const uint MAP_LEVEL2_BITS = 10;
static const uint MAP_LEVEL3_BITS = 10;
static const uint MAP_LEVEL4_BITS = 3;  // least significant bits
static const uint MAP_TOTAL_BITS  = MAP_LEVEL0_BITS + MAP_LEVEL1_BITS +
                                    MAP_LEVEL2_BITS + MAP_LEVEL3_BITS +
                                    MAP_LEVEL4_BITS;

static const uint MAP_WIDTH = 1 << MAP_LEVEL4_BITS;
static const Addr MAP_MIN_ADDR = 0;
static const Addr MAP_MAX_ADDR = (Addr(1) << MAP_TOTAL_BITS) - 1;

/** The MapGeneric class defines the generic interface to a map
 *  class. This allows the user of a map to be independent of the
 *  implementation of the map. The destructor is virtual so that
 *  it can be overloaded. The insert, remove and lookup methods
 *  are virtual and typically overloaded by a sub-class in
 *  order to give a specific Map implementation.
 */

template<class T> class MapGeneric
{
public:
  /** Constructor for MapGeneric.
   *    @param n the name of the map.
   *    @param s the start address of the map.
   *    @param e the end address of the map.
   *    @param w the size in bytes of elements in the map. This must
   *             be an integral power of 2.
   *
   *  A map will be provided for the address range [s, e]. Addresses
   *  outside this range will fail.
   */
  MapGeneric(string n, Addr s, Addr e, uint w);

  /** Destructor for MapGeneric. */
  virtual ~MapGeneric() {}

  /** Insert a mapping from the specified address to the specified item.
   *    @param addr the address to be inserted into the map.
   *    @param item a pointer to the item assoicated with this address.
   *    @return true if the mapping was inserted successfully, otherwise false.
   */
  virtual bool insert(Addr addr, T *item) { return false; }

  /** Remove a mapping from the specified address, and return a pointer
   *  to the associated item (if any).
   *    @param addr the address to be removed from the map.
   *    @return a pointer to the associated object, or NULL if no object at
   *            the specified address.
   */
  virtual T *remove(Addr addr) { return NULL; }

  /** Lookup a mapping at the specified address, and return a pointer
   *  to the associated item (if any).
   *    @param addr the address to be looked up in the map.
   *    @return a pointer to the associated object, or NULL if no object at
   *            the specified address.
   */
  virtual T *lookup(Addr addr) { return NULL; }

protected:
  string name;
  Addr start;
  Addr end;
};

template<class T> struct MapLevel0;    // forward reference

template<class T> class Map : public MapGeneric<T>
{
public:
  /** Constructor for Map.
   *    @param n the name of the map.
   *    @param s the start address of the map.
   *    @param e the end address of the map.
   *    @param w the size in bytes of elements in the map. For this
   *             implementation w must be exactly 8 bytes (the default)
   *             which corresponds to the size of almost all memory-mapped
   *             registers.
   *
   *  A map will be provided for the address range [s, e]. Addresses
   *  outside this range will fail.
   */
  Map(string n, Addr s=MAP_MIN_ADDR, Addr e=MAP_MAX_ADDR, uint w=MAP_WIDTH);

  /** Destructor for Map. */
  ~Map();

  /** Insert a mapping from the specified address to the specified item.
   *    @param addr the address to be inserted into the map.
   *    @param item a pointer to the item assoicated with this address.
   *    @return true if the mapping was inserted successfully, otherwise false.
   */
  bool insert(Addr addr, T *item);

  /** Remove a mapping from the specified address, and return a pointer
   *  to the associated item (if any).
   *    @param addr the address to be removed from the map.
   *    @return a pointer to the associated object, or NULL if no object at
   *            the specified address.
   */
  T *remove(Addr addr);

  /** Lookup a mapping at the specified address, and return a pointer
   *  to the associated item (if any).
   *    @param addr the address to be looked up in the map.
   *    @return a pointer to the associated object, or NULL if no object at
   *            the specified address.
   */
  T *lookup(Addr addr);

private:
  MapLevel0<T> *map;
  uint count_level0;
  uint count_level1;
  uint count_level2;
  uint count_level3;
  uint count_level4;
  uint64 bytes;
};

#include "pMap.h"

#endif