1 // Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies). |
|
2 // All rights reserved. |
|
3 // This component and the accompanying materials are made available |
|
4 // under the terms of "Eclipse Public License v1.0" |
|
5 // which accompanies this distribution, and is available |
|
6 // at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // Surface Manager driver |
|
15 // |
|
16 // |
|
17 |
|
18 /** |
|
19 @file |
|
20 @internalComponent |
|
21 @prototype |
|
22 */ |
|
23 |
|
24 |
|
25 /** |
|
26 The driver's name |
|
27 @return The name of the driver |
|
28 @internalComponent |
|
29 */ |
|
30 inline const TDesC& RSurfaceManagerDriver::Name() |
|
31 { |
|
32 _LIT(KSurfaceManagerName, "surfacemanagerdriver"); |
|
33 return KSurfaceManagerName; |
|
34 } |
|
35 |
|
36 /** |
|
37 The driver's version |
|
38 @return The version number of the driver |
|
39 @internalComponent |
|
40 */ |
|
41 inline TVersion RSurfaceManagerDriver::VersionRequired() |
|
42 { |
|
43 const TInt KMajorVersionNumber=1; |
|
44 const TInt KMinorVersionNumber=0; |
|
45 const TInt KBuildVersionNumber=KE32BuildVersionNumber; |
|
46 return TVersion(KMajorVersionNumber,KMinorVersionNumber,KBuildVersionNumber); |
|
47 } |
|
48 |
|
49 |
|
50 #ifndef __KERNEL_MODE__ |
|
51 |
|
52 |
|
53 inline TInt RSurfaceManagerDriver::GetSurfaceManagerAttrib(RSurfaceManager::TSurfaceManagerAttrib aAttrib, TInt& aValue) |
|
54 {return DoControl(RSurfaceManagerDriver::EControlGetSurfaceManagerAttrib, (TAny*)&aAttrib, (TAny*)&aValue);} |
|
55 |
|
56 |
|
57 /** |
|
58 Opens a surface. If the surface is already open in this process, this call increments the reference count for the surface for this process. |
|
59 If the surface hasn't been opened in this process, it opens the surface in this process and sets the reference count to 1 for this process. |
|
60 A surface will be deleted when all its reference counts are 0. |
|
61 @param aSurfaceId The surface id originally returned when the surface was created. |
|
62 @pre The surface id is for an existing surface. |
|
63 @post The surface is open in this process. |
|
64 @return KErrNone if successful otherwise a system wide error code. |
|
65 */ |
|
66 inline TInt RSurfaceManagerDriver::OpenSurface(const TSurfaceId& aSurfaceId) |
|
67 {return DoControl(RSurfaceManagerDriver::EControlOpenSurface, (TAny*)&aSurfaceId);} |
|
68 |
|
69 |
|
70 |
|
71 /** |
|
72 Creates a surface and allocates the memory for the surface. |
|
73 It does not map the surface memory into this process. |
|
74 Sets the surface ID, aSurfaceId, to a globally unique identifier for the surface. |
|
75 The most significant byte of the 4th TUint in the TSurfaceId will be set to a value to identify the surface type. |
|
76 The surface will be open with a reference count of 1 in this process after a successful call to CreateSurface. |
|
77 |
|
78 The creation attributes are validated as follows: |
|
79 The alignment is 1,2,4, 8,16,32,64 or TPageAlignment::EPageAligned. |
|
80 The offset to first buffer is correctly aligned. |
|
81 The width and height are both greater than zero. |
|
82 There is at least one buffer. |
|
83 The calculated chunk size isn't so big that it will exceed a signed int. |
|
84 The caching attribute is valid |
|
85 If the offset between the start of one buffer and the next is specified, it must be correctly aligned and at least as big as the buffer size calculated from the height and stride. |
|
86 A surface hint key of zero is allowed when creating a surface, it is ignored |
|
87 |
|
88 If offset to first buffer or offset between buffers is not aligned properly, then surface manager will do the alignment, based on surface is CPU cached or not. |
|
89 - If surface is CPU cached it will be aligned with minimum of the specified alignment 32(for alignment 1, 2, 4, 8, 16, 32) or 64. |
|
90 - If surface is not CPU cached it will be aligned based on creation attribute's alignment. |
|
91 For page alignment it will be rounded to page size. |
|
92 |
|
93 @param aReqs Input parameter, specifies attributes of the surface required. |
|
94 @param aSurfaceId Output parameter, the surface ID, set if the call succeeds. |
|
95 @pre The device driver is loaded and a channel to it has been opened. |
|
96 @post The surface is created and opened in the creating process. |
|
97 @return KErrNone if it succeeds, KErrArgument if the surface attributes are incorrect, |
|
98 KErrNoMemory if the surface cannot be created due to out of memory, |
|
99 KErrOverflow if the chunk limit has been exceeded in the moving memory model, otherwise a standard Symbian error code. |
|
100 */ |
|
101 inline TInt RSurfaceManagerDriver::CreateSurface(const RSurfaceManager::TSurfaceCreationAttributesBuf& aReqs, TSurfaceId& aSurfaceId) |
|
102 {return DoControl(RSurfaceManagerDriver::EControlCreateSurface, (TAny*)&aReqs, (TAny*)&aSurfaceId);} |
|
103 |
|
104 |
|
105 |
|
106 /** |
|
107 Creates a surface in the shared chunk memory specified by the user. |
|
108 Sets a new surface ID aSurfaceId to a globally unique identifier for the surface. |
|
109 The most significant byte of the 4th TUint in the TSurfaceId will be set to a value to identify |
|
110 the surface type. The surface will be open with a reference count of 1 in this process after a |
|
111 successful call to CreateSurface. |
|
112 The creation attributes are validated as follows: |
|
113 The alignment is 1,2,4, 8,16,32,64 or page alignment. |
|
114 The offset to first buffer is correctly aligned. |
|
115 The width and height are both greater than zero. |
|
116 There is at least one buffer. |
|
117 The chunk should be a valid shared chunk of the necessary size. |
|
118 If the offset between the start of one buffer and the next is specified, it must be correctly |
|
119 aligned and at least as big as the buffer size calculated from the height and stride. |
|
120 A surface hint key of zero is allowed when creating a surface, it is ignored |
|
121 |
|
122 The offset can be 0 and that means the surface manager will calculate the offset |
|
123 The TSurfaceCreationAttributes members iContiguous and iCacheAttribute will not be used for already existing chunks |
|
124 Also, note that surface manager will not do any rounding for offset to first buffer and offset between buffer. |
|
125 Surface manager will expect exact aligned values for this buffer attributes, otherwise surface creation will fail. |
|
126 |
|
127 @param aReqs Input parameter, specifies attributes of the surface required. |
|
128 @param aSurfaceId Output parameter, the surface ID, set if the call succeeds. |
|
129 @param aChunkHandle Handle of the existing shared chunk. |
|
130 |
|
131 Preconditions: |
|
132 @pre The device driver is loaded and a channel has been opened. A valid shared chunk should be created and |
|
133 big enough for the requested size. The shared chunk type should be Shared Kernel multiple and should be right the size, |
|
134 ie., the size should be calculated as Offset to first buffer + (the number of buffers * ((stride * height * pixel depth in bytes) rounded up to the specified alignment) all rounded to a page size |
|
135 @post The surface manager opens the chunk. |
|
136 @return KErrNone if it succeeds, KErrArgument if the surface attributes are incorrect. |
|
137 KErrBadHandle If the handle is of an invalid shared chunk memory |
|
138 */ |
|
139 inline TInt RSurfaceManagerDriver::CreateSurface(const RSurfaceManager::TSurfaceCreationAttributesBuf& aReqs, TSurfaceId& aSurfaceId, const RChunk& aChunkHandle) |
|
140 { |
|
141 TDeviceParam create((TAny*)&aSurfaceId, (TAny*)&aReqs); |
|
142 return DoControl(RSurfaceManagerDriver::EControlCreateSurfaceEx, (TAny*)&create, (TAny*)aChunkHandle.Handle()); |
|
143 } |
|
144 |
|
145 |
|
146 /** |
|
147 Closes the surface. Decrements the reference count for the surface for the calling process. |
|
148 If the surface has other owners, it will not be deleted from memory. |
|
149 If this is the last process to close the surface, the surface will be deleted and the surface ID will become invalid. |
|
150 @param aSurfaceId The surface identifier originally returned when the surface was created. |
|
151 @pre The surface is open. |
|
152 @post The surface is closed. |
|
153 @return KErrNone if successful, KErrArgument if the surface ID does not refer to a surface, |
|
154 KErrAccessDenied if the surface is not open in the current process, otherwise a system wide |
|
155 error code. |
|
156 */ |
|
157 inline TInt RSurfaceManagerDriver::CloseSurface(const TSurfaceId& aSurfaceId) |
|
158 {return DoControl(RSurfaceManagerDriver::EControlCloseSurface, (TAny*)&aSurfaceId);} |
|
159 |
|
160 |
|
161 |
|
162 /** |
|
163 Maps the surface into the current client process address space. |
|
164 The actual memory will remain mapped into the calling process for as long as the RChunk handle aHandle is open. |
|
165 The RChunk handle is owned by the calling thread, so will need to be duplicated if passed to other threads in the process. |
|
166 |
|
167 @param aSurfaceId The surface identifier originally returned when the surface was created. |
|
168 @param aHandle Output parameter, handle to the implementation specific Shared Chunk. |
|
169 @pre The surface is open. |
|
170 @post The surface memory will be mapped into the calling porcesses address space. |
|
171 @return KErrNone if successful, KErrArgument if the surface ID does not refer to a |
|
172 surface, KErrAccessDenied if the surface is not open in the current process, |
|
173 KErrNotSupported if the surface is not mappable, KErrOverflow if the chunk limit has been |
|
174 exceeded in the moving memory model, otherwise a system wide error code. |
|
175 @see RChunk |
|
176 @see RHandleBase::Duplicate |
|
177 */ |
|
178 inline TInt RSurfaceManagerDriver::MapSurface(const TSurfaceId& aSurfaceId, RChunk& aHandle) |
|
179 {return aHandle.SetReturnedHandle(DoControl(RSurfaceManagerDriver::EControlAccessSurfaceData, (TAny*)&aSurfaceId));} |
|
180 |
|
181 |
|
182 |
|
183 /** |
|
184 Returns information about a particular surface identified by its surface ID. |
|
185 @param aSurfaceId The surface identifier originally returned when the surface was created. |
|
186 @param aInfo TInfoBuf to receive the information about the surface. |
|
187 @pre The surface is open in the calling process. |
|
188 @return KErrNone if successful, KErrArgument if the surface ID does not refer to a surface, |
|
189 KErrAccessDenied if the surface is not open in the current process, otherwise a system wide |
|
190 error code. |
|
191 */ |
|
192 inline TInt RSurfaceManagerDriver::SurfaceInfo(const TSurfaceId& aSurfaceId, RSurfaceManager::TInfoBuf& aInfo) |
|
193 {return DoControl(RSurfaceManagerDriver::EControlSurfaceInfo, (TAny*)&aSurfaceId, (TAny*)&aInfo);} |
|
194 |
|
195 |
|
196 |
|
197 /** |
|
198 Opens a channel to the surface manager logical device driver. |
|
199 @pre The logical device driver has been loaded |
|
200 @return Returns KErrNone if successful, KErrNotFound if the driver hasn't been loaded, otherwise a system wide error code. |
|
201 @see User::LoadLogicalDevice |
|
202 */ |
|
203 inline TInt RSurfaceManagerDriver::Open() |
|
204 {return DoCreate(Name(),VersionRequired(),KNullUnit,NULL,NULL,EOwnerProcess);} |
|
205 |
|
206 |
|
207 |
|
208 /** |
|
209 This function ensures the memory is updated consistently before and/or after triggering non CPU hardware access. |
|
210 Also ensures the CPU cache and the physical memory are in a consistent state before and after non CPU hardware or DMA access |
|
211 to the physical memory. |
|
212 @param aSurfaceId The surface identifier originally returned when the surface was created. |
|
213 @param aBuffer The buffer number indexed from 0 within the surface whose memory region is to be flushed. |
|
214 @param aOperation Specifies the sync operation as before non CPU hardware reads or before non CPU hardware writes or after non CPU hardware |
|
215 writes between physical memory of the surface and the cache contents. |
|
216 @pre The surface is open in the calling process. |
|
217 @post The surface buffer memory will be synchronized properly with cache contents. |
|
218 @return KErrNone if successful, KErrArgument if the surface ID is invalid or |
|
219 buffer number is invalid, KErrAccessDenied if the surface is not open in this |
|
220 process, otherwise a system wide error code. |
|
221 */ |
|
222 inline TInt RSurfaceManagerDriver::SynchronizeCache(const TSurfaceId& aSurfaceId, TInt aBuffer, RSurfaceManager::TSyncOperation aOperation) |
|
223 { |
|
224 TDeviceParam buff((TAny*)&aSurfaceId, (TAny*)aBuffer); |
|
225 return DoControl(RSurfaceManagerDriver::EControlSynchronizeCache, (TAny*)&buff, (TAny*)aOperation); |
|
226 } |
|
227 |
|
228 /** |
|
229 Get the surface hint value for the given surface ID and hint pair key. |
|
230 @param aSurfaceId The surface identifier originally returned when the surface was created. |
|
231 @param aHint The hint value for the requested hint pair key. |
|
232 @pre The surface is open in the calling process. |
|
233 @pre Hint key should be a key for a hint set for this surface. |
|
234 @post The hint value will be updated in the hint pair. |
|
235 @return KErrNone if successful, KErrArgument if the surface ID is invalid or |
|
236 invalid hint pair key used, KErrAccessDenied if the surface is not open in the |
|
237 current process, otherwise a system wide error code. |
|
238 */ |
|
239 inline TInt RSurfaceManagerDriver::GetSurfaceHint(const TSurfaceId& aSurfaceId, RSurfaceManager::THintPair& aHint) |
|
240 {return DoControl(RSurfaceManagerDriver::EControlGetSurfaceHint, (TAny*)&aSurfaceId, (TAny*)&aHint);} |
|
241 |
|
242 |
|
243 /** |
|
244 Set the surface hint value for the surface Id. |
|
245 Parameters: |
|
246 @param aSurfaceId The surface identifier originally returned when the surface was created. |
|
247 @param aHint The value of the hint pair to set. |
|
248 @pre The surface is open in the calling process. |
|
249 @pre The Hint key should be a key for a hint set for this surface. |
|
250 @pre Only mutable hints can be updated. |
|
251 @post The hint value will be updated in the surface hint pair. |
|
252 @return KErrNone if successful, KErrArgument if the surface ID is invalid or if invalid |
|
253 hint key used, KErrAccessDenied if the hint pair is immutable or the surface is not open |
|
254 in the current process, otherwise a system wide error code. |
|
255 */ |
|
256 inline TInt RSurfaceManagerDriver::SetSurfaceHint(const TSurfaceId& aSurfaceId, const RSurfaceManager::THintPair& aHint) |
|
257 {return DoControl(RSurfaceManagerDriver::EControlSetSurfaceHint, (TAny*)&aSurfaceId, (TAny*)&aHint);} |
|
258 |
|
259 |
|
260 /** |
|
261 Adds a new surface hint to the surface. This function will fail if the surface already has its maximum number of hints |
|
262 or if the hint key is a duplicate or invalid. |
|
263 Parameters: |
|
264 @param aSurfaceId The surface identifier originally returned when the surface was created. |
|
265 @param aHint The value of the hint pair to add. |
|
266 @pre The surface is open in the calling process. |
|
267 @pre Atleast one free space to add a hint pair. |
|
268 @pre The new hint key should be unique. |
|
269 @post New hint pair will be added in the surface. |
|
270 @return Returns KErrNone if successful, KErrArgument if the surface ID is invalid or the |
|
271 hint pair has invalid key UID, KErrAccessDenied if the surface is not open in the current |
|
272 process, KErrAlreadyExists if duplicate hint key used, KErrOverflow if no space to add new |
|
273 pair, otherwise a system wide error code. |
|
274 */ |
|
275 inline TInt RSurfaceManagerDriver::AddSurfaceHint(const TSurfaceId& aSurfaceId, const RSurfaceManager::THintPair& aHint) |
|
276 {return DoControl(RSurfaceManagerDriver::EControlAddSurfaceHint, (TAny*)&aSurfaceId, (TAny*)&aHint);} |
|
277 |
|
278 /** |
|
279 Get the offset of the specified buffer from the base address of the underlying |
|
280 chunk. |
|
281 |
|
282 To obtain the address of the buffer, the offset returned must be added onto the |
|
283 base address of the RChunk returned in a call to MapSurface(). Note that |
|
284 buffer offsets are immutable during the lifetime of the surface. |
|
285 @param aSurfaceId The surface identifier originally returned when the surface |
|
286 was created. |
|
287 @param aBuffer The buffer for which the offset is requested. Indexed from 0. |
|
288 @param aOffset Output parameter set to the offset within the chunk. |
|
289 @pre The surface is open in the calling process. |
|
290 @return KErrNone if successful, KErrArgument if aSurfaceId or aBuffer are invalid, |
|
291 KErrAccessDenied if the surface is not open in the current process, KErrNotSupported if |
|
292 the surface is not mappable, otherwise a system wide error code. |
|
293 */ |
|
294 inline TInt RSurfaceManagerDriver::GetBufferOffset(const TSurfaceId& aSurfaceId, TInt aBuffer, TInt& aOffset) |
|
295 { |
|
296 TDeviceParam buff((TAny*)&aSurfaceId, (TAny*)aBuffer); |
|
297 return DoControl(RSurfaceManagerDriver::EControlGetBufferOffset, (TAny*)&buff, (TAny*)&aOffset); |
|
298 } |
|
299 |
|
300 #endif //__KERNEL_MODE__ |
|
301 |
|