Shutdown interrupt sources

RTC: 39878

Change-Id: I0c37a0dce8b818cf4a7b6fefe982b838dafcf917
Reviewed-on: http://gfw160.austin.ibm.com:8080/gerrit/1074
Tested-by: Jenkins Server
Reviewed-by: Daniel M. Crowell <dcrowell@us.ibm.com>
Reviewed-by: A. Patrick Williams III <iawillia@us.ibm.com>

1 files changed, 35 insertions, 6 deletions

diff --git a/src/include/usr/intr/interrupt.H b/src/include/usr/intr/interrupt.H
index 5d0633051..f87a5cb5d 100644
--- a/src/include/usr/intr/interrupt.H
+++ b/src/include/usr/intr/interrupt.H
@@ -33,13 +33,25 @@ namespace INTR
 
     /**
      * External Interrupt Types (XISR)
+     * This value is passed in message data[0] on interrupt or shutdown.
+     * @note The XISR is 24 bits:
+     * XISR[ 0: 4] NOT DEFINED
+     * XISR[ 5: 7] Node id
+     * XISR[ 8:10] chipId within Node 
+     * XISR[11:12] Unit selection [GX='00', PHB0='01', PHB1='10', PHB2='11']
+     * XISR[13:19] BUID
+     * XISR[20:23] level
+     *
+     * extr_intr_t values are XISR right shifted, lsb = bit 23
      */
     enum ext_intr_t
     {
         NO_INTERRUPT = 0,       //!< no interrupt present
-        INTERPROC = 2,          //!< Inter processor interrupt
+        INTERPROC = 2,          //!< Inter processor interrupt (should be changed?)
         FSP_MAILBOX = 0x1A,     //!< TODO final value??
         ATTENTION = 0x26,       //!< TODO find this value
+        MAX_XISR  = 0x00FFFFFF, //!< Max value of the XISR
+        SHUT_DOWN = 0x01000000, //!< INTR presenter sends this when shutting down
     };
 
     /**
@@ -57,12 +69,29 @@ namespace INTR
 
 
     /**
-     * Register a message queue to recieve external interrupts
-     * @param[in] i_msgQ  The message queue
-     * @param[in] i_type  The type of interrupt (XISR value)
-     * @return errlHndl_t on error.
+     * Register a message queue for an interrupt type
+     * @param[in] i_msgQ The message queue
+     * @param[in] i_msg_type, The message type of the message to send
+     *                        to i_msgQ when an interrupt of
+     *                        i_intr_type occurrs.
+     * @param[in] i_intr_type, The interrupt type to register.
+     *
+     * @note the interrupt type is currently the XISR value in the XIRR
+     *       register and consists of the chipid, buid, and level
+     *       @see  i_intr_type for enumerations.
+     *
+     * @note when an interrupt of type i_msg_type occurrs, the
+     * interrupt presenter sends a sync message with type i_msg_type to
+     * i_msgQ with i_intr_type in message data word 0 and then waits
+     * for a response.
+     *
+     * @note When HB is shutting down the interrupt presenter will send
+     * a message to all registered queues with a sync message type of
+     * i_msg_type, and data[0] = INTR::SHUT_DOWN.  A response is expected.
      */
-    errlHndl_t registerMsgQ(msg_q_t i_msgQ, ext_intr_t i_type);
+    errlHndl_t registerMsgQ(msg_q_t i_msgQ,
+                            uint32_t i_msg_type,
+                            ext_intr_t i_intr_type);
 
     /**
      * Un register a message queue from the interrupt handler