Add defaultErrFxn and an err fxn to module state
[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;
37 import ti.sdo.ipc.interfaces.IMessageQTransport;
39 import xdc.rov.ViewInfo;
41 /*!
42  *  ======== TransportCirc ========
43  *  Transport for MessageQ that uses a circular buffer.
44  *
45  *  This is a {@link ti.sdo.ipc.MessageQ} transport that utilizes shared
46  *  memory for passing messages between multiple processors.
47  *
48  *  The transport utilizes shared memory in the manner indicated by the
49  *  following diagram.
50  *
51  *  @p(code)
52  *
53  *  NOTE: Processor '0' corresponds to the M3 and '1' corresponds to the C28
54  *
55  * sharedAddr -> --------------------------- bytes
56  *               |  entry0  (0) [Put]      | msgSize
57  *               |  entry1  (0)            | msgSize
58  *               |  ...                    |
59  *               |  entryN  (0)            | msgSize
60  *               |                         |
61  *               |-------------------------|
62  *               |  putWriteIndex (0)      | 4
63  *               |                         |
64  *               |-------------------------|
65  *               |  getReadIndex (1)       | 4
66  *               |                         |
67  *               |-------------------------|
68  *               |  entry0  (1) [Get]      | msgSize
69  *               |  entry1  (1)            | msgSize
70  *               |  ...                    |
71  *               |  entryN  (1)            | msgSize
72  *               |                         |
73  *               |-------------------------|
74  *               |  putWriteIndex (1)      | 4
75  *               |                         |
76  *               |-------------------------|
77  *               |  getReadIndex (0)       | 4
78  *               |                         |
79  *               |-------------------------|
80  *
81  *
82  *  Legend:
83  *  (0), (1) : belongs to the respective processor
84  *  (N)      : length of buffer
85  *
86  *  @p
87  */
89 @InstanceFinalize
90 @InstanceInitError
92 module TransportCirc inherits IMessageQTransport
93 {
94     /*! @_nodoc */
95     metaonly struct BasicView {
96         String      remoteProcName;
97     }
99     /*! @_nodoc */
100     metaonly struct EventDataView {
101         UInt        index;
102         String      buffer;
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     /*!
215      *  ======== swiPriority ========
216      *  The priority of the Transport Swi object created
217      */
218     config UInt swiPriority = 1;
220 internal:
222     /*! The max index set to (numMsgs - 1) */
223     config UInt maxIndex;
225     /*!
226      *  The message size calculated based on the target.
227      */
228     config UInt msgSize;
230     /*!
231      *  ======== defaultErrFxn ========
232      *  This is the default error function.
233      *
234      *  This function is an empty function that does nothing.
235      *
236      *  @param(reason)  reason for error function
237      *  @param(handle)  handle of transport that had error
238      *  @param(ptr)     pointer to the message
239      *  @param(arg)     argument passed to error function
240      */
241     Void defaultErrFxn(IMessageQTransport.Reason reason,
242                        IMessageQTransport.Handle handle, Ptr ptr, UArg arg);
244     /*!
245      *  ======== swiFxn ========
246      *  This function takes the messages from the transport ListMP and
247      *  calls MessageQ_put to send them to their destination queue.
248      *  This function is posted by the NotifyFxn.
249      *
250      *  @param(arg)     argument for the function
251      */
252     Void swiFxn(UArg arg);
254     /*!
255      *  ======== notifyFxn ========
256      *  This is a callback function registered with Notify.  It is called
257      *  when a remote processor does a Notify_sendEvent().  It is executed
258      *  at ISR level.  It posts the instance Swi object to execute swiFxn.
259      *
260      *  @param(procId)  remote processor id
261      *  @param(lineId)  Notify line id
262      *  @param(eventId) Notify event id
263      *  @param(arg)     argument for the function
264      *  @param(payload) 32-bit payload value.
265      */
266     Void notifyFxn(UInt16 procId, UInt16 lineId, UInt32 eventId, UArg arg,
267                    UInt32 payload);
269     /* Instance State object */
270     struct Instance_State {
271         Ptr             *putBuffer;     /* buffer used to put message       */
272         Bits32          *putReadIndex;  /* ptr to readIndex for put buffer  */
273         Bits32          *putWriteIndex; /* ptr to writeIndex for put buffer */
274         Ptr             *getBuffer;     /* buffer used to get message       */
275         Bits32          *getReadIndex;  /* ptr to readIndex for get buffer  */
276         Bits32          *getWriteIndex; /* ptr to writeIndex for put buffer */
277         Swi.Object      swiObj;         /* Each instance has a swi          */
278         SizeT           allocSize;      /* Shared memory allocated          */
279         UInt16          remoteProcId;   /* dst proc id                      */
280         UInt16          priority;       /* priority to register             */
281     };
283     struct Module_State {
284         ErrFxn errFxn;                  /* error function */
285     };