1    /*
     2     * Copyright (c) 2015, 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    package ti.sysbios.family.arm.exc;
    37    
    38    import xdc.rov.ViewInfo;
    39    
    40    import xdc.runtime.Error;
    41    
    42    import ti.sysbios.BIOS;
    43    
    44    /*!
    45     *  ======== Exception ========
    46     *  Exception Module
    47     *
    48     *  The Exception module is a basic ARM exception handler.
    49     *  When an exception occurs, the execution state is saved into
    50     *  a buffer with a structure of type {@link #ExcContext ExcContext}.
    51     *
    52     *  By default, a formatted dump of this structure is also sent to
    53     *  the console using System_printf(). This behavior can be suppressed
    54     *  by setting the {@link #enableDecode} config parameter to 'false'.
    55     *
    56     *  An ROV view of the exception context is provided when
    57     *  attached to the target board with CCS.
    58     *
    59     *  @a(Notes)
    60     *  No attempt is made to return from an exception as these are
    61     *  generally fatal in nature.
    62     *
    63     *  When used, the Exception module will override the default
    64     *  exception handlers provided by the current Hwi module.
    65     */
    66    
    67    @ModuleStartup          /* generates call to Exception_Module_startup at startup */
    68    @DirectCall
    69    
    70    module Exception
    71    {
    72        /*! Exception hook function type definition. */
    73        typedef Void (*ExceptionHookFuncPtr)(ExcContext *);
    74    
    75        /* Exception types */
    76        enum Type {
    77            Type_Supervisor = 0x13,         /*! Supervisor (SWI). */
    78            Type_PreAbort   = 0x17,         /*! Abort exception. */
    79            Type_DataAbort  = 0x18,         /*! Abort exception. */
    80            Type_UndefInst  = 0x1b          /*! Undefined instruction exception. */
    81        };
    82    
    83        /*!
    84         *  Exception Context - Register contents at the time of an exception.
    85         */
    86        struct ExcContext {
    87            /* Thread Context */
    88            BIOS.ThreadType threadType; /* Type of thread executing at */
    89                                        /* the time the exception occurred */
    90            Ptr     threadHandle;       /* Handle to thread executing at */
    91                                        /* the time the exception occurred */
    92            Ptr     threadStack;        /* Address of stack contents of thread */
    93                                        /* executing at the time the exception */
    94                                        /* occurred */
    95            SizeT   threadStackSize;    /* size of thread stack */
    96    
    97            Type    type;
    98    
    99            /* Internal Registers */
   100            Ptr     r0;
   101            Ptr     r1;
   102            Ptr     r2;
   103            Ptr     r3;
   104            Ptr     r4;
   105            Ptr     r5;
   106            Ptr     r6;
   107            Ptr     r7;
   108            Ptr     r8;
   109            Ptr     r9;
   110            Ptr     r10;
   111            Ptr     r11;
   112            Ptr     r12;
   113            Ptr     sp;
   114            Ptr     lr;
   115            Ptr     pc;
   116            Ptr     psr;
   117    
   118            /* Fault registers */
   119            Ptr     dfsr;
   120            Ptr     ifsr;
   121            Ptr     dfar;
   122            Ptr     ifar;
   123        }
   124    
   125        /*! @_nodoc */
   126        metaonly struct ModuleView {
   127            String      exception;      /* Summary Exception */
   128        };
   129    
   130        /*!
   131         *  ======== rovViewInfo ========
   132         *  @_nodoc
   133         */
   134        @Facet
   135        metaonly config ViewInfo.Instance rovViewInfo =
   136            ViewInfo.create({
   137                viewMap: [
   138                    ['Basic',
   139                        {
   140                            type: ViewInfo.TREE,
   141                            viewInitFxn: 'viewInitBasic',
   142                            structName: 'ExcContext'
   143                        }
   144                    ],
   145                    ['Module',
   146                        {
   147                            type: ViewInfo.MODULE,
   148                            viewInitFxn: 'viewInitModule',
   149                            structName: 'ModuleView'
   150                        }
   151                    ]
   152                ]
   153            });
   154    
   155        /*! Error raised when a SWI exception occurs */
   156        config Error.Id E_swi = {
   157            msg: "E_swi: pc = 0x%08x, lr = 0x%08x."
   158        };
   159    
   160        /*! Error raised when an prefetch abort exception occurs */
   161        config Error.Id E_prefetchAbort = {
   162            msg: "E_prefetchAbort: pc = 0x%08x, lr = 0x%08x."
   163        };
   164    
   165        /*! Error raised when an data abort exception occurs */
   166        config Error.Id E_dataAbort = {
   167            msg: "E_dataAbort: pc = 0x%08x, lr = 0x%08x."
   168        };
   169    
   170        /*! Error raised when an undefined instruction exception occurs */
   171        config Error.Id E_undefinedInstruction = {
   172            msg: "E_undefinedInstruction: pc = 0x%08x, lr = 0x%08x."
   173        };
   174    
   175        /*!
   176         *  Enable full exception decoding, default is true.
   177         *
   178         *  When enabled, the exception handler will fully
   179         *  decode an exception and dump the registers to the
   180         *  system console.
   181         *
   182         *  When set to false, only an Error is printed on the console.
   183         *
   184         *  In either case, the full exception context is always
   185         *  saved and visible with ROV.
   186         */
   187        config Bool enableDecode = true;
   188    
   189        /*!
   190         *  ======== excStackSize ========
   191         *  Exception stack size in MAUs.
   192         *  Default size is same as Hwi stack size.
   193         *
   194         *  If running in SMP mode, the exception stacks
   195         *  on all cores are set to this size.
   196         */
   197        metaonly config SizeT excStackSize;
   198    
   199        /*!
   200         *  ======== excStackSection ========
   201         *  Memory section used for Exception stack.
   202         *  Default is null, which results in the stack
   203         *  being placed in .bss.
   204         *
   205         *  The exception stacks on all cores are placed
   206         *  in this section.
   207         */
   208        metaonly config String excStackSection = null;
   209    
   210        /*!
   211         *  ======== excContextBuffer ========
   212         *  User Exception Context Buffer Address
   213         *
   214         *  By default, when an exception occurs, an {@link #ExcContext}
   215         *  structure is allocated on the exception stack and filled in
   216         *  by the exception handler.
   217         *
   218         *  If {@link #excContextBuffer} is initialized by the user, the
   219         *  {@link #ExcContext} structure will be placed at that address instead.
   220         *
   221         *  The buffer must be large enough to contain an {@link #ExcContext}
   222         *  structure.
   223         *
   224         *  @a(Note)
   225         *  If running in SMP mode and both excContextBuffer and
   226         *  excContextBuffers[0] are set, then excContextBuffer is used on Core0.
   227         */
   228        metaonly config Ptr excContextBuffer;
   229        metaonly config Ptr excContextBuffers[];
   230    
   231        /*!
   232         *  ======== excStackBuffer ========
   233         *  User Exception Stack Buffer Address
   234         *
   235         *  When an exception occurs, a pointer to the base address
   236         *  of the stack being used by the thread causing the exception is stored
   237         *  in the ExcContext buffer.
   238         *
   239         *  If {@link #excStackBuffer} is initialized by the user, the
   240         *  entire contents of that stack will also be
   241         *  copied to the address specified.
   242         *
   243         *  The buffer must be large enough to contain the largest task stack or ISR
   244         *  stack defined in the application.
   245         *
   246         *  @a(Note)
   247         *  If running in SMP mode and both excStackBuffer and
   248         *  excStackBuffers[0] are set, then excStackBuffer is used on Core0.
   249         */
   250        metaonly config Ptr excStackBuffer;
   251        metaonly config Ptr excStackBuffers[];
   252    
   253        /*!
   254         *  ======== excHookFunc ========
   255         *  User Exception hook function.
   256         *
   257         *  Called just after exception context has been initialized.
   258         *
   259         *  @a(Note)
   260         *  If running in SMP mode and both excHookFunc and excHookFuncs[0]
   261         *  are set, then excHookFunc is used on Core0.
   262         */
   263        config ExceptionHookFuncPtr excHookFunc = null;
   264        config ExceptionHookFuncPtr excHookFuncs[];
   265    
   266        /*!
   267         *  @_nodoc
   268         *  ======== initCoreX ========
   269         *  Assembly code mode registers setup
   270         *
   271         *  Called by core-specific SMP boot function
   272         */
   273        Void initCoreX();
   274    
   275    internal:   /* not for client use */
   276    
   277        /*
   278         *  ======== initCore0 ========
   279         *  Assembly code mode registers setup on Core0
   280         */
   281        Void initCore0();
   282    
   283        /*!
   284         *  ======== excHandlerAsm ========
   285         *  asm code common exception handler
   286         */
   287        Void excHandlerAsm();
   288    
   289        /*!
   290         *  ======== excHandlerDataAsm ========
   291         *  asm code Data Abort exception handler
   292         */
   293        Void excHandlerDataAsm();
   294    
   295        /*!
   296         *  ======== excHandler ========
   297         *  C function exception Handler
   298         */
   299        Void excHandler(UInt *excStack, UInt lr);
   300    
   301        /*!
   302         *  ======== excDumpContext ========
   303         */
   304        Void excDumpContext(UInt pc);
   305    
   306        struct Module_State {
   307            Bool        excActive[];        // TRUE if an exception has occurred
   308            ExcContext  *excContext[];      // Exception context
   309            Ptr         excStackBuffers[];  // where to copy thread's stack
   310            Char        excStack[][];       // buffer used for exception stack
   311            SizeT       excStackSize;
   312        };
   313    }