1    /*
     2     * Copyright (c) 2013, 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     *  ======== MultithreadSupport.xdc ========
    34     */
    35    
    36    package ti.sysbios.rts.iar;
    37    
    38    import xdc.runtime.Error;
    39    import xdc.runtime.Assert;
    40    
    41    import ti.sysbios.knl.Task;
    42    
    43    /*!
    44     *  ======== MultithreadSupport ========
    45     *  This Multithread support module uses Hook Functions, Hook Context
    46     *  and an overloaded implementation of the library's lock and thread
    47     *  local storage access functions to make C runtime library calls re-entrant.
    48     *
    49     *  Multithread support will be enabled when IAR linker option "--threaded_lib"
    50     *  is passed as the target's linker options prefix. This can be done in one
    51     *  of the following ways:
    52     *     - When building an application in IAR Embedded Workbench, under
    53     *       Project -> Options -> General Options -> Library Configuration,
    54     *       check the "Enable thread support in Library" box.
    55     *     - When building an application through makefile using configuro, pass
    56     *       the linker options on configuro command line using "--linkOptions"
    57     *       option.
    58     *     - When building an application through XDC build system using config.bld,
    59     *       pass the linker options through the XDC target linkOpts.prefix in
    60     *       config.bld.
    61     *
    62     *  Note: Calling C runtime functions from SWI and HWI threads
    63     *        is not supported and will generate an exception if
    64     *        multithread support is enabled.
    65     *
    66     */
    67    
    68    module MultithreadSupport
    69    {
    70        /*!
    71         *  ======== enableMultithreadSupport ========
    72         *  Enable/Disable multithread support
    73         *
    74         *  @_nodoc
    75         */
    76        config Bool enableMultithreadSupport = false;
    77    
    78        /*!
    79         *  ======== A_badThreadType ========
    80         *  Asserted in MultithreadSupport_perThreadAccess()
    81         *
    82         *  @_nodoc
    83         */
    84        config Assert.Id A_badThreadType = {
    85            msg: "A_badThreadType: Cannot call a C runtime library API from a Hwi or Swi thread."
    86        };
    87    
    88        /*!
    89         *  ======== A_badLockRelease ========
    90         *  Asserted in MultithreadSupport_releaseLock()
    91         *
    92         *  @_nodoc
    93         */
    94        config Assert.Id A_badLockRelease = {
    95            msg: "A_badLockRelease: Trying to release a lock not owned by this thread."
    96        };
    97    
    98    internal:   /* not for client use */
    99    
   100        /*!
   101         *  ======== perThreadAccess ========
   102         *  Returns a pointer the symbol in the current task's TLS memory
   103         *
   104         *  Calculates the symbol address based on the input symbol pointer
   105         *  in main task's TLS memory and returns the address to the symbol
   106         *  in the current task's TLS memory.
   107         *
   108         *  @param(symbp) Pointer to symbol in the main task's TLS memory.
   109         *
   110         */
   111        Void *perThreadAccess(Void *symbp);
   112    
   113        /*!
   114         *  ======== initLock ========
   115         *  Initializes a system lock
   116         *
   117         *  Creates a system lock and assigns it to the pointer passed as input.
   118         *
   119         *  @param(ptr) Pointer to a lock struct pointer.
   120         *
   121         */
   122        Void initLock(Void **ptr);
   123    
   124        /*!
   125         *  ======== destroyLock ========
   126         *  Destroy a system lock
   127         *
   128         *  Deletes the semaphore in the lock and frees the lock.
   129         *
   130         *  @param(ptr) Pointer to a lock struct pointer.
   131         *
   132         */
   133        Void destroyLock(Void **ptr);
   134    
   135        /*!
   136         *  ======== acquireLock ========
   137         *  Acquire a system lock
   138         *
   139         *  Blocks the task if lock is not available. Supports nested calls.
   140         *
   141         *  @param(ptr) Pointer to a lock struct pointer.
   142         *
   143         */
   144        Void acquireLock(Void **ptr);
   145    
   146        /*!
   147         *  ======== releaseLock ========
   148         *  Release a system lock
   149         *
   150         *  Releases the lock to other waiting task if any. Supports nested calls.
   151         *
   152         *  @param(ptr) Pointer to a lock struct pointer.
   153         *
   154         */
   155        Void releaseLock(Void **ptr);
   156    
   157        /*!
   158         *  ======== taskCreateHook ========
   159         *  Create task hook function
   160         *
   161         *  It is used to create and initialize all task's hook context.
   162         *
   163         *  @param(task) Handle of the Task to initialize.
   164         *  @param(eb) Error block.
   165         *
   166         */
   167        Void taskCreateHook(Task.Handle task, Error.Block *eb);
   168    
   169        /*!
   170         *  ======== taskDeleteHook ========
   171         *  Delete hook function used to remove the task's hook context.
   172         *
   173         *  @param(task) Handle of the Task to delete.
   174         *
   175         */
   176        Void taskDeleteHook(Task.Handle task);
   177    
   178        /*!
   179         *  ======== taskRegHook ========
   180         *  Registration function for the module's hook
   181         *
   182         *  @param(id) The id of the hook for use in load.
   183         *
   184         */
   185        Void taskRegHook(Int id);
   186    
   187        /* -------- Internal Module Types -------- */
   188    
   189        struct Module_State {
   190            Int taskHId;             /* Task Hook Context Id for this module */
   191        };
   192    }