1    /* 
     2     * Copyright (c) 2012, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * */
    32    /*
    33     *  ======== Exception.xdc ========
    34     *
    35     */
    36    
    37    package ti.sysbios.family.c64p;
    38    
    39    import xdc.rov.ViewInfo;
    40    import xdc.runtime.Error;
    41    import xdc.runtime.Diags;
    42    import xdc.runtime.Log;
    43    
    44    /*!
    45     *  ======== Exception ========
    46     *  Exception Module
    47     *
    48     *  The Exception module is a basic C64+ exception handler.  It is generally
    49     *  considered to be a program endpoint, since an exception usually
    50     *  indicates something fatal to the system.
    51     *
    52     *  During initialization, the Exception module sets TSR.GEE and TSR.XEN to
    53     *  enable the CPU to recognize the EXECP input.
    54     *
    55     *  Function hooks are provided to the user for hooking in their own functions
    56     *  at different points of an exception. The hook functions are called in the
    57     *  following order: 
    58     *  (1) exceptionHook - called whenever an exception occurs. 
    59     *  (2) internalHook - called only when an internal exception occurs. 
    60     *  (3) externalHook - called only when an external exception occurs. 
    61     *  (4) nmiHook - called only when a legacy NMI occurs. 
    62     *  (5) returnHook - called whenever an exception occurs. 
    63     *
    64     *  @p(html)
    65     *  <h3> Calling Context </h3>
    66     *  <table border="1" cellpadding="3">
    67     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    68     *
    69     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    70     *    <!--                                                                                                                 -->
    71     *    <tr><td> {@link #clearLastStatus}         </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    72     *    <tr><td> {@link #evtEvtClear}             </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    73     *    <tr><td> {@link #evtExpMaskEnable}        </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    74     *    <tr><td> {@link #getLastStatus}           </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    75     *    <tr><td> {@link #setReturnPtr}            </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    76     *    <tr><td colspan="6"> Definitions: <br />
    77     *       <ul>
    78     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    79     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    80     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    81     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    82     *           <ul>
    83     *             <li> In your module startup after this module is started (e.g. Mod_Module_startupDone() returns TRUE). </li>
    84     *             <li> During xdc.runtime.Startup.lastFxns. </li>
    85     *             <li> During main().</li>
    86     *             <li> During BIOS.startupFxns.</li>
    87     *           </ul>
    88     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
    89     *           <ul>
    90     *             <li> During xdc.runtime.Startup.firstFxns.</li>
    91     *             <li> In your module startup before this module is started (e.g. Mod_Module_startupDone() returns FALSE).</li>
    92     *           </ul>
    93     *       </ul>
    94     *    </td></tr>
    95     *
    96     *  </table>
    97     *  @p
    98     */
    99    
   100    @ModuleStartup         /* generate a call to Exception at startup */
   101    
   102    module Exception
   103    {
   104        /*!
   105         *  ======== rovViewInfo ========
   106         *  @_nodoc
   107         */
   108        @Facet
   109        metaonly config ViewInfo.Instance rovViewInfo =
   110            ViewInfo.create({
   111                viewMap: [
   112                     ['Exception',
   113                        {
   114                            type: ViewInfo.TREE,
   115                            viewInitFxn: 'viewInitException',
   116                            structName: 'Context'
   117                        }
   118                    ]
   119                ]
   120            });
   121            
   122        // -------- Module Types --------
   123    
   124        /*! FuncPtr - Hook function type definition. */
   125        typedef Void (*FuncPtr)(void);
   126    
   127        /*! @_nodoc 
   128         *  Context - Register contents at the time of the exception.
   129         *  dispatch() creates a Context structure on the Hwi ISR stack and
   130         *  fills it before calling handler.  A pointer to this
   131         *  Context structure is returned by getLastStatus().
   132         */
   133        struct Context {
   134            Ptr ILC;        //! register ILC
   135            Ptr RILC;       //! register RILC
   136            Ptr AMR;        //! register AMR
   137            Ptr SSR;        //! register SSR
   138            Ptr IRP;        //! register IRP
   139            Ptr NRP;        //! register NRP
   140            Ptr ITSR;       //! register ITSR
   141            Ptr NTSR;       //! register NTSR
   142            Ptr EFR;        //! register EFR
   143            Ptr IERR;       //! register IERR
   144            Ptr B30;        //! general purpose register b30
   145            Ptr B31;        //! general purpose register b31
   146            Ptr B28;        //! general purpose register b28
   147            Ptr B29;        //! general purpose register b29
   148            Ptr B26;        //! general purpose register b26
   149            Ptr B27;        //! general purpose register b27
   150            Ptr B24;        //! general purpose register b24
   151            Ptr B25;        //! general purpose register b25
   152            Ptr B22;        //! general purpose register b22
   153            Ptr B23;        //! general purpose register b23
   154            Ptr B20;        //! general purpose register b20
   155            Ptr B21;        //! general purpose register b21
   156            Ptr B18;        //! general purpose register b18
   157            Ptr B19;        //! general purpose register b19
   158            Ptr B16;        //! general purpose register b16
   159            Ptr B17;        //! general purpose register b17
   160            Ptr B14;        //! general purpose register b14
   161            Ptr B15;        //! general purpose register b15
   162            Ptr B12;        //! general purpose register b12
   163            Ptr B13;        //! general purpose register b13
   164            Ptr B10;        //! general purpose register b10
   165            Ptr B11;        //! general purpose register b11
   166            Ptr B8;         //! general purpose register b8
   167            Ptr B9;         //! general purpose register b9
   168            Ptr B6;         //! general purpose register b6
   169            Ptr B7;         //! general purpose register b7
   170            Ptr B4;         //! general purpose register b4
   171            Ptr B5;         //! general purpose register b5
   172            Ptr B2;         //! general purpose register b2
   173            Ptr B3;         //! general purpose register b3
   174            Ptr B0;         //! general purpose register b0
   175            Ptr B1;         //! general purpose register b1
   176            Ptr A30;        //! general purpose register a30
   177            Ptr A31;        //! general purpose register a31
   178            Ptr A28;        //! general purpose register a28
   179            Ptr A29;        //! general purpose register a29
   180            Ptr A26;        //! general purpose register a26
   181            Ptr A27;        //! general purpose register a27
   182            Ptr A24;        //! general purpose register a24
   183            Ptr A25;        //! general purpose register a25
   184            Ptr A22;        //! general purpose register a22
   185            Ptr A23;        //! general purpose register a23
   186            Ptr A20;        //! general purpose register a20
   187            Ptr A21;        //! general purpose register a21
   188            Ptr A18;        //! general purpose register a18
   189            Ptr A19;        //! general purpose register a19
   190            Ptr A16;        //! general purpose register a16
   191            Ptr A17;        //! general purpose register a17
   192            Ptr A14;        //! general purpose register a14
   193            Ptr A15;        //! general purpose register a15
   194            Ptr A12;        //! general purpose register a12
   195            Ptr A13;        //! general purpose register a13
   196            Ptr A10;        //! general purpose register a10
   197            Ptr A11;        //! general purpose register a11
   198            Ptr A8;         //! general purpose register a8
   199            Ptr A9;         //! general purpose register a9
   200            Ptr A6;         //! general purpose register a6
   201            Ptr A7;         //! general purpose register a7
   202            Ptr A4;         //! general purpose register a4
   203            Ptr A5;         //! general purpose register a5
   204            Ptr A2;         //! general purpose register a2
   205            Ptr A3;         //! general purpose register a3
   206            Ptr A0;         //! general purpose register a0
   207            Ptr A1;         //! general purpose register a1
   208        };
   209    
   210        /*! Status - structure filled by getLastStatus(). */
   211        struct Status {
   212            Bits32  efr;            //! Exception flag register
   213            Bits32  nrp;            //! NMI return pointer register
   214            Bits32  ntsr;           //! NMI/Exception task state register
   215            Bits32  ierr;           //! Internal Exception report register
   216            Context *excContext;//! Context structure filled by last exception
   217        };
   218    
   219        // -------- Module Constants --------
   220    
   221        /*
   222         *  Bitmasks for C64+ Exception Flag Register (EFR).
   223         */
   224        const Bits32 EFRSXF = 0x00000001;   //! Software exception flag
   225        const Bits32 EFRIXF = 0x00000002;   //! Internal exception flag
   226        const Bits32 EFREXF = 0x40000000;   //! EXCEP flag
   227        const Bits32 EFRNXF = 0x80000000;   //! NMI exception flag
   228    
   229        /*
   230         *  Bitmasks for C64+ Exception Clear Register (ECR).
   231         */
   232        const Bits32 ECRSXF = EFRSXF;       //! Software exception flag
   233        const Bits32 ECRIXF = EFRIXF;       //! Internal exception flag
   234        const Bits32 ECREXF = EFREXF;       //! EXCEP flag
   235        const Bits32 ECRNXF = EFRNXF;       //! NMI exception flag
   236    
   237        /*
   238         *  Bitmasks for C64+ Internal Exception Report Register (IERR).
   239         */
   240        const Bits32 IERRIFX = 0x00000001;  //! Instruction fetch exception
   241        const Bits32 IERRFPX = 0x00000002;  //! Fetch packet exception
   242        const Bits32 IERREPX = 0x00000004;  //! Execute packet exception
   243        const Bits32 IERROPX = 0x00000008;  //! Opcode exception
   244        const Bits32 IERRRCX = 0x00000010;  //! Resource conflict exception
   245        const Bits32 IERRRAX = 0x00000020;  //! Resource access exeption
   246        const Bits32 IERRPRX = 0x00000040;  //! Priviledge exception
   247        const Bits32 IERRLBX = 0x00000080;  //! Loop buffer exception
   248        const Bits32 IERRMSX = 0x00000100;  //! Missed stall exception
   249    
   250        /*
   251         *  Exception-related bitmasks for C64+ Task State Register (TSR).
   252         */
   253        const Bits32 TSRGEE = 0x00000004;   //! Global exception enable
   254        const Bits32 TSRXEN = 0x00000008;   //! External exception enable
   255        const Bits32 TSREXC = 0x00000400;   //! Exception processing
   256        
   257        /* TSR Privilege Mode bits */
   258        const Bits32 TSRCXM   = 0x000000C0; //! Current execution mode bits
   259        const Bits32 TSRCXMSHIFT = 6;       //! TSR.CXM left shift value
   260        const Bits32 TSRCXMSV = 0x00000000; //! Supervisor mode
   261        const Bits32 TSRCXMUS = 0x00000040; //! User mode
   262    
   263        /*! Error raised when {@link #enablePrint Exception.enablePrint} is false */
   264        config Error.Id E_exceptionMin = {
   265            msg: "E_exceptionMin: pc = 0x%08x, sp = 0x%08x.\nTo see more exception detail, use ROV or set 'ti.sysbios.family.c64p.Exception.enablePrint = true;'"
   266        };
   267    
   268        /*! Error raised when {@link #enablePrint Exception.enablePrint} is true */
   269        config Error.Id E_exceptionMax = {
   270            msg: "E_exceptionMax: pc = 0x%08x, sp = 0x%08x."
   271        };
   272    
   273        // -------- Module Parameters --------
   274    
   275        /*!
   276         *  enableExternalMPC - Enable handling of Memory Protection
   277         *  Controller (MPC) exceptions.
   278         */
   279        config Bool enableExternalMPC = false;
   280    
   281        /*!
   282         *  enablePrint - Enable print of exception details and Register values
   283         */
   284        config Bool enablePrint = true;
   285    
   286        /*!
   287         *  exceptionHook - Function hook called by handler
   288         *  This is called anytime an exception occurs.
   289         */
   290        config FuncPtr exceptionHook = null;
   291    
   292        /*!
   293         *  internalHook - Function hook called by internalHandler
   294         *  Function is only called when an internal exception has occurred.
   295         */
   296        config FuncPtr internalHook = null;
   297    
   298        /*!
   299         *  externalHook - Function hook called by externalHandler
   300         *  Function is only called when an external exception has occurred.
   301         */
   302        config FuncPtr externalHook = null;
   303    
   304        /*!
   305         *  nmiHook - Function hook called by nmiHandler
   306         *  Function is called for legacy NMI exceptions only
   307         */
   308        config FuncPtr nmiHook = null;
   309    
   310        /*! returnHook - Function hook called at the end of Exception_dispatch */
   311        config FuncPtr returnHook = null;
   312    
   313        /*!
   314         *  getLastStatus - Fills passed status structure with the Status
   315         *  fields that were recorded by the last invocation of
   316         *  dispatch(), handler() and internalHandler().
   317         *  The 'excContext' is valid only in the scope of sub-handler
   318         *  "Hook" functions, since the Context structure is stored on the
   319         *  Hwi ISR stack.
   320         */
   321        @DirectCall
   322        Void getLastStatus(Status *status);
   323    
   324        /*!
   325         *  clearLastStatus - Clears internal Status structure.
   326         */
   327        @DirectCall
   328        Void clearLastStatus();
   329    
   330        /*!
   331         *  setReturnPtr - Configures dispatch() to "return" (branch) to the
   332         *  passed ptr.
   333         */
   334        @DirectCall
   335        FuncPtr setReturnPtr(FuncPtr ptr);
   336    
   337        /*!
   338         *  evtEvtClear - Clear a C64+ event from the EVTFLAG register.
   339         */
   340        @DirectCall
   341        Void evtEvtClear(UInt event);
   342    
   343        /*!
   344         *  evtExpMaskEnable - Enable a C64+ event to generate an exception.
   345         */
   346        @DirectCall
   347        Void evtExpMaskEnable(UInt event);
   348    
   349        /*! @_nodoc 
   350         *  dispatch - The default low-level dispatcher, plugged into the
   351         *  C64+ NMI vector.
   352         */
   353        @DirectCall
   354        Void dispatch();
   355    
   356    internal:
   357    
   358        /* MPC CPU Access Memory Protecton Fault Event numbers */
   359        const UInt EVTPMCCMPA = 120;        /* PMC memory protection fault event */
   360        const UInt EVTDMCCMPA = 122;        /* DMC memory protection fault event */
   361        const UInt EVTUMCCMPA = 124;        /* UMC memory protection fault event */
   362        const UInt EVTEMCCMPA = 126;        /* EMC memory protection fault event */
   363    
   364        /*!
   365         *  handler - The high-level dispatcher, called by dispatch().
   366         *  Performs the following steps in order:
   367         *    a. records EFR/NRP/NTSR in a Status structure
   368         *    b. logs EFR/NRP/NTSR.CXM with text output to module's logger
   369         *    c. calls exceptionHook
   370         *    d. clears EFR
   371         *    e. calls into subhandlers
   372         *    f. aborts system
   373         */
   374        Void handler(Bool abortFlag);
   375    
   376        /*!
   377         *  internalHandler - Internal exception handler called by
   378         *  handler().  Performs the following steps in order:
   379         *    a. records IERR in a Status structure
   380         *    b. logs IERR with text output to module's logger
   381         *    c. calls internalHook
   382         *    d. clears IERR
   383         */
   384        Void internalHandler();
   385    
   386        /*!
   387         *  externalHandler - External exception handler called by
   388         *  handler().  Performs the following steps in order:
   389         *    a. logs text output to module's logger
   390         *    b. calls externalHook
   391         */
   392        Void externalHandler();
   393    
   394        /*!
   395         *  nmiHandler - Legacy NMI handler called by handler().
   396         *  Performs the following steps in order:
   397         *    a. logs text output to module's logger
   398         *    b. calls nmiHook
   399         */
   400        Void nmiHandler();
   401    
   402        struct Module_State {
   403            Bits32  efr;
   404            Bits32  nrp;
   405            Bits32  ntsr;
   406            Bits32  ierr;
   407            FuncPtr returnHook;
   408            Context *excContext;
   409            Char    scratch[16];    // sratch memory used by dispatch
   410            Char    *isrStack;      // for ROM - Points to isrStack address
   411        };
   412    
   413    }
   414    
   415    /*
   416     *  @(#) ti.sysbios.family.c64p; 2, 0, 0, 0,545; 2-24-2012 11:40:00; /db/vtree/library/trees/avala/avala-q28x/src/ xlibrary
   417    
   418     */
   419