1    /* --COPYRIGHT--,EPL
     2     *  Copyright (c) 2008 Texas Instruments and others.
     3     *  All rights reserved. This program and the accompanying materials
     4     *  are made available under the terms of the Eclipse Public License v1.0
     5     *  which accompanies this distribution, and is available at
     6     *  http://www.eclipse.org/legal/epl-v10.html
     7     * 
     8     *  Contributors:
     9     *      Texas Instruments - initial implementation
    10     * 
    11     * --/COPYRIGHT--*/
    12    import xdc.runtime.Log;
    13    import xdc.runtime.Diags;
    14    
    15    /*!
    16     *  ======== Stack ========
    17     *  Stack monitoring functions
    18     *
    19     *  This module provides simple stack monitoring operations that enables an
    20     *  application efficiently monitor the system's worst-case stack usage.
    21     *
    22     *  Stack overruns are a common problem in embedded development and they
    23     *  result in intermittent and difficult to reproduce failures.  The ability
    24     *  to quickly determine of unexpected behavious is the result of a stack
    25     *  overrun can save hours of debug time.
    26     */
    27    @ModuleStartup
    28    module Stack
    29    {
    30        /*!
    31         *  ======== Status ========
    32         *  Stack status information buffer
    33         */
    34        struct Status {
    35            Int unused;     /*! number of words never used (so far) */
    36            Int used;       /*! worst-case number of words used (so far) */
    37            Int curDepth;   /*! current number of words on the stack */
    38        }
    39        
    40        /*!
    41         *  ======== UNUSED ========
    42         *  Unused stack space event
    43         */
    44        config Log.Event UNUSED = {
    45            mask: Diags.USER1,
    46            msg: "unused stack space = %d words"
    47        };
    48    
    49        /*!
    50         *  ======== check ========
    51         *  Return non-zero if stack pointer is within allocated stack
    52         *
    53         *  If this function returns 0, the current stack pointer is pointing
    54         *  to a location _outside_ the caller's allocated stack.
    55         */
    56        @DirectCall
    57        Bool check();
    58    
    59        /*!
    60         *  ======== fill ========
    61         *  Fill unused stack with initial value
    62         *
    63         *  This function is called at startup and may be called at runtime
    64         *  to re-initialize the stack.  However, interrupts must be disabled
    65         *  during this process (to prevent corruption of ISR state).
    66         */
    67        Void fill();
    68        
    69        /*!
    70         *  ======== getUnused ========
    71         *  Get number of words of unused stack space
    72         */
    73        Int getUnused();
    74    
    75        /*!
    76         *  ======== getStatus ========
    77         *  Get number of words of unused stack space
    78         */
    79        Void getStatus(Status *stat);
    80    }