57f02f339e63769f83b5080c580364821a66e6f3
[ipc/ipcdev.git] / packages / ti / sdo / ipc / family / f28m35x / TransportCirc.xdc
1 /*
2  * Copyright (c) 2012-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  *  ======== TransportCirc.xdc ========
34  */
36 import ti.sysbios.knl.Swi;
38 import xdc.rov.ViewInfo;
40 /*!
41  *  ======== TransportCirc ========
42  *  Transport for MessageQ that uses a circular buffer.
43  *
44  *  This is a {@link ti.sdo.ipc.MessageQ} transport that utilizes shared
45  *  memory for passing messages between multiple processors.
46  *
47  *  The transport utilizes shared memory in the manner indicated by the
48  *  following diagram.
49  *
50  *  @p(code)
51  *
52  *  NOTE: Processor '0' corresponds to the M3 and '1' corresponds to the C28
53  *
54  * sharedAddr -> --------------------------- bytes
55  *               |  entry0  (0) [Put]      | 4
56  *               |  entry1  (0)            | 4
57  *               |  ...                    |
58  *               |  entryN  (0)            | 4
59  *               |                         |
60  *               |-------------------------|
61  *               |  putWriteIndex (0)      | 4
62  *               |                         |
63  *               |-------------------------|
64  *               |  getReadIndex (1)       | 4
65  *               |                         |
66  *               |-------------------------|
67  *               |  entry0  (1) [Get]      | 4
68  *               |  entry1  (1)            | 4
69  *               |  ...                    |
70  *               |  entryN  (1)            | 4
71  *               |                         |
72  *               |-------------------------|
73  *               |  putWriteIndex (1)      | 4
74  *               |                         |
75  *               |-------------------------|
76  *               |  getReadIndex (0)       | 4
77  *               |                         |
78  *               |-------------------------|
79  *
80  *
81  *  Legend:
82  *  (0), (1) : belongs to the respective processor
83  *  (N)      : length of buffer
84  *
85  *  @p
86  */
88 @InstanceFinalize
89 @InstanceInitError
91 module TransportCirc inherits ti.sdo.ipc.interfaces.IMessageQTransport
92 {
93     /*! @_nodoc */
94     metaonly struct BasicView {
95         String      remoteProcName;
96     }
98     /*! @_nodoc */
99     metaonly struct EventDataView {
100         UInt        index;
101         String      buffer;
102         Ptr         addr;
103         Ptr         message;
104     }
106     /*!
107      *  ======== rovViewInfo ========
108      */
109     @Facet
110     metaonly config ViewInfo.Instance rovViewInfo =
111         ViewInfo.create({
112             viewMap: [
113                 ['Basic',
114                     {
115                         type: ViewInfo.INSTANCE,
116                         viewInitFxn: 'viewInitBasic',
117                         structName: 'BasicView'
118                     }
119                 ],
120                 ['Events',
121                     {
122                         type: ViewInfo.INSTANCE_DATA,
123                         viewInitFxn: 'viewInitData',
124                         structName: 'EventDataView'
125                     }
126                 ],
127             ]
128         });
130     /*!
131      *  ======== close ========
132      *  Close an opened instance
133      *
134      *  Closing an instance will free local memory consumed by the opened
135      *  instance.  Instances that are opened should be closed before the
136      *  instance is deleted.
137      *
138      *  @param(handle)  handle that is returned from an {@link #openByAddr}
139      */
140     Void close(Handle *handle);
142     /*! @_nodoc
143      *  ======== notifyEventId ========
144      *  Notify event ID for transport.
145      */
146     config UInt16 notifyEventId = 2;
148     /*! @_nodoc
149      *  ======== numMsgs ========
150      *  The maximum number of outstanding messages
151      *
152      *  This number must be greater than 0 and a power of 2.
153      *  If the transport reaches this threshold, it spins waiting for
154      *  another message slot to be freed by the remote processor.
155      */
156     config UInt numMsgs = 4;
158     /*! @_nodoc
159      *  ======== maxMsgSizeInBytes ========
160      *  The maximum message size (in bytes) that is supported
161      */
162     config UInt maxMsgSizeInBytes = 128;
164     /*! @_nodoc
165      *  ======== sharedMemReq ========
166      *  Amount of shared memory required for creation of each instance
167      *
168      *  @param(params)      Pointer to the parameters that will be used in
169      *                      create.
170      *
171      *  @a(returns)         Number of MAUs needed to create the instance.
172      */
173     SizeT sharedMemReq(const Params *params);
175     /*! @_nodoc
176      *  ======== sharedMemReqMeta ========
177      *  Amount of shared memory required for creation of each instance
178      *
179      *  @param(params)      Pointer to the parameters that will be used in
180      *                      create.
181      *
182      *  @a(returns)         Size of shared memory in MAUs on local processor.
183      */
184     metaonly SizeT sharedMemReqMeta(const Params *params);
186 instance:
188     /*! @_nodoc
189      *  ======== openFlag ========
190      *  Set to 'true' by the open() call. No one else should touch this!
191      */
192     config Bool openFlag = false;
194     /*!
195      *  ======== readAddr ========
196      *  Physical address of the read address in shared memory
197      *
198      *  This address should be specified in the local processor's memory
199      *  space.  It must point to the same physical write address of the
200      *  remote processor its communicating with.
201      */
202     config Ptr readAddr = null;
204     /*!
205      *  ======== writeAddr ========
206      *  Physical address of the write address in shared memory
207      *
208      *  This address should be specified in the local processor's memory
209      *  space.  It must point to the same physical read address of the
210      *  remote processor its communicating with.
211      */
212     config Ptr writeAddr = null;
214 internal:
216     /*! The max index set to (numMsgs - 1) */
217     config UInt maxIndex;
219     /*!
220      *  The message size calculated based on the target.
221      */
222     config UInt msgSize;
224     /*!
225      *  ======== swiFxn ========
226      *  This function takes the messages from the transport ListMP and
227      *  calls MessageQ_put to send them to their destination queue.
228      *  This function is posted by the NotifyFxn.
229      *
230      *  @param(arg)     argument for the function
231      */
232     Void swiFxn(UArg arg);
234     /*!
235      *  ======== notifyFxn ========
236      *  This is a callback function registered with Notify.  It is called
237      *  when a remote processor does a Notify_sendEvent().  It is executed
238      *  at ISR level.  It posts the instance Swi object to execute swiFxn.
239      *
240      *  @param(procId)  remote processor id
241      *  @param(lineId)  Notify line id
242      *  @param(eventId) Notify event id
243      *  @param(arg)     argument for the function
244      *  @param(payload) 32-bit payload value.
245      */
246     Void notifyFxn(UInt16 procId, UInt16 lineId, UInt32 eventId, UArg arg,
247                    UInt32 payload);
249     /* Instance State object */
250     struct Instance_State {
251         Ptr             *putBuffer;     /* buffer used to put message       */
252         Bits32          *putReadIndex;  /* ptr to readIndex for put buffer  */
253         Bits32          *putWriteIndex; /* ptr to writeIndex for put buffer */
254         Ptr             *getBuffer;     /* buffer used to get message       */
255         Bits32          *getReadIndex;  /* ptr to readIndex for get buffer  */
256         Bits32          *getWriteIndex; /* ptr to writeIndex for put buffer */
257         Swi.Object      swiObj;         /* Each instance has a swi          */
258         SizeT           allocSize;      /* Shared memory allocated          */
259         UInt16          remoteProcId;   /* dst proc id                      */
260         UInt16          priority;       /* priority to register             */
261     };