1    /*
     2     * Copyright (c) 2015-2020, 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.c7x;
    38    
    39    import xdc.runtime.Error;
    40    
    41    /*!
    42     *  ======== Exception ========
    43     *  Exception Module
    44     *
    45     *  The Exception module is a basic C7x exception handler.  It is generally
    46     *  considered to be a program endpoint, since an exception usually
    47     *  indicates something fatal to the system.
    48     *
    49     *  Function hooks are provided to the user for hooking in their own functions
    50     *  at different points of an exception. The hook functions are called in the
    51     *  following order:
    52     *  (1) exceptionHook - called whenever an exception occurs.
    53     *  (2) internalHook - called only when an internal exception or page fault
    54     *      occurs.
    55     *  (5) returnHook - called whenever an exception occurs.
    56     *
    57     *  @p(html)
    58     *  <h3> Calling Context </h3>
    59     *  <table border="1" cellpadding="3">
    60     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    61     *
    62     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    63     *    <!--                                                                                                                 -->
    64     *    <tr><td> {@link #clearLastStatus}         </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    65     *    <tr><td> {@link #getLastStatus}           </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    66     *    <tr><td> {@link #setReturnPtr}            </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    67     *    <tr><td colspan="6"> Definitions: <br />
    68     *       <ul>
    69     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    70     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    71     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    72     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    73     *           <ul>
    74     *             <li> In your module startup after this module is started (e.g. Mod_Module_startupDone() returns TRUE). </li>
    75     *             <li> During xdc.runtime.Startup.lastFxns. </li>
    76     *             <li> During main().</li>
    77     *             <li> During BIOS.startupFxns.</li>
    78     *           </ul>
    79     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
    80     *           <ul>
    81     *             <li> During xdc.runtime.Startup.firstFxns.</li>
    82     *             <li> In your module startup before this module is started (e.g. Mod_Module_startupDone() returns FALSE).</li>
    83     *           </ul>
    84     *       </ul>
    85     *    </td></tr>
    86     *
    87     *  </table>
    88     *  @p
    89     */
    90    
    91    @ModuleStartup         /* generate a call to Exception at startup */
    92    @DirectCall
    93    module Exception
    94    {
    95        // -------- Module Types --------
    96    
    97        /*! FuncPtr - Hook function type definition. */
    98        typedef Void (*FuncPtr)(void);
    99    
   100        /*! @_nodoc
   101         *  Context - Register contents at the time of the exception.
   102         *  dispatch() creates a Context structure on the Hwi ISR stack or
   103         *  context buffer and fills it before calling handler.  A pointer
   104         *  to this Context structure is returned by getLastStatus().
   105         */
   106        struct Context {
   107            Ptr IERR;
   108            Ptr IEAR;
   109            Ptr IESR;
   110            Ptr RP;
   111            Ptr FPCR;
   112            Ptr FSR;
   113            Ptr GFPGFR;
   114            Ptr GPLY;
   115            Ptr P7;
   116            Ptr P6;
   117            Ptr P5;
   118            Ptr P4;
   119            Ptr P3;
   120            Ptr P2;
   121            Ptr P1;
   122            Ptr P0;
   123            Ptr SE0_0[8];
   124            Ptr SE0_1[8];
   125            Ptr SE0_2[8];
   126            Ptr SE0_3[8];
   127            Ptr SE1_0[8];
   128            Ptr SE1_1[8];
   129            Ptr SE1_2[8];
   130            Ptr SE1_3[8];
   131            Ptr SA3CR[8];
   132            Ptr SA2CR[8];
   133            Ptr SA1CR[8];
   134            Ptr SA0CR[8];
   135            Ptr SA3CNTR0[8];
   136            Ptr SA2CNTR0[8];
   137            Ptr SA1CNTR0[8];
   138            Ptr SA0CNTR0[8];
   139            Ptr CUCR3[8];
   140            Ptr CUCR2[8];
   141            Ptr CUCR1[8];
   142            Ptr CUCR0[8];
   143            Ptr VBL7[8];
   144            Ptr VBL6[8];
   145            Ptr VBL5[8];
   146            Ptr VBL4[8];
   147            Ptr VBL3[8];
   148            Ptr VBL2[8];
   149            Ptr VBL1[8];
   150            Ptr VBL0[8];
   151            Ptr VBM7[8];
   152            Ptr VBM6[8];
   153            Ptr VBM5[8];
   154            Ptr VBM4[8];
   155            Ptr VBM3[8];
   156            Ptr VBM2[8];
   157            Ptr VBM1[8];
   158            Ptr VBM0[8];
   159            Ptr VB15[8];
   160            Ptr VB14[8];
   161            Ptr VB13[8];
   162            Ptr VB12[8];
   163            Ptr VB11[8];
   164            Ptr VB10[8];
   165            Ptr VB9[8];
   166            Ptr VB8[8];
   167            Ptr VB7[8];
   168            Ptr VB6[8];
   169            Ptr VB5[8];
   170            Ptr VB4[8];
   171            Ptr VB3[8];
   172            Ptr VB2[8];
   173            Ptr VB1[8];
   174            Ptr VB0[8];
   175            Ptr AL7;
   176            Ptr AL6;
   177            Ptr AL5;
   178            Ptr AL4;
   179            Ptr AL3;
   180            Ptr AL2;
   181            Ptr AL1;
   182            Ptr AL0;
   183            Ptr AM7;
   184            Ptr AM6;
   185            Ptr AM5;
   186            Ptr AM4;
   187            Ptr AM3;
   188            Ptr AM2;
   189            Ptr AM1;
   190            Ptr AM0;
   191            Ptr D15;
   192            Ptr D14;
   193            Ptr D13;
   194            Ptr D12;
   195            Ptr D11;
   196            Ptr D10;
   197            Ptr D9;
   198            Ptr D8;
   199            Ptr D7;
   200            Ptr D6;
   201            Ptr D5;
   202            Ptr D4;
   203            Ptr D3;
   204            Ptr D2;
   205            Ptr D1;
   206            Ptr D0;
   207            Ptr A15;
   208            Ptr A14;
   209            Ptr A13;
   210            Ptr A12;
   211            Ptr A11;
   212            Ptr A10;
   213            Ptr A9;
   214            Ptr A8;
   215            Ptr A7;
   216            Ptr A6;
   217            Ptr A5;
   218            Ptr A4;
   219            Ptr A3;
   220            Ptr A2;
   221            Ptr A1;
   222            Ptr A0;
   223        };
   224    
   225        /*! Status - structure filled by getLastStatus(). */
   226        struct Status {
   227            Bits64  nrp;            //! NMI return pointer register
   228            Bits64  ntsr;           //! NMI/Exception task state register
   229            Bits64  ierr;           //! Internal Exception report register
   230            Bits64  iear;           //! Internal Exception report register
   231            Bits64  iesr;           //! Internal Exception report register
   232            Context *excContext;//! Context structure filled by last exception
   233        };
   234    
   235        // -------- Module Constants --------
   236    
   237        /*
   238         *  Bitmasks for C7x Internal Exception Report Register (IERR).
   239         */
   240        const Bits32 IERRPFX = 0x00000001;  //! Page fault exception
   241        const Bits32 IERRIFX = 0x00000002;  //! Instruction fetch exception
   242        const Bits32 IERRFPX = 0x00000004;  //! Fetch packet exception
   243        const Bits32 IERREPX = 0x00000008;  //! Execute packet exception
   244        const Bits32 IERROPX = 0x00000010;  //! Illegal opcode exception
   245        const Bits32 IERRRCX = 0x00000020;  //! Resource conflict exception
   246        const Bits32 IERRRAX = 0x00000040;  //! Resource access exeption
   247        const Bits32 IERRPRX = 0x00000080;  //! Priviledge exception
   248        const Bits32 IERRLBX = 0x00000100;  //! Loop buffer exception
   249        const Bits32 IERRMSX = 0x00000200;  //! Missed stall exception
   250        const Bits32 IERRDFX = 0x00000400;  //! Data fetch exception
   251        const Bits32 IERRSEX = 0x00000800;  //! Streaming engine exception
   252        const Bits32 IERREXX = 0x00001000;  //! Execution exception
   253        const Bits32 IERRADX = 0x00002000;  //! Address exception
   254        const Bits32 IERRMMX = 0x00004000;  //! MMA exception
   255    
   256        /* size of buffer (in bytes) to hold exception context */
   257        const UInt32 sizeContextBuf = 0x1000;
   258    
   259        /*! Error raised when {@link #enablePrint Exception.enablePrint} is false */
   260        config Error.Id E_exceptionMin = {
   261            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;'"
   262        };
   263    
   264        /*! Error raised when {@link #enablePrint Exception.enablePrint} is true */
   265        config Error.Id E_exceptionMax = {
   266            msg: "E_exceptionMax: pc = 0x%08x, sp = 0x%08x."
   267        };
   268    
   269        // -------- Module Parameters --------
   270    
   271        /*!
   272         *  If true, the exception context is saved to an internal buffer.
   273         *  If false, the exception context is saved to the bottom of the isr stack
   274         *  and no memory for the internal buffer is allocated.
   275         */
   276        config Bool useInternalBuffer = false;
   277    
   278        /*!
   279         *  enablePrint - Enable print of exception details and Register values
   280         */
   281        config Bool enablePrint = true;
   282    
   283        /*!
   284         *  exceptionHook - Function hook called by handler
   285         *  This is called anytime an exception occurs.
   286         */
   287        config FuncPtr exceptionHook = null;
   288    
   289        /*!
   290         *  internalHook - Function hook called by internalHandler
   291         *  Function is only called when an internal exception has occurred.
   292         */
   293        config FuncPtr internalHook = null;
   294    
   295        /*! returnHook - Function hook called at the end of Exception_dispatch */
   296        config FuncPtr returnHook = null;
   297    
   298        /*!
   299         *  getLastStatus - Fills passed status structure with the Status
   300         *  fields that were recorded by the last invocation of
   301         *  dispatch(), handler() and internalHandler().
   302         *  The 'excContext' is valid only in the scope of sub-handler
   303         *  "Hook" functions.
   304         */
   305        Void getLastStatus(Status *status);
   306    
   307        /*!
   308         *  clearLastStatus - Clears internal Status structure.
   309         */
   310        Void clearLastStatus();
   311    
   312        /*!
   313         *  setReturnPtr - Configures dispatch() to "return" (branch) to the
   314         *  passed ptr.
   315         */
   316        FuncPtr setReturnPtr(FuncPtr ptr);
   317    
   318        /*! @_nodoc
   319         *  dispatch - The default low-level dispatcher, plugged into the
   320         *  C7x internal exception vector and page fault vector.
   321         */
   322        Void dispatch();
   323    
   324    internal:
   325    
   326        /*!
   327         *  handler - The high-level dispatcher, called by dispatch().
   328         *  Performs the following steps in order:
   329         *    a. records EFR/NRP/NTSR in a Status structure
   330         *    b. logs EFR/NRP/NTSR.CXM with System_printf()
   331         *    c. calls exceptionHook
   332         *    d. clears EFR
   333         *    e. calls into subhandlers
   334         *    f. aborts system
   335         */
   336        Void handler(Bool abortFlag, Int vectorType);
   337    
   338        /*!
   339         *  internalHandler - Internal exception handler called by
   340         *  handler().  Performs the following steps in order:
   341         *    a. records IERR in a Status structure
   342         *    b. logs IERR with System_printf()
   343         *    c. calls internalHook
   344         *    d. clears IERR
   345         */
   346        Void internalHandler();
   347    
   348        struct Module_State {
   349            Bits64  nrp;
   350            Bits64  ntsr;
   351            Bits64  ierr;
   352            Bits64  iear;
   353            Bits64  iesr;
   354            FuncPtr returnHook;
   355            Context *excContext;
   356            Char    *excPtr;        // points to isrStack or contextBuf
   357            Char    contextBuf[];   // Need at least 74 words for context buf
   358        };
   359    }