5285a12c11e7fa1b28d773c5e7ec1b269169b6f9
[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]      | msgSize
56  *               |  entry1  (0)            | msgSize
57  *               |  ...                    |
58  *               |  entryN  (0)            | msgSize
59  *               |                         |
60  *               |-------------------------|
61  *               |  putWriteIndex (0)      | 4
62  *               |                         |
63  *               |-------------------------|
64  *               |  getReadIndex (1)       | 4
65  *               |                         |
66  *               |-------------------------|
67  *               |  entry0  (1) [Get]      | msgSize
68  *               |  entry1  (1)            | msgSize
69  *               |  ...                    |
70  *               |  entryN  (1)            | msgSize
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         message;
103     }
105     /*!
106      *  ======== rovViewInfo ========
107      */
108     @Facet
109     metaonly config ViewInfo.Instance rovViewInfo =
110         ViewInfo.create({
111             viewMap: [
112                 ['Basic',
113                     {
114                         type: ViewInfo.INSTANCE,
115                         viewInitFxn: 'viewInitBasic',
116                         structName: 'BasicView'
117                     }
118                 ],
119                 ['Events',
120                     {
121                         type: ViewInfo.INSTANCE_DATA,
122                         viewInitFxn: 'viewInitData',
123                         structName: 'EventDataView'
124                     }
125                 ],
126             ]
127         });
129     /*!
130      *  ======== close ========
131      *  Close an opened instance
132      *
133      *  Closing an instance will free local memory consumed by the opened
134      *  instance.  Instances that are opened should be closed before the
135      *  instance is deleted.
136      *
137      *  @param(handle)  handle that is returned from an {@link #openByAddr}
138      */
139     Void close(Handle *handle);
141     /*! @_nodoc
142      *  ======== notifyEventId ========
143      *  Notify event ID for transport.
144      */
145     config UInt16 notifyEventId = 2;
147     /*! @_nodoc
148      *  ======== numMsgs ========
149      *  The maximum number of outstanding messages
150      *
151      *  This number must be greater than 0 and a power of 2.
152      *  If the transport reaches this threshold, it spins waiting for
153      *  another message slot to be freed by the remote processor.
154      */
155     config UInt numMsgs = 4;
157     /*! @_nodoc
158      *  ======== maxMsgSizeInBytes ========
159      *  The maximum message size (in bytes) that is supported
160      */
161     config UInt maxMsgSizeInBytes = 128;
163     /*! @_nodoc
164      *  ======== sharedMemReq ========
165      *  Amount of shared memory required for creation of each instance
166      *
167      *  @param(params)      Pointer to the parameters that will be used in
168      *                      create.
169      *
170      *  @a(returns)         Number of MAUs needed to create the instance.
171      */
172     SizeT sharedMemReq(const Params *params);
174     /*! @_nodoc
175      *  ======== sharedMemReqMeta ========
176      *  Amount of shared memory required for creation of each instance
177      *
178      *  @param(params)      Pointer to the parameters that will be used in
179      *                      create.
180      *
181      *  @a(returns)         Size of shared memory in MAUs on local processor.
182      */
183     metaonly SizeT sharedMemReqMeta(const Params *params);
185 instance:
187     /*! @_nodoc
188      *  ======== openFlag ========
189      *  Set to 'true' by the open() call. No one else should touch this!
190      */
191     config Bool openFlag = false;
193     /*!
194      *  ======== readAddr ========
195      *  Physical address of the read address in shared memory
196      *
197      *  This address should be specified in the local processor's memory
198      *  space.  It must point to the same physical write address of the
199      *  remote processor its communicating with.
200      */
201     config Ptr readAddr = null;
203     /*!
204      *  ======== writeAddr ========
205      *  Physical address of the write address in shared memory
206      *
207      *  This address should be specified in the local processor's memory
208      *  space.  It must point to the same physical read address of the
209      *  remote processor its communicating with.
210      */
211     config Ptr writeAddr = null;
213     /*!
214      *  ======== swiPriority ========
215      *  The priority of the Transport Swi object created
216      */
217     config UInt swiPriority = 1;
219 internal:
221     /*! The max index set to (numMsgs - 1) */
222     config UInt maxIndex;
224     /*!
225      *  The message size calculated based on the target.
226      */
227     config UInt msgSize;
229     /*!
230      *  ======== swiFxn ========
231      *  This function takes the messages from the transport ListMP and
232      *  calls MessageQ_put to send them to their destination queue.
233      *  This function is posted by the NotifyFxn.
234      *
235      *  @param(arg)     argument for the function
236      */
237     Void swiFxn(UArg arg);
239     /*!
240      *  ======== notifyFxn ========
241      *  This is a callback function registered with Notify.  It is called
242      *  when a remote processor does a Notify_sendEvent().  It is executed
243      *  at ISR level.  It posts the instance Swi object to execute swiFxn.
244      *
245      *  @param(procId)  remote processor id
246      *  @param(lineId)  Notify line id
247      *  @param(eventId) Notify event id
248      *  @param(arg)     argument for the function
249      *  @param(payload) 32-bit payload value.
250      */
251     Void notifyFxn(UInt16 procId, UInt16 lineId, UInt32 eventId, UArg arg,
252                    UInt32 payload);
254     /* Instance State object */
255     struct Instance_State {
256         Ptr             *putBuffer;     /* buffer used to put message       */
257         Bits32          *putReadIndex;  /* ptr to readIndex for put buffer  */
258         Bits32          *putWriteIndex; /* ptr to writeIndex for put buffer */
259         Ptr             *getBuffer;     /* buffer used to get message       */
260         Bits32          *getReadIndex;  /* ptr to readIndex for get buffer  */
261         Bits32          *getWriteIndex; /* ptr to writeIndex for put buffer */
262         Swi.Object      swiObj;         /* Each instance has a swi          */
263         SizeT           allocSize;      /* Shared memory allocated          */
264         UInt16          remoteProcId;   /* dst proc id                      */
265         UInt16          priority;       /* priority to register             */
266     };