1    /*
     2     * Copyright (c) 2014, 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     *  ======== IpcMgr.xdc ========
    34     */
    35    
    36    import xdc.runtime.Assert;
    37    import xdc.runtime.Error;
    38    
    39    /*!
    40     *  ======== IpcMgr ========
    41     *  IPC Manager
    42     *
    43     *  This modules is used only for F2837x devices.  Users can statically
    44     *  configure which shared memory segments to enable, the owner processor
    45     *  and the owner's write access.  This module is used for specifying shared
    46     *  memory for IPC between the two C28 processors (CPU1 master and
    47     *  CPU2 slave).
    48     *
    49     *  There are no API's that need to be called.  The necessary drivers for
    50     *  IPC are all created within this module's startup function.  The shared
    51     *  memory is also programmed within this function.  There is handshaking
    52     *  between the processors.  CPU1 releases CPU2 from reset and both processors
    53     *  will synchronize at this point.
    54     *
    55     *  The {@link #readAddr} must point to shared memory which is writeable
    56     *  by the remote core while the {@link #writeAddr} must point to shared
    57     *  memory which is writeable by the local core.  The {@link #readAddr}
    58     *  and {@link #writeAddr} pointers must point to different shared memory
    59     *  blocks.  Memory addresses must be specified in the local core's
    60     *  memory space.
    61     *
    62     *  The {@link #cpu1} configuration parameter specifies whether or not
    63     *  the executable will be run on CPU1 or CPU2.
    64     *
    65     *  For example on CPU1:
    66     *  @p(code)
    67     *  var IpcMgr = xdc.useModule('ti.sdo.ipc.family.f2837x.IpcMgr');
    68     *  IpcMgr.readAddr  = 0x3F800;
    69     *  IpcMgr.writeAddr = 0x3FC00;
    70     *  @p
    71     *
    72     *  On the CPU2:
    73     *  @p(code)
    74     *  var IpcMgr = xdc.useModule('ti.sdo.ipc.family.f2837x.IpcMgr');
    75     *  IpcMgr.readAddr  = 0x3FC00;
    76     *  IpcMgr.writeAddr = 0x3F800;
    77     *  IpcMgr.cpu1 = false;
    78     *  @p
    79     */
    80    
    81    @ModuleStartup
    82    
    83    module IpcMgr
    84    {
    85        /*
    86         *************************************************************************
    87         *                       Generic Errors/Asserts
    88         *************************************************************************
    89         */
    90    
    91        /*!
    92         *  ======== A_internal ========
    93         *  Assert raised when an internal error is encountered
    94         */
    95        config Assert.Id A_internal = {
    96            msg: "A_internal: An internal error has occurred"
    97        };
    98    
    99        /*!
   100         *  ======== A_invParam ========
   101         *  Assert raised when a parameter is invalid
   102         */
   103        config Assert.Id A_invParam  = {
   104            msg: "A_invParam: Invalid configuration parameter supplied"
   105        };
   106    
   107        /*!
   108         *  ======== A_notEnoughMemory ========
   109         *  Assert raised when there's not enough memory for creating instances.
   110         */
   111        config Assert.Id A_notEnoughMemory  = {
   112            msg: "A_notEnoughMemory: There is not enough memory for operation"
   113        };
   114    
   115        /*!
   116         *  ======== A_nullArgument ========
   117         *  Assert raised when a required argument is null
   118         */
   119        config Assert.Id A_nullArgument  = {
   120            msg: "A_nullArgument: Required argument is null"
   121        };
   122    
   123        /*!
   124         *  ======== E_internal ========
   125         *  Error raised when an internal error occured
   126         */
   127        config Error.Id E_internal  = {
   128            msg: "E_internal: An internal error occurred"
   129        };
   130    
   131        /*
   132         *************************************************************************
   133         *                       Module-wide Config Parameters
   134         *************************************************************************
   135         */
   136    
   137        /*!
   138         *  ======== genLinkerSections ========
   139         *  For generating or not generating the linker sections
   140         *
   141         *  By default this is set to 'true' so the following linker sections
   142         *  are generated for the amount of memory used for IPC. For the
   143         *  read address - "ti.sdo.ipc.family.f2837x.IpcMgr.readSect" and for
   144         *  the write address - "ti.sdo.ipc.family.f2837x.IpcMgr.writeSect".
   145         *  To disable generation, set this to 'false'.
   146         */
   147        metaonly config Bool genLinkerSections = true;
   148    
   149        /*!
   150         *  ======== cpu1 ========
   151         *  Set to false if this is CPU2.
   152         */
   153        config Bool cpu1 = true;
   154    
   155        /*!
   156         *  ======== ipcSetFlag ========
   157         *  The IPC set flag that is used for generating the IPC interrupt
   158         *
   159         *  Only a value of 0, 1, 2, or 3 are valid since only those flags
   160         *  have an interrupt associated with them. This value must be the
   161         *  same on both processors.
   162         */
   163        config UInt32 ipcSetFlag = 3;
   164    
   165        /*!
   166         *  ======== messageQSize ========
   167         *  The largest MessageQ size (in bytes) supported by the transport
   168         *
   169         *  This value must be large enough to handle the largest message.
   170         *  The size must be specified in bytes.
   171         */
   172        config UInt32 messageQSize = 128;
   173    
   174        /*!
   175         *  ======== messageQEventId ========
   176         *  Notify event ID for MessageQ transport.
   177         */
   178        config UInt16 messageQEventId = 2;
   179    
   180        /*!
   181         *  ======== nameServerEventId ========
   182         *  Notify event ID for NameServer.
   183         */
   184        config UInt16 nameServerEventId = 4;
   185    
   186        /*!
   187         *  ======== numNotifyMsgs ========
   188         *  The number of messages for the Notify driver's circular buffer
   189         *
   190         *  This is used to determine the size of the put and get buffers.
   191         *  This value must be a power of 2.  A value of 'N' allows 'N-1'
   192         *  outstanding notifications.
   193         */
   194        config UInt32 numNotifyMsgs = 32;
   195    
   196        /*!
   197         *  ======== numMessageQMsgs ========
   198         *  The number of messages for the MessageQ transport's circular buffer
   199         *
   200         *  This is used to determine the size of the put and get buffers.
   201         *  This value must be a power of 2.  A value of 'N' allows 'N-1'
   202         *  outstanding notifications.
   203         */
   204        config UInt32 numMessageQMsgs = 4;
   205    
   206        /*!
   207         *  ======== readAddr ========
   208         *  The base address of read-only shared memory.
   209         *
   210         *  The address must be specified in the local core's memory space.
   211         *  It must point to the same physical address as the writeAddr for
   212         *  the remote processor.
   213         */
   214        config Ptr readAddr;
   215    
   216        /*!
   217         *  ======== writeAddr ========
   218         *  The base address of read/write shared memory.
   219         *
   220         *  The address must be specified in the local core's memory space.
   221         *  It must point to the same physical address as the readAddr for
   222         *  the remote processor.
   223         */
   224        config Ptr writeAddr;
   225    
   226    internal:
   227    
   228        /* the amount of shared memory used */
   229        config UInt32 sharedMemSizeUsed;
   230    
   231        /* function to create NotifyCirc driver instances */
   232        Int notifyCircAttach(UInt16 remoteProcId, Ptr writeAddr, Ptr readAddr);
   233    
   234        /* function to create NameServer remote instances */
   235        Int nameServerAttach(UInt16 remoteProcId, Ptr writeAddr, Ptr readAddr);
   236    
   237        /* function to create MessageQ transport instances */
   238        Int transportCircAttach(UInt16 remoteProcId, Ptr writeAddr, Ptr readAddr);
   239    }