[processor-sdk/performance-audio-sr.git] / psdk_cust / ipc_3_43_00_00_eng / docs / cdoc / ti / sdo / ipc / gates / GatePeterson-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.gates.GatePeterson</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"> * ======== GatePeterson.xdc ========
41 </span> 34 <span class="comment"> *
42 </span> 35 <span class="comment"> */</span>
43 36
44 37 <span class=key>package</span> ti.sdo.ipc.gates;
45 38
46 39 import xdc.runtime.Error;
47 40 import xdc.runtime.Assert;
48 41 import xdc.runtime.IGateProvider;
49 42 import xdc.runtime.Diags;
50 43 import xdc.runtime.Log;
51 44 import xdc.rov.ViewInfo;
52 45
53 46 import ti.sdo.utils.MultiProc;
54 47 import ti.sdo.ipc.Ipc;
55 48
56 49 import ti.sdo.ipc.interfaces.IGateMPSupport;
57 50
58 51 <span class="xdoc">/*!
59 </span> 52 <span class="xdoc"> * ======== GatePeterson ========
60 </span> 53 <span class="xdoc"> * IGateMPSupport gate based on the Peterson algorithm
61 </span> 54 <span class="xdoc"> *
62 </span> 55 <span class="xdoc"> * This module implements the {<b>@link</b> ti.sdo.ipc.interfaces.IGateMPSupport}
63 </span> 56 <span class="xdoc"> * interface using the Peterson Algorithm in shared memory. This
64 </span> 57 <span class="xdoc"> * implementation works for only 2 processors.
65 </span> 58 <span class="xdoc"> *
66 </span> 59 <span class="xdoc"> * Each GatePeterson instance requires a small piece of
67 </span> 60 <span class="xdoc"> * shared memory. The base address of this shared memory is specified as
68 </span> 61 <span class="xdoc"> * the 'sharedAddr' argument to the create. The amount of shared memory
69 </span> 62 <span class="xdoc"> * consumed by a single instance can be obtained using the
70 </span> 63 <span class="xdoc"> * {<b>@link</b> #sharedMemReq} call.
71 </span> 64 <span class="xdoc"> *
72 </span> 65 <span class="xdoc"> * Shared memory has to conform to the following specification. Padding is
73 </span> 66 <span class="xdoc"> * added between certain elements in shared memory if cache alignment is
74 </span> 67 <span class="xdoc"> * required for the region in which the instance is placed.
75 </span> 68 <span class="xdoc"> *
76 </span> 69 <span class="xdoc"> * <b>@p(code)</b>
77 </span> 70 <span class="xdoc"> *
78 </span> 71 <span class="xdoc"> * shmBaseAddr -> --------------------------- bytes
79 </span> 72 <span class="xdoc"> * | version | 4
80 </span> 73 <span class="xdoc"> * (Attrs struct) | creatorProcId | 2
81 </span> 74 <span class="xdoc"> * | openerProcId | 2
82 </span> 75 <span class="xdoc"> * | (PADDING if aligned) |
83 </span> 76 <span class="xdoc"> * |-------------------------|
84 </span> 77 <span class="xdoc"> * | flag[0] | 2
85 </span> 78 <span class="xdoc"> * | (PADDING if aligned) |
86 </span> 79 <span class="xdoc"> * |-------------------------|
87 </span> 80 <span class="xdoc"> * | flag[1] | 2
88 </span> 81 <span class="xdoc"> * | (PADDING if aligned) |
89 </span> 82 <span class="xdoc"> * |-------------------------|
90 </span> 83 <span class="xdoc"> * | turn | 2
91 </span> 84 <span class="xdoc"> * | (PADDING if aligned) |
92 </span> 85 <span class="xdoc"> * |-------------------------|
93 </span> 86 <span class="xdoc"> * <b>@p</b>
94 </span> 87 <span class="xdoc"> */</span>
95 88 @InstanceInitError
96 89 @InstanceFinalize
97 90
98 91 <span class=key>module</span> GatePeterson <span class=key>inherits</span> IGateMPSupport
99 92 {
100 93 <span class="xdoc">/*! <b>@_nodoc</b> */</span>
101 94 <span class=key>metaonly</span> <span class=key>struct</span> BasicView {
102 95 String objType;
103 96 Ptr localGate;
104 97 UInt nested;
105 98 UInt creatorProcId;
106 99 UInt openerProcId;
107 100 String gateOwner;
108 101 }
109 102
110 103 <span class="xdoc">/*! <b>@_nodoc</b> */</span>
111 104 @Facet
112 105 <span class=key>metaonly</span> <span class=key>config</span> ViewInfo.Instance rovViewInfo =
113 106 ViewInfo.create({
114 107 viewMap: [
115 108 [<span class="string">'Basic'</span>,
116 109 {
117 110 type: ViewInfo.INSTANCE,
118 111 viewInitFxn: <span class="string">'viewInitBasic'</span>,
119 112 structName: <span class="string">'BasicView'</span>
120 113 }
121 114 ],
122 115 ]
123 116 });
124 117
125 118 <span class="xdoc">/*!
126 </span> 119 <span class="xdoc"> * ======== E_gateRemotelyOpened ========
127 </span> 120 <span class="xdoc"> * Error raised when gate cannot be opened because of the opener's ID
128 </span> 121 <span class="xdoc"> *
129 </span> 122 <span class="xdoc"> * Error raised in {<b>@link</b> #open} when trying to remotely open a
130 </span> 123 <span class="xdoc"> * GatePeterson instance whose configured opener processor Id does
131 </span> 124 <span class="xdoc"> * not match that of the opener's MultiProc id. but it has already been
132 </span> 125 <span class="xdoc"> * opened/created on two other processors. GatePeterson only works with
133 </span> 126 <span class="xdoc"> * two processors.
134 </span> 127 <span class="xdoc"> */</span>
135 128 <span class=key>config</span> Error.Id E_gateRemotelyOpened = {
136 129 msg: <span class="string">"E_gateRemotelyOpened: Gate already in use by two other processors: creator: %d, opener: %d"</span>
137 130 };
138 131
139 132 <span class="xdoc">/*!
140 </span> 133 <span class="xdoc"> * ======== numInstances ========
141 </span> 134 <span class="xdoc"> * Maximum number of instances supported by the GatePeterson module
142 </span> 135 <span class="xdoc"> */</span>
143 136 <span class=key>config</span> UInt numInstances = 512;
144 137
145 138 <span class=key>instance</span>:
146 139
147 140 <span class="xdoc">/*!
148 </span> 141 <span class="xdoc"> * <b>@_nodoc</b>
149 </span> 142 <span class="xdoc"> * ======== enter ========
150 </span> 143 <span class="xdoc"> * Enter this gate
151 </span> 144 <span class="xdoc"> */</span>
152 145 @DirectCall
153 146 <span class=key>override</span> IArg enter();
154 147
155 148 <span class="xdoc">/*!
156 </span> 149 <span class="xdoc"> * <b>@_nodoc</b>
157 </span> 150 <span class="xdoc"> * ======== leave ========
158 </span> 151 <span class="xdoc"> * Leave this gate
159 </span> 152 <span class="xdoc"> */</span>
160 153 @DirectCall
161 154 <span class=key>override</span> Void leave(IArg key);
162 155
163 156 <span class=key>internal</span>:
164 157
165 158 <span class="comment">/* Used for the 'flag' in shared memory */</span>
166 159 <span class=key>const</span> UInt32 FREE = 0;
167 160 <span class=key>const</span> UInt32 BUSY = 1;
168 161
169 162 <span class="comment">/* Stored in shared memory */</span>
170 163 <span class=key>struct</span> Attrs {
171 164 Bits16 creatorProcId;
172 165 Bits16 openerProcId;
173 166 };
174 167
175 168 <span class="comment">/* initializes shared memory */</span>
176 169 Void postInit(Object *obj);
177 170
178 171 <span class=key>struct</span> Instance_State {
179 172 Attrs *attrs;
180 173 volatile Bits16 *flag[2];
181 174 volatile Bits16 *turn;
182 175 UInt16 selfId;
183 176 UInt16 otherId;
184 177 UInt nested; <span class="comment">/* For nesting */</span>
185 178 IGateProvider.Handle localGate;
186 179 Ipc.ObjType objType;
187 180 SizeT cacheLineSize;
188 181 Bool cacheEnabled;
189 182 };
190 183 }
191 </pre>
192 </body></html>