[processor-sdk/performance-audio-sr.git] / processor_audio_sdk_1_00_00_00 / psdk_cust / ipc_3_43_00_00_eng / docs / cdoc / ti / sdo / ipc / transports / TransportShm-src.html
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2 <html><head><title>module ti.sdo.ipc.transports.TransportShm</title>
3 <meta name="googlebot" content="noindex,nofollow">
4 <link rel="stylesheet" type="text/css" href="../../../../src.css"/>
5 </head>
6 <body>
7 <pre class=src>
8 1 <span class="comment">/*
9 </span> 2 <span class="comment"> * Copyright (c) 2012-2013, Texas Instruments Incorporated
10 </span> 3 <span class="comment"> * All rights reserved.
11 </span> 4 <span class="comment"> *
12 </span> 5 <span class="comment"> * Redistribution and use in source and binary forms, with or without
13 </span> 6 <span class="comment"> * modification, are permitted provided that the following conditions
14 </span> 7 <span class="comment"> * are met:
15 </span> 8 <span class="comment"> *
16 </span> 9 <span class="comment"> * * Redistributions of source code must retain the above copyright
17 </span> 10 <span class="comment"> * notice, this list of conditions and the following disclaimer.
18 </span> 11 <span class="comment"> *
19 </span> 12 <span class="comment"> * * Redistributions in binary form must reproduce the above copyright
20 </span> 13 <span class="comment"> * notice, this list of conditions and the following disclaimer in the
21 </span> 14 <span class="comment"> * documentation and/or other materials provided with the distribution.
22 </span> 15 <span class="comment"> *
23 </span> 16 <span class="comment"> * * Neither the name of Texas Instruments Incorporated nor the names of
24 </span> 17 <span class="comment"> * its contributors may be used to endorse or promote products derived
25 </span> 18 <span class="comment"> * from this software without specific prior written permission.
26 </span> 19 <span class="comment"> *
27 </span> 20 <span class="comment"> * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
28 </span> 21 <span class="comment"> * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
29 </span> 22 <span class="comment"> * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
30 </span> 23 <span class="comment"> * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
31 </span> 24 <span class="comment"> * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
32 </span> 25 <span class="comment"> * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
33 </span> 26 <span class="comment"> * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
34 </span> 27 <span class="comment"> * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
35 </span> 28 <span class="comment"> * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
36 </span> 29 <span class="comment"> * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
37 </span> 30 <span class="comment"> * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
38 </span> 31 <span class="comment"> */</span>
39 32 <span class="comment">/*
40 </span> 33 <span class="comment"> * ======== TransportShm.xdc ========
41 </span> 34 <span class="comment"> */</span>
42 35
43 36 import xdc.runtime.Error;
44 37 import ti.sdo.ipc.Ipc;
45 38 import ti.sdo.ipc.GateMP;
46 39 import ti.sdo.ipc.ListMP;
47 40 import ti.sdo.ipc.SharedRegion;
48 41 import ti.sysbios.knl.Swi;
49 42
50 43 <span class="xdoc">/*!
51 </span> 44 <span class="xdoc"> * ======== TransportShm ========
52 </span> 45 <span class="xdoc"> * Shared-memory MessageQ transport that uses ListMP to queue messages
53 </span> 46 <span class="xdoc"> *
54 </span> 47 <span class="xdoc"> * Messages sent via TransportShm are temporarily queued in a shared memory
55 </span> 48 <span class="xdoc"> * {<b>@link</b> ti.sdo.ipc.ListMP} instance before the messages are moved by the
56 </span> 49 <span class="xdoc"> * receiver to the destination queue.
57 </span> 50 <span class="xdoc"> */</span>
58 51 @InstanceFinalize
59 52 @InstanceInitError
60 53
61 54 <span class=key>module</span> TransportShm <span class=key>inherits</span> ti.sdo.ipc.interfaces.IMessageQTransport
62 55 {
63 56 <span class="xdoc">/*! <b>@_nodoc</b>
64 </span> 57 <span class="xdoc"> * ======== openByAddr ========
65 </span> 58 <span class="xdoc"> * Open a created TransportShm instance by address
66 </span> 59 <span class="xdoc"> *
67 </span> 60 <span class="xdoc"> * Just like {<b>@link</b> #open}, openByAddr returns a handle to a created
68 </span> 61 <span class="xdoc"> * TransportShm instance. This function is used to open a
69 </span> 62 <span class="xdoc"> * TransportShm using a shared address instead of a name.
70 </span> 63 <span class="xdoc"> * While {<b>@link</b> #open} should generally be used to open transport
71 </span> 64 <span class="xdoc"> * instances that have been either locally or remotely created, openByAddr
72 </span> 65 <span class="xdoc"> * may be used to bypass a NameServer query that would typically be
73 </span> 66 <span class="xdoc"> * required of an {<b>@link</b> #open} call.
74 </span> 67 <span class="xdoc"> *
75 </span> 68 <span class="xdoc"> * Opening by address requires that the created instance was created
76 </span> 69 <span class="xdoc"> * by supplying a {<b>@link</b> #sharedAddr} parameter rather than a
77 </span> 70 <span class="xdoc"> * {<b>@link</b> #regionId} parameter.
78 </span> 71 <span class="xdoc"> *
79 </span> 72 <span class="xdoc"> * A status value of Status_SUCCESS is returned if the instance
80 </span> 73 <span class="xdoc"> * is successfully opened. Status_FAIL indicates that the instance
81 </span> 74 <span class="xdoc"> * is not yet ready to be opened. Status_ERROR indicates that
82 </span> 75 <span class="xdoc"> * an error was raised in the error block.
83 </span> 76 <span class="xdoc"> *
84 </span> 77 <span class="xdoc"> * Call {<b>@link</b> #close} when the opened instance is no longer needed.
85 </span> 78 <span class="xdoc"> *
86 </span> 79 <span class="xdoc"> * <b>@param(sharedAddr)</b> Shared address for the instance
87 </span> 80 <span class="xdoc"> * <b>@param(handlePtr)</b> Pointer to handle to be opened
88 </span> 81 <span class="xdoc"> * <b>@param(eb)</b> Pointer to error block
89 </span> 82 <span class="xdoc"> *
90 </span> 83 <span class="xdoc"> * <b>@a(returns)</b> TransportShm status
91 </span> 84 <span class="xdoc"> */</span>
92 85 Int openByAddr(Ptr sharedAddr, Handle *handlePtr, Error.Block *eb);
93 86
94 87 <span class="xdoc">/*!
95 </span> 88 <span class="xdoc"> * ======== close ========
96 </span> 89 <span class="xdoc"> * Close an opened instance
97 </span> 90 <span class="xdoc"> *
98 </span> 91 <span class="xdoc"> * Closing an instance will free local memory consumed by the opened
99 </span> 92 <span class="xdoc"> * instance. Instances that are opened should be closed before the
100 </span> 93 <span class="xdoc"> * instance is deleted.
101 </span> 94 <span class="xdoc"> *
102 </span> 95 <span class="xdoc"> * <b>@param(handle)</b> handle that is returned from an {<b>@link</b> #openByAddr}
103 </span> 96 <span class="xdoc"> */</span>
104 97 Void close(Handle *handle);
105 98
106 99 <span class="xdoc">/*! <b>@_nodoc</b>
107 </span> 100 <span class="xdoc"> * ======== sharedMemReq ========
108 </span> 101 <span class="xdoc"> * Amount of shared memory required for creation of each instance
109 </span> 102 <span class="xdoc"> *
110 </span> 103 <span class="xdoc"> * Can be used to make sure the {link #sharedAddr} buffer is large
111 </span> 104 <span class="xdoc"> * enough before calling create.
112 </span> 105 <span class="xdoc"> *
113 </span> 106 <span class="xdoc"> * The {<b>@link</b> #sharedAddr} needs to be
114 </span> 107 <span class="xdoc"> * supplied because the cache alignment settings for the region
115 </span> 108 <span class="xdoc"> * may affect the total amount of shared memory required.
116 </span> 109 <span class="xdoc"> *
117 </span> 110 <span class="xdoc"> * <b>@param(params)</b> Pointer to the parameters that will be used in
118 </span> 111 <span class="xdoc"> * the create.
119 </span> 112 <span class="xdoc"> *
120 </span> 113 <span class="xdoc"> * <b>@a(returns)</b> Number of MAUs needed to create the instance.
121 </span> 114 <span class="xdoc"> */</span>
122 115 SizeT sharedMemReq(<span class=key>const</span> Params *params);
123 116
124 117 <span class="xdoc">/*!
125 </span> 118 <span class="xdoc"> * ======== notifyEventId ========
126 </span> 119 <span class="xdoc"> * Notify event ID for transport.
127 </span> 120 <span class="xdoc"> */</span>
128 121 <span class=key>config</span> UInt16 notifyEventId = 2;
129 122
130 123 <span class=key>instance</span>:
131 124
132 125 <span class="xdoc">/*!
133 </span> 126 <span class="xdoc"> * ======== gate ========
134 </span> 127 <span class="xdoc"> * GateMP used for critical region management of the shared memory
135 </span> 128 <span class="xdoc"> */</span>
136 129 <span class=key>config</span> GateMP.Handle gate = <span class=key>null</span>;
137 130
138 131 <span class="xdoc">/*! <b>@_nodoc</b>
139 </span> 132 <span class="xdoc"> * ======== openFlag ========
140 </span> 133 <span class="xdoc"> * Set to 'true' by the open() call. No one else should touch this!
141 </span> 134 <span class="xdoc"> */</span>
142 135 <span class=key>config</span> Bool openFlag = <span class=key>false</span>;
143 136
144 137 <span class="xdoc">/*!
145 </span> 138 <span class="xdoc"> * ======== sharedAddr ========
146 </span> 139 <span class="xdoc"> * Physical address of the shared memory
147 </span> 140 <span class="xdoc"> *
148 </span> 141 <span class="xdoc"> * The creator must supply the shared memory that is used to maintain
149 </span> 142 <span class="xdoc"> * shared state information.
150 </span> 143 <span class="xdoc"> */</span>
151 144 <span class=key>config</span> Ptr sharedAddr = <span class=key>null</span>;
152 145
153 146 <span class=key>internal</span>:
154 147
155 148 <span class="xdoc">/*!
156 </span> 149 <span class="xdoc"> * Constants that all delegate writers need.
157 </span> 150 <span class="xdoc"> */</span>
158 151 <span class=key>const</span> UInt32 UP = 0xBADC0FFE;
159 152
160 153 <span class="xdoc">/*!
161 </span> 154 <span class="xdoc"> * ======== swiFxn ========
162 </span> 155 <span class="xdoc"> * This function takes the messages from the transport ListMP and
163 </span> 156 <span class="xdoc"> * calls MessageQ_put to send them to their destination queue.
164 </span> 157 <span class="xdoc"> * This function is posted by the NotifyFxn.
165 </span> 158 <span class="xdoc"> *
166 </span> 159 <span class="xdoc"> * <b>@param(arg)</b> argument for the function
167 </span> 160 <span class="xdoc"> */</span>
168 161 Void swiFxn(UArg arg);
169 162
170 163 <span class="xdoc">/*!
171 </span> 164 <span class="xdoc"> * ======== notifyFxn ========
172 </span> 165 <span class="xdoc"> * This is a callback function registered with Notify. It is called
173 </span> 166 <span class="xdoc"> * when a remote processor does a Notify_sendEvent(). It is executed
174 </span> 167 <span class="xdoc"> * at ISR level. It posts the instance Swi object to execute swiFxn.
175 </span> 168 <span class="xdoc"> *
176 </span> 169 <span class="xdoc"> * <b>@param(eventId)</b> Notify event id
177 </span> 170 <span class="xdoc"> * <b>@param(arg)</b> argument for the function
178 </span> 171 <span class="xdoc"> * <b>@param(payload)</b> 32-bit payload value.
179 </span> 172 <span class="xdoc"> */</span>
180 173 Void notifyFxn(UInt16 procId, UInt16 lineId, UInt32 eventId, UArg arg,
181 174 UInt32 payload);
182 175
183 176 <span class="comment">/* Structure of attributes in shared memory */</span>
184 177 <span class=key>struct</span> Attrs {
185 178 Bits32 flag;
186 179 Bits32 creatorProcId;
187 180 Bits32 notifyEventId;
188 181 Bits16 priority;
189 182 SharedRegion.SRPtr gateMPAddr;
190 183 };
191 184
192 185 <span class="comment">/* Instance State object */</span>
193 186 <span class=key>struct</span> Instance_State {
194 187 Attrs *self; <span class="comment">/* Attrs in shared memory */</span>
195 188 Attrs *other; <span class="comment">/* Only flag field is used */</span>
196 189 ListMP.Handle localList; <span class="comment">/* ListMP to my processor */</span>
197 190 ListMP.Handle remoteList; <span class="comment">/* ListMP to remote processor */</span>
198 191 Swi.Object swiObj; <span class="comment">/* Each instance has a swi */</span>
199 192 UInt32 status; <span class="comment">/* Current status */</span>
200 193 Ipc.ObjType objType; <span class="comment">/* Static/Dynamic? open/creator? */</span>
201 194 SizeT allocSize; <span class="comment">/* Shared memory allocated */</span>
202 195 Bool cacheEnabled; <span class="comment">/* Whether to do cache calls */</span>
203 196 UInt16 regionId; <span class="comment">/* the shared region id */</span>
204 197 UInt16 remoteProcId; <span class="comment">/* dst proc id */</span>
205 198 UInt16 priority; <span class="comment">/* priority to register */</span>
206 199 GateMP.Handle gate; <span class="comment">/* Gate for critical regions */</span>
207 200 };
208 201
209 202 }
210 </pre>
211 </body></html>