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 * ======== TransportShm.xdc ========
34 */
36 import xdc.runtime.Error;
37 import ti.sdo.ipc.Ipc;
38 import ti.sdo.ipc.GateMP;
39 import ti.sdo.ipc.ListMP;
40 import ti.sdo.ipc.SharedRegion;
41 import ti.sysbios.knl.Swi;
43 /*!
44 * ======== TransportShm ========
45 * Shared-memory MessageQ transport that uses ListMP to queue messages
46 *
47 * Messages sent via TransportShm are temporarily queued in a shared memory
48 * {@link ti.sdo.ipc.ListMP} instance before the messages are moved by the
49 * receiver to the destination queue.
50 */
51 @InstanceFinalize
52 @InstanceInitError
54 module TransportShm inherits ti.sdo.ipc.interfaces.IMessageQTransport
55 {
56 /*! @_nodoc
57 * ======== openByAddr ========
58 * Open a created TransportShm instance by address
59 *
60 * Just like {@link #open}, openByAddr returns a handle to a created
61 * TransportShm instance. This function is used to open a
62 * TransportShm using a shared address instead of a name.
63 * While {@link #open} should generally be used to open transport
64 * instances that have been either locally or remotely created, openByAddr
65 * may be used to bypass a NameServer query that would typically be
66 * required of an {@link #open} call.
67 *
68 * Opening by address requires that the created instance was created
69 * by supplying a {@link #sharedAddr} parameter rather than a
70 * {@link #regionId} parameter.
71 *
72 * A status value of Status_SUCCESS is returned if the instance
73 * is successfully opened. Status_FAIL indicates that the instance
74 * is not yet ready to be opened. Status_ERROR indicates that
75 * an error was raised in the error block.
76 *
77 * Call {@link #close} when the opened instance is no longer needed.
78 *
79 * @param(sharedAddr) Shared address for the instance
80 * @param(handlePtr) Pointer to handle to be opened
81 * @param(eb) Pointer to error block
82 *
83 * @a(returns) TransportShm status
84 */
85 Int openByAddr(Ptr sharedAddr, Handle *handlePtr, Error.Block *eb);
87 /*!
88 * ======== close ========
89 * Close an opened instance
90 *
91 * Closing an instance will free local memory consumed by the opened
92 * instance. Instances that are opened should be closed before the
93 * instance is deleted.
94 *
95 * @param(handle) handle that is returned from an {@link #openByAddr}
96 */
97 Void close(Handle *handle);
99 /*! @_nodoc
100 * ======== sharedMemReq ========
101 * Amount of shared memory required for creation of each instance
102 *
103 * Can be used to make sure the {link #sharedAddr} buffer is large
104 * enough before calling create.
105 *
106 * The {@link #sharedAddr} needs to be
107 * supplied because the cache alignment settings for the region
108 * may affect the total amount of shared memory required.
109 *
110 * @param(params) Pointer to the parameters that will be used in
111 * the create.
112 *
113 * @a(returns) Number of MAUs needed to create the instance.
114 */
115 SizeT sharedMemReq(const Params *params);
117 /*!
118 * ======== notifyEventId ========
119 * Notify event ID for transport.
120 */
121 config UInt16 notifyEventId = 2;
123 instance:
125 /*!
126 * ======== gate ========
127 * GateMP used for critical region management of the shared memory
128 */
129 config GateMP.Handle gate = null;
131 /*! @_nodoc
132 * ======== openFlag ========
133 * Set to 'true' by the open() call. No one else should touch this!
134 */
135 config Bool openFlag = false;
137 /*!
138 * ======== sharedAddr ========
139 * Physical address of the shared memory
140 *
141 * The creator must supply the shared memory that is used to maintain
142 * shared state information.
143 */
144 config Ptr sharedAddr = null;
146 internal:
148 /*!
149 * Constants that all delegate writers need.
150 */
151 const UInt32 UP = 0xBADC0FFE;
153 /*!
154 * ======== swiFxn ========
155 * This function takes the messages from the transport ListMP and
156 * calls MessageQ_put to send them to their destination queue.
157 * This function is posted by the NotifyFxn.
158 *
159 * @param(arg) argument for the function
160 */
161 Void swiFxn(UArg arg);
163 /*!
164 * ======== notifyFxn ========
165 * This is a callback function registered with Notify. It is called
166 * when a remote processor does a Notify_sendEvent(). It is executed
167 * at ISR level. It posts the instance Swi object to execute swiFxn.
168 *
169 * @param(eventId) Notify event id
170 * @param(arg) argument for the function
171 * @param(payload) 32-bit payload value.
172 */
173 Void notifyFxn(UInt16 procId, UInt16 lineId, UInt32 eventId, UArg arg,
174 UInt32 payload);
176 /* Structure of attributes in shared memory */
177 struct Attrs {
178 Bits32 flag;
179 Bits32 creatorProcId;
180 Bits32 notifyEventId;
181 Bits16 priority;
182 SharedRegion.SRPtr gateMPAddr;
183 };
185 /* Instance State object */
186 struct Instance_State {
187 Attrs *self; /* Attrs in shared memory */
188 Attrs *other; /* Only flag field is used */
189 ListMP.Handle localList; /* ListMP to my processor */
190 ListMP.Handle remoteList; /* ListMP to remote processor */
191 Swi.Object swiObj; /* Each instance has a swi */
192 UInt32 status; /* Current status */
193 Ipc.ObjType objType; /* Static/Dynamic? open/creator? */
194 SizeT allocSize; /* Shared memory allocated */
195 Bool cacheEnabled; /* Whether to do cache calls */
196 UInt16 regionId; /* the shared region id */
197 UInt16 remoteProcId; /* dst proc id */
198 UInt16 priority; /* priority to register */
199 GateMP.Handle gate; /* Gate for critical regions */
200 };
202 }