sam-t2/sam/cpus/vonk/ss/lib/cpu/src/SS_Message.h

/*
* ========== Copyright Header Begin ==========================================
*
* OpenSPARC T2 Processor File: SS_Message.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 __SS_Message_h__
#define __SS_Message_h__

#include "SS_Signal.h"
#include "BL_Atomic.h"
#include "SS_SnapShot.h"

// SS_Message is the container class that holds messages for
// a strand that need to be dealth with on the next step.
// The class is the crucial element in the run loop of the
// strand, and part of it's implementation directly impacts
// performance in a big way. The SS_Strand::get_signal is
// the only consumer of this class.

class SS_Message
{
  public:
    SS_Message();

    // is_pending() returns true if one or more messages have been
    // send to the strand. This routines is the key test in the
    // tight runloop of the strand and should not be changed.

    uint64_t is_pending()
    {
      return pending;
    }

    // set_reenter_loop() is used to send a message to the strand
    // that special state such as pstate and hpstate of the strand
    // changed and w\it needs to get out of the loop to update things
    // like global variables held in registers. Currently only
    // SS_Strand::ss_sim_update calls this function.

    void set_reenter_loop()             { flag.reenterloop = 1; }

    // clr_reenter_loop() is used to notify that the reenter loop
    // message is handled.

    void clr_reenter_loop()             { flag.reenterloop = 0; }

    // set_handle_trap() is used to message othe strand that the
    // next step should launch the trap handler. Only SS_Interrupt
    // calls this method as it controls which trap is launched.

    void set_handle_trap( SS_Trap::Type tt )
    {
      assert(tt < SS_Trap::TCC_INSTRUCTION);
      assert(SS_Trap::Type(flag.trap_type) == SS_Trap::RESERVED);
      flag.trap_type = tt;
    }

    // clr_handle_trap() is used to notify that the trap has been
    // handled: the strand is now set to step into the trap code.

    void clr_handle_trap()
    {
      flag.trap_type = SS_Trap::RESERVED;
    }

    // get_handle_trap() is used to find out if a trap is to be
    // handled. A return value SS_Trap:RESERVED means no trap.

    SS_Trap::Type get_handle_trap()
    {
      return SS_Trap::Type(flag.trap_type);
    }

    // test_signal() returns true while there are SS_Signal type
    // messages pending. get_signal() is used to consume those
    // messages.

    bool test_signal()                  { return head->next != 0; }

    // post_signal() is used to send a SS_Signal based message
    // to the strand. The routine is MP safe; it uses a mutex for enqueue.

    void post_signal( SS_Signal* node )
    {
      node->next = 0;
      mutex.lock();
      tail = tail->next = node;
      mutex.unlock();
      bl_atomic_add32((int32_t*)&flag.signal,1);
    }

    // get_signal() is used by the strand to consume a posted SS_Signal
    // message. This routine can only be used when test_signal() returns
    // true. Note each strand has one SS_Message instance so there is
    // only one user of get_signal(), hence dequeue does not have to
    // use MP safe constructs.

    SS_Signal* get_signal()
    {
      // There is always one SS_Signal on an empty queue. On a non empty queue
      // the SS_Signal after the head is the one we are interested in.

      SS_Signal* temp = head;
      SS_Signal* help = temp->next;
      head = help;
      assert(help);
      bl_atomic_add32((int32_t*)&flag.signal,-1);
      temp->next = free_list;
      temp->type = SS_Signal::FREE;
      free_list  = temp;
      ++free_count;
      if (free_count >= free_count_max)
      {
        SS_Signal* h = free_list;
        for (temp = free_list->next;
             free_count > free_count_max/2;
             free_list = temp)
        {
          assert(free_list->type == SS_Signal::FREE);
          assert(free_count > 0);
          --free_count;
          temp = free_list->next;
        }
        SS_Signal* t = free_list;
        free_list = t->next;
        assert(free_count > 0);
        --free_count;
        SS_Signal::list_free(h, t);
      }

      return help;
    }

    // make_signal() creates a new signal that can be posted to a strand.
    // This class maintains it's own pool of signals for MP scalability
    // reasons.

    SS_Signal* make_signal( SS_Signal::Type type )
    {
      SS_Signal* help = free_list;
      if (help == 0)
      {
        assert(free_count == 0);
        return SS_Signal::alloc(type);
      }
      else
      {
        assert(free_count > 0);
        --free_count;
      }
      free_list = help->next;
      help->init(type);
      return help;
    }

    void snapshot( SS_SnapShot& ss, const char* prefix );

  private:
    BL_Mutex mutex;

    // The Flags structure holds all fast but not MP safe flags. These
    // can only be set by the strand itself. The signal flag is used
    // for the MP safe SS_Signal based list.

    struct Flags
    {
      uint8_t  reenterloop;     // Get out of tight loop and reenter
      uint8_t  trap_type;       // Handle (disrupting) trap on th next step
      uint8_t  spare[2];        // Reserved for future fast lock free flags
      int32_t  signal;          // Used to count number SS_Signals pending
    };

    union
    {
      uint64_t pending;         // One 8 byte load to test all the flags
      Flags    flag;            // The flags for fast messages
    };

    // The signal queue always has a valid head and tail pointer.

    SS_Signal* head;            // Head of the message queue
    SS_Signal* tail;            // Tail of the message queue
    SS_Signal* free_list;       // Free list of signals
    uint_t     free_count;      // Nr signals on free list
    static const uint_t free_count_max = 1024;
};

#endif