1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/kernelhwsrv/kernel/eka/drivers/resourceman/resourceman.cpp Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,844 @@
1.4 +// Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies).
1.5 +// All rights reserved.
1.6 +// This component and the accompanying materials are made available
1.7 +// under the terms of the License "Eclipse Public License v1.0"
1.8 +// which accompanies this distribution, and is available
1.9 +// at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.10 +//
1.11 +// Initial Contributors:
1.12 +// Nokia Corporation - initial contribution.
1.13 +//
1.14 +// Contributors:
1.15 +//
1.16 +// Description:
1.17 +// e32\drivers\resourceman\resourceman.cpp
1.18 +//
1.19 +//
1.20 +
1.21 +#include <drivers/resourcecontrol.h>
1.22 +#include <drivers/resourceman.h>
1.23 +/**
1.24 +@publishedPartner
1.25 +@prototype 9.5
1.26 +
1.27 +Register a client with the resource manager
1.28 +
1.29 +@param aClientId A reference to a client ID: returns a unique handle if registration was
1.30 + successful, 0 otherwise.
1.31 +@param aName Descriptor with name for client. The descriptor is created by the client
1.32 + in kernel heap or in kernel stack.
1.33 + NOTE: Name should ideally relate to component name and should take care
1.34 + of name uniqueness as this is not checked by resource manager unless
1.35 + DEBUG_VERSION macro is enabled.
1.36 +@param aType Defines ownership
1.37 + EOwnerProcess - The client ID can be used by all thread in the process to
1.38 + call the resource manager API's
1.39 + EOwnerThread - The client ID can only be used by the thread that registered
1.40 + the client to resource manager to call the PRM API's
1.41 + By default this is set to EOwnerProcess.
1.42 +
1.43 +@return KErrNone if the operation was successful,
1.44 + KErrNoMemory if a new client link was needed but could not be created and
1.45 + added to the client list,
1.46 + KErrTooBig if the length of the descriptor passed is greater than 32.
1.47 + KErrAlreadyExists if the specified name already exists. This is valid only if
1.48 + DEBUG_VERSION macro is enabled.
1.49 + KErrNotSupported if the number of expected kernel side clients is set to zero
1.50 + by PSL during initialisation.
1.51 +
1.52 +@pre Interrupts must be enabled.
1.53 +@pre Kernel must be unlocked.
1.54 +@pre No fast mutex can be held.
1.55 +@pre Call in a thread context, but not from null thread or DFC thread1.
1.56 +@pre Can be used in a device driver
1.57 +*/
1.58 +EXPORT_C TInt PowerResourceManager::RegisterClient(TUint& aClientId, const TDesC8& aName, TOwnerType aType)
1.59 + {
1.60 + __KTRACE_OPT(KRESMANAGER, Kern::Printf(">PowerResourceManager::RegisterClient"));
1.61 + __KTRACE_OPT(KRESMANAGER, Kern::Printf("Client Name %S", &aName));
1.62 + __KTRACE_OPT(KRESMANAGER, Kern::Printf("OwnerType %d", aType));
1.63 + return TInterface::RegisterClient(aClientId, aName, aType);
1.64 + }
1.65 +
1.66 +/**
1.67 +@publishedPartner
1.68 +@prototype 9.5
1.69 +
1.70 +Deregister a client with the resource manager
1.71 +
1.72 +@param aClientId The ID of the client which is being deregistered
1.73 +
1.74 +@return KErrNone if the operation was successful
1.75 + KErrNotFound if this client ID could not be found in the current
1.76 + list of clients
1.77 + KErrArgument if user side client ID is specified or client ID to be used
1.78 + by Power Controller is specified.
1.79 + KErrAccessDenied if client was registered to be thread relative and this API
1.80 + is not called from the same thread.
1.81 +
1.82 +
1.83 +@pre Interrupts must be enabled
1.84 +@pre Kernel must be unlocked
1.85 +@pre No fast mutex can be held
1.86 +@pre Call in a thread context but not from null thread or DFC thread1
1.87 +@pre Can be used in a device driver
1.88 +*/
1.89 +EXPORT_C TInt PowerResourceManager::DeRegisterClient(TUint aClientId)
1.90 + {
1.91 + __KTRACE_OPT(KRESMANAGER, Kern::Printf(">PowerResourceManager::DeRegisterClient"));
1.92 + __KTRACE_OPT(KRESMANAGER, Kern::Printf("Client ID %d", aClientId));
1.93 + return TInterface::DeRegisterClient(aClientId);
1.94 + }
1.95 +
1.96 +/**
1.97 +@publishedPartner
1.98 +@prototype 9.5
1.99 +
1.100 +Obtain the name of a registered client of the resource manager
1.101 +
1.102 +@param aClientId The ID of the client which is requesting the name of
1.103 + another client whose ID is specified in aTargetClientId.
1.104 +@param aTargetClientId The ID of the client whose name is being requested.
1.105 +@param aName Descriptor to be filled with the name of the client.
1.106 + The descriptor is created by the client in kernel stack or heap.
1.107 +
1.108 +@return KErrNone if the operation was successful
1.109 + KErrNotFound if this client ID (aTargetClientId) could not be
1.110 + found in the current list of registered clients.
1.111 + KErrAccessDenied if the client ID (aClientId) could not be found
1.112 + in the current list of registered clients or if the client was
1.113 + registered to be thread relative and this API is not called from
1.114 + the same thread.
1.115 +
1.116 +@pre Interrupts must be enabled
1.117 +@pre Kernel must be unlocked
1.118 +@pre No fast mutex can be held
1.119 +@pre Call in a thread context but not from null thread or DFC thread1
1.120 +@pre Can be used in a device driver
1.121 +*/
1.122 +EXPORT_C TInt PowerResourceManager::GetClientName(TUint aClientId, TUint aTargetClientId, TDes8&
1.123 + aName)
1.124 + {
1.125 + __KTRACE_OPT(KRESMANAGER, Kern::Printf(">PowerResourceManager::GetClientName"));
1.126 + __KTRACE_OPT(KRESMANAGER, Kern::Printf("aClientId 0x%08x", aClientId));
1.127 + __KTRACE_OPT(KRESMANAGER, Kern::Printf("aTargetClientId 0x%08x", aTargetClientId));
1.128 + return TInterface::GetClientName(aClientId, aTargetClientId, aName);
1.129 + }
1.130 +
1.131 +/**
1.132 +@publishedPartner
1.133 +@prototype 9.5
1.134 +
1.135 +Obtain the Id of registered client of the resource manager
1.136 +
1.137 +@param aClientId ID of the client which is requesting the ID of the another
1.138 + client whose name is specified in aClientName
1.139 +@param aClientName Descriptor containing the name of the client whose ID is being
1.140 + requested. The client must create the descriptor in kernel stack
1.141 + or heap.
1.142 + NOTE: Resource manager does not check for uniqueness of client
1.143 + name during registration, so if there are multiple clients registered
1.144 + to PRM with same name it will return the ID of the first client encountered
1.145 + with the specified name (order is not guaranteed).
1.146 +@param aTargetClientId Updates with ID of the requested client on success
1.147 +
1.148 +@return KErrNone if the operation was successful
1.149 + KErrNotFound if this client name could not be found in the current list
1.150 + of registered client.
1.151 + KErrAccessDenied if the client ID (aClientId) could not be found in the current
1.152 + list of registered client or if the client was registered to
1.153 + be thread relative and this API is not called from the same thread.
1.154 + KErrTooBig if the length of the descriptor passed is greater than 32.
1.155 +
1.156 +@pre Interrupts must be enabled
1.157 +@pre Kernel must be unlocked
1.158 +@pre No fast mutex can be held
1.159 +@pre Call in a thread context but not from null thread or DFC thread1
1.160 +@pre Can be used in a device driver
1.161 +*/
1.162 +EXPORT_C TInt PowerResourceManager::GetClientId(TUint aClientId, TDesC8& aClientName, TUint& aTargetClientId)
1.163 + {
1.164 + __KTRACE_OPT(KRESMANAGER, Kern::Printf(">PowerResourceManager::GetClientId"));
1.165 + __KTRACE_OPT(KRESMANAGER, Kern::Printf("aClientId 0x%08x", aClientId));
1.166 + __KTRACE_OPT(KRESMANAGER, Kern::Printf("aClientName %S", &aClientName));
1.167 + return TInterface::GetClientId(aClientId, aClientName, aTargetClientId);
1.168 + }
1.169 +
1.170 +/**
1.171 +@publishedPartner
1.172 +@prototype 9.5
1.173 +
1.174 +Obtain the ID of registered resource of the resource manager.
1.175 +NOTE: ID of the first matching name found in the resource list will be returned
1.176 +
1.177 +@param aClientId ID of the client which is requesting the ID of the
1.178 + resource, by specifying its name.
1.179 +@param aResourceName Descriptor containing the name of the resource whose
1.180 + ID is being requested.The client must create descriptor in
1.181 + kernel stack or heap.
1.182 +@param aResourceId Updates with ID of the requested resource on success
1.183 +
1.184 +@return KErrNone if the operation was successful
1.185 + KErrAccessDenied if the ID of the client could not be found in the
1.186 + current list of registered clients or if the client was
1.187 + registered to be thread relative and this API is not called
1.188 + from the same thread.
1.189 + KErrNotFound if this resource name could not be found in the current
1.190 + list of registered resources.
1.191 + KErrTooBig if the length of the descriptor passed is greater than 32.
1.192 +
1.193 +@pre Interrupts must be enabled
1.194 +@pre Kernel must be unlocked
1.195 +@pre No fast mutex can be held
1.196 +@pre Call in a thread context but not from null thread or DFC thread1
1.197 +@pre Can be used in a device driver
1.198 +*/
1.199 +EXPORT_C TInt PowerResourceManager::GetResourceId(TUint aClientId, TDesC8& aResourceName, TUint& aResourceId)
1.200 + {
1.201 + __KTRACE_OPT(KRESMANAGER, Kern::Printf(">PowerResourceManager::GetResourceId"));
1.202 + __KTRACE_OPT(KRESMANAGER, Kern::Printf("aClientId 0x%08x", aClientId));
1.203 + __KTRACE_OPT(KRESMANAGER, Kern::Printf("aResourceName %S", &aResourceName));
1.204 + return TInterface::GetResourceId(aClientId, aResourceName, aResourceId);
1.205 + }
1.206 +
1.207 +/**
1.208 +@publishedPartner
1.209 +@prototype 9.5
1.210 +
1.211 +Request a structure containing information on a resource.
1.212 +
1.213 +@param aClientId ID of the client which is requesting the resource information
1.214 +@param aResourceId ID of the resource whose information is being requested.
1.215 +@param aInfo A pointer to descriptor containing resource information
1.216 + structure (TPowerResourceInfoV01) to be filled in
1.217 + with the requested resource information. The client must
1.218 + create the descriptor in kernel stack or heap.
1.219 +
1.220 +@return KErrNone if the operation was successful
1.221 + KErrAccessDenied if the client ID could not be found in the current list
1.222 + of registered clients or if the client was registered to be
1.223 + thread relative and this API is not called from the same thread.
1.224 + KErrNotFound if this resource ID could not be found in the current list
1.225 + of controllable resource.
1.226 + KErrArgument if aInfo is NULL or size of descriptor passed is less than size of
1.227 + TPowerResourceInfoV01.
1.228 +
1.229 +@pre Interrupts must be enabled
1.230 +@pre Kernel must be unlocked
1.231 +@pre No fast mutex can be held
1.232 +@pre Call in a thread context but not from null thread or DFC thread1
1.233 +@pre Can be used in a device driver
1.234 +*/
1.235 +EXPORT_C TInt PowerResourceManager::GetResourceInfo(TUint aClientId, TUint aResourceId, TAny* aInfo)
1.236 + {
1.237 + __KTRACE_OPT(KRESMANAGER, Kern::Printf(">PowerResourceManager::GetResourceInfo"));
1.238 + __KTRACE_OPT(KRESMANAGER, Kern::Printf("aClientId 0x%08x", aClientId));
1.239 + __KTRACE_OPT(KRESMANAGER, Kern::Printf("aResourceId 0x%08x", aResourceId));
1.240 + return TInterface::GetResourceInfo(aClientId, aResourceId, aInfo);
1.241 + }
1.242 +
1.243 +
1.244 +/**
1.245 +@publishedPartner
1.246 +@prototype 9.5
1.247 +
1.248 +Request number of resources that the specified client (aTargetClientId) has
1.249 +requirement on resource level. Client ID starts from 1, so if 0 is specified in
1.250 +aTargetClientId, returns the total number of controllable resources registered with PRM.
1.251 +
1.252 +@param aClientId ID of the client that is requesting the number of resources for which
1.253 + the specified client (aTargetClientId) holds requirement on the
1.254 + resource level change.
1.255 +@param aTargetClientId ID of the client for which the number of resources that it
1.256 + has requested a level on is to be returned.
1.257 +@param aNumResource Updated with the number of resources that the specified client
1.258 + has requirement on resource level change, if valid client
1.259 + ID is passed. If client ID is 0, updates the total number
1.260 + of resources registered with resource manager.
1.261 +
1.262 +@return KErrNone if the operation was successful.
1.263 + KErrAccessDenied if the client ID (aClientId) could not be found in the
1.264 + current list of registered clients or if the client was registered
1.265 + to be thread relative and this API is not called from the same thread.
1.266 + KErrNotFound if the client ID (aTargetClientId) could not be found in the
1.267 + current list of registered clients and is not 0.
1.268 +
1.269 +@pre Interrupts must be enabled
1.270 +@pre Kernel must be unlocked
1.271 +@pre No fast mutex can be held
1.272 +@pre Call in a thread context but not from null thread or DFC thread1
1.273 +@pre Can be used in a device driver
1.274 +*/
1.275 +EXPORT_C TInt PowerResourceManager::GetNumResourcesInUseByClient(TUint aClientId, TUint aTargetClientId,
1.276 + TUint& aNumResource)
1.277 + {
1.278 + __KTRACE_OPT(KRESMANAGER, Kern::Printf(">PowerResourceManager::GetNumResourcesInUseByClient"));
1.279 + __KTRACE_OPT(KRESMANAGER, Kern::Printf("aClientId 0x%08x", aClientId));
1.280 + __KTRACE_OPT(KRESMANAGER, Kern::Printf("aTargetClientId 0x%08x", aTargetClientId));
1.281 + return TInterface::GetNumResourcesInUseByClient(aClientId, aTargetClientId, aNumResource);
1.282 + }
1.283 +
1.284 +/**
1.285 +@publishedPartner
1.286 +@prototype 9.5
1.287 +
1.288 +Request information on resources.
1.289 +If client ID (aTargetClientId) is valid, aInfo is updated with the information
1.290 +of the resources that this client requested a resource level.
1.291 +If client ID (aTargetClientId) is 0, aInfo is updated with the information of all the resources
1.292 +registered with resource controller.
1.293 +The number of resources for which information will be provided will be equal or less than
1.294 +the number specified in aNumResources.
1.295 +
1.296 +@param aClientId ID of the client which is requesting the resource information.
1.297 +@param aTargetClientId ID of the client. The information of all the resources on
1.298 + which it has requirement on resource level change is requested.
1.299 + Client ID starts from 1, so calling this API with client ID 0 will
1.300 + fill the details of all the controllable resource registered with
1.301 + resource manager starting from resource ID 1.
1.302 +@param aNumResources Number of resource whose information needs to be filled in aInfo i.e,
1.303 + it specifies the size of aInfo array.
1.304 +@param aInfo A pointer to an array of descriptor containing an information structure
1.305 + (TPowerResourceInfoV01) to be filled in with the information
1.306 + on the resources. It will be assumed that array allocated will be equal
1.307 + to the number passed in aNumResources. The client must create the array
1.308 + in Kernel stack or heap.
1.309 +
1.310 +@return KErrNone if the operation was successful
1.311 + KErrAccessDenied if client ID (aClientId) could not be found in the registered
1.312 + client list or if the client was registered to be thread relative
1.313 + and this API is not called from the same thread.
1.314 + KErrNotFound if client ID (aTargetClientId) could not be found in the current list
1.315 + of registered client and is also not 0.
1.316 + KErrArgument if aNumResources is 0 or aInfo is NULL or if size of aInfo is not
1.317 + sufficient to hold the resource information of number of resources
1.318 + specified in aNumResource.
1.319 +
1.320 +@pre Interrupts must be enabled
1.321 +@pre Kernel must be unlocked
1.322 +@pre No fast mutex can be held
1.323 +@pre Call in a thread context but not from null thread or DFC thread1
1.324 +@pre Can be used in a device driver
1.325 +*/
1.326 +EXPORT_C TInt PowerResourceManager::GetInfoOnResourcesInUseByClient(TUint aClientId, TUint aTargetClientId,
1.327 + TUint& aNumResource, TAny* aInfo)
1.328 + {
1.329 + __KTRACE_OPT(KRESMANAGER, Kern::Printf(">PowerResourceManager::GetInfoOnResourcesInUseByClient"));
1.330 + __KTRACE_OPT(KRESMANAGER, Kern::Printf("aClientId 0x%08x", aClientId));
1.331 + __KTRACE_OPT(KRESMANAGER, Kern::Printf("aTargetClientId 0x%08x", aTargetClientId));
1.332 + __KTRACE_OPT(KRESMANAGER, Kern::Printf("aNumResource 0x%08x", aNumResource));
1.333 + return TInterface::GetInfoOnResourcesInUseByClient(aClientId, aTargetClientId, aNumResource, aInfo);
1.334 + }
1.335 +
1.336 +/**
1.337 +@publishedPartner
1.338 +@prototype 9.5
1.339 +
1.340 +Request number of clients which has requirements on the resource level change of the specified
1.341 +resource. Resource ID starts from 1, so 0 can be used to get the number of clients
1.342 +registered with resource manager.
1.343 +
1.344 +@param aClientId ID of the client which is requesting number of clients
1.345 + holding requirement on specified resource.
1.346 +@param aResourceId ID of the resource.
1.347 +@param aNumClient Upon success, updated with number of clients having a requirement
1.348 + on resource level for the specified resource, if valid resource ID is specified.
1.349 + If resource ID is 0, then it is updated with number of clients
1.350 + registered with PRM.
1.351 +
1.352 +@return KErrNone if the operation was successful
1.353 + KErrAccessDenied if the client ID could not found in the current list of
1.354 + registered clients or if the client was registered to be thread
1.355 + relative and this API is not called from the same thread.
1.356 + KErrNotFound If this resource ID could not be found in the current list
1.357 + of registered resource and is also not 0.
1.358 +
1.359 +@pre Interrupts must be enabled
1.360 +@pre Kernel must be unlocked
1.361 +@pre No fast mutex can be held
1.362 +@pre Call in a thread context but not from null thread or DFC thread1
1.363 +@pre Can be used in a device driver
1.364 +*/
1.365 +EXPORT_C TInt PowerResourceManager::GetNumClientsUsingResource(TUint aClientId, TUint aResourceId, TUint& aNumClients)
1.366 + {
1.367 + __KTRACE_OPT(KRESMANAGER, Kern::Printf(">PowerResourceManager::GetNumClientsUsingResource"));
1.368 + __KTRACE_OPT(KRESMANAGER, Kern::Printf("aClientId 0x%08x", aClientId));
1.369 + __KTRACE_OPT(KRESMANAGER, Kern::Printf("aResourceId 0x%08x", aResourceId));
1.370 + return TInterface::GetNumClientsUsingResource(aClientId, aResourceId, aNumClients);
1.371 + }
1.372 +
1.373 +/**
1.374 +@publishedPartner
1.375 +@prototype 9.5
1.376 +
1.377 +Request information on clients
1.378 +If resource ID is valid, aInfo is updated with the information of the clients
1.379 +which have a requirements on the resource level for the specified resource
1.380 +If resource ID is 0, aInfo is updated with the information of the clients registered
1.381 +with resource manager, starting from client ID 1.
1.382 +The number of clients for which information will be provided will be equal to or less
1.383 +than the number specified in a NumClients.
1.384 +
1.385 +@param aClientId ID of the client which is requesting the information
1.386 +@param aResourceId Id of the resource.
1.387 +@param aNumClients Number of clients whose information needs to be filled in aInfo
1.388 + ie, it specifies the size of aInfo array.
1.389 +@param aInfo A pointer to an array of descriptor containing an information
1.390 + structure (TPowerClientInfoV01) to be filled in with
1.391 + the information on the client. It will be assumed that array
1.392 + allocated will be equal to the number passed in aNumClients.
1.393 + The Client must create the array of descriptors in kernel stack
1.394 + or heap.
1.395 +
1.396 +@return KErrNone if the operation was successful.
1.397 + KErrNotFound if resource ID could not be found in the registered resource list and is
1.398 + also not 0.
1.399 + KErrAccessDenied if client ID (aClientId) could not be found in the registered client list
1.400 + or if the client was registered to be thread relative and this API is not
1.401 + called from the same thread.
1.402 + KErrArgument if aNumClients is 0 or aInfo is NULL or if size of aInfo is not sufficient
1.403 + to hold client information of specified client number in aNumClients.
1.404 +
1.405 +@pre Interrupts must be enabled
1.406 +@pre Kernel must be unlocked
1.407 +@pre No fast mutex can be held
1.408 +@pre Call in a thread context but not from null thread or DFC thread1
1.409 +@pre Can be used in a device driver
1.410 +*/
1.411 +EXPORT_C TInt PowerResourceManager::GetInfoOnClientsUsingResource(TUint aClientId, TUint aResourceId,
1.412 + TUint& aNumClients, TAny* aInfo)
1.413 + {
1.414 + __KTRACE_OPT(KRESMANAGER, Kern::Printf(">PowerResourceManager::GetInfoOnClientsUsingResource"));
1.415 + __KTRACE_OPT(KRESMANAGER, Kern::Printf("aClientId 0x%08x", aClientId));
1.416 + __KTRACE_OPT(KRESMANAGER, Kern::Printf("aResourceId 0x%08x", aResourceId));
1.417 + __KTRACE_OPT(KRESMANAGER, Kern::Printf("aNumClients 0x%08x", aNumClients));
1.418 + return TInterface::GetInfoOnClientsUsingResource(aClientId, aResourceId, aNumClients, aInfo);
1.419 + }
1.420 +
1.421 +/**
1.422 +@publishedPartner
1.423 +@prototype 9.5
1.424 +
1.425 +Request changing the state of a resource
1.426 +NOTE: If a resource callback is specified for instantaneous resource, then callback
1.427 + will be called after resource change and will be executed in the context of the
1.428 + client thread.
1.429 + If a resource callback is specified for long latency reosurces, then it will be
1.430 + executed asynchronously.
1.431 + When the request is accepted the API returns immediately and the calling thread
1.432 + is unblocked: the callback (called in the client's context) will be invoked when
1.433 + the resource change finally takes place.
1.434 + If aCb is not specified (NULL by default) the API executes synchronously and will
1.435 + only return when the resource change has taken place for long latency resource.
1.436 + The client thread is blocked throughout
1.437 + When state change for a shared resource is requested, only minimum state that
1.438 + satisfy the requirement is guaranteed and it is not guaranteed for the absolute
1.439 + value change.
1.440 +
1.441 +@param aClientId ID of the client which is requesting the resource change.
1.442 +@param aResourceId ID of the resource whose state is to be changed.
1.443 +@param aNewState The new state of the resource. This could be a binary value for a
1.444 + binary resource, an integer level for a multilevel resource or some
1.445 + platform specific token for a multi-property resource.
1.446 +@param aCb For Long latency resource
1.447 + A pointer to a resource callback object which encapsulates a
1.448 + callback function to be called whenever the resource state change
1.449 + happens (if left NULL the API will execute synchrounously).
1.450 + For Instantaneous resource
1.451 + A pointer to a resource callback object which encapsulates a callback
1.452 + function to be called after resource change. This executes in the
1.453 + context of the client thread.
1.454 +
1.455 +@return KErrNone If the API is to be executed synchronously it indicates the change was
1.456 + successful, if the API is to be executed asynchronously it indicates
1.457 + the request to change the resource state has been accepted.
1.458 + KErrNotFound if the resource ID could not be found in the current list of
1.459 + controllable resources.
1.460 + KErrAccessDenied if the client ID could not be found in the list of
1.461 + registered clients or if the client was registered to be thread
1.462 + relative and this API is not called from the same thread.
1.463 + KErrNotReady if the request is issued before the resource controller completes its
1.464 + internal initialisation.
1.465 + KErrUnderflow if the client has exceeded the reserved number of
1.466 + SPowerResourceClientLevel and the free pool is empty or if it is
1.467 + an asynchronous operation on long latency resource and the client has exceeded
1.468 + the reserved number of TPowerRequest and the free pool is empty.
1.469 + KErrArgument if requested level is out of range (outside of min and max levels)
1.470 + KErrPermissionDenied if the requested state of the resource is not accepted by its dependents.
1.471 + This error is valid only for dependent resource state change in extened
1.472 + version of PRM.
1.473 +
1.474 +@pre Interrupts must be enabled
1.475 +@pre Kernel must be unlocked
1.476 +@pre No fast mutex can be held
1.477 +@pre Call in a thread context but not from null thread or DFC thread1
1.478 +@pre Can be used in a device driver
1.479 +@pre Do not call synchronous version from DFC thread 0 for long latency resource
1.480 +*/
1.481 +EXPORT_C TInt PowerResourceManager::ChangeResourceState(TUint aClientId , TUint aResourceId,
1.482 + TInt aNewState, TPowerResourceCb* aCb)
1.483 + {
1.484 + __KTRACE_OPT(KRESMANAGER, Kern::Printf(">PowerResourceManager::ChangeResourceState"));
1.485 + __KTRACE_OPT(KRESMANAGER, Kern::Printf("aClientId 0x%08x", aClientId));
1.486 + __KTRACE_OPT(KRESMANAGER, Kern::Printf("aResourceId 0x%08x", aResourceId));
1.487 + __KTRACE_OPT(KRESMANAGER, Kern::Printf("aNewState 0x%08x", aNewState));
1.488 + return TInterface::ChangeResourceState(aClientId, aResourceId, aNewState, aCb);
1.489 + }
1.490 +
1.491 +/**
1.492 +@publishedPartner
1.493 +@prototype 9.5
1.494 +
1.495 +Request the state of the resource synchronously. Client thread will be blocked throughout.
1.496 +
1.497 +@param aClientId ID of the client which is requesting the resource state.
1.498 +@param aResourceId ID of the resource whose state is being requested.
1.499 +@param aCached If ETrue, cached value will be updated in aState.
1.500 + If EFalse, aState will be updated after the resource
1.501 + state is read from resource.
1.502 +@param aState Returns the resource state if operation was successful. This
1.503 + could be a binary value for a binary resource, an integer level
1.504 + for a multilevel resource or some platform specific tolen for a
1.505 + multi-property resource.
1.506 +@param aLevelOwnerId Returns the Id of the client that is currently the owner of the resource.
1.507 + -1 is returned when no client is owner of the resource.
1.508 +
1.509 +@return KErrNone if operation was successful
1.510 + KErrAccessDenied if the client ID could not be found in the current list
1.511 + of registered clients or if the client was registered to be thread
1.512 + relative and this API is not called from the same thread.
1.513 + KErrNotFound if this resource ID could not be found in the current list
1.514 + of controllable resources.
1.515 + KErrNotReady if the request is issued before the resource controller completes
1.516 + its internal initialization.
1.517 +
1.518 +@pre Interrupts must be enabled
1.519 +@pre Kernel must be unlocked
1.520 +@pre No fast mutex can be held
1.521 +@pre Call in a thread context but not from null thread or DFC thread1
1.522 +@pre Can be used in a device driver
1.523 +@pre Do not call from DFC thread 0 for long latency resource with caching disabled.
1.524 +*/
1.525 +EXPORT_C TInt PowerResourceManager::GetResourceState(TUint aClientId, TUint aResourceId, TBool aCached,
1.526 + TInt& aState, TInt& aLevelOwnerId)
1.527 + {
1.528 + __KTRACE_OPT(KRESMANAGER, Kern::Printf(">PowerResourceManager::GetResourceState"));
1.529 + __KTRACE_OPT(KRESMANAGER, Kern::Printf("aClientId 0x%08x", aClientId));
1.530 + __KTRACE_OPT(KRESMANAGER, Kern::Printf("aResourceId 0x%08x", aResourceId));
1.531 + __KTRACE_OPT(KRESMANAGER, Kern::Printf("aCached 0x%08x", aCached));
1.532 + return TInterface::GetResourceState(aClientId, aResourceId, aCached, aState, aLevelOwnerId);
1.533 + }
1.534 +
1.535 +/**
1.536 +@publishedPartner
1.537 +@prototype 9.5
1.538 +
1.539 +Request the state of the resource asynchrounously.
1.540 +
1.541 +@param aClientId ID of the client which is requesting the resource state.
1.542 +@param aResourceId ID of the resource whose state is being requested.
1.543 +@param aCached If ETrue, cached value will be updated in aState
1.544 + If EFalse, will be updated after the resource state is read from resource
1.545 +@param aCb For long latency resource:
1.546 + A pointer to a resource callback object which encapsulates a callback function
1.547 + to be called whenever the state of the resource is available for the long
1.548 + latency resource (executes in the context of resource manager)
1.549 + For instantaneous resource:
1.550 + A pointer to a resource callback object which encapsulates a callback
1.551 + function to be called after the resource state is read. This is executed
1.552 + synchronously in the context of the calling thread.
1.553 + NOTE: The client must create the callback object in kernel heap or
1.554 + data section.
1.555 +
1.556 +@return KErrNone if the operation was successful
1.557 + KErrAccessDenied if the client ID could not be found in the current list
1.558 + of registered clients or if the client was registered to be
1.559 + thread relative and this API is not called from the same thread.
1.560 + KErrNotFound if this resource ID could not be found in the current list
1.561 + of controllable resources.
1.562 + KErrNotReady if the request is issued before the resource controller completes
1.563 + its internal initialisation
1.564 + KErrUnderflow if the client has exceeded the reserved number of TPowerRequest
1.565 + and the TPowerRequest free pool is empty for long latency resource.
1.566 + KErrArgument if callback object is NULL.
1.567 +
1.568 +@pre Interrupts must be enabled
1.569 +@pre Kernel must be unlocked
1.570 +@pre No fast mutex can be held
1.571 +@pre Call in a thread context but not from null thread or DFC thread1
1.572 +@pre Can be used in a device driver
1.573 +*/
1.574 +EXPORT_C TInt PowerResourceManager::GetResourceState(TUint aClientId, TUint aResourceId, TBool aCached, TPowerResourceCb& aCb)
1.575 + {
1.576 + __KTRACE_OPT(KRESMANAGER, Kern::Printf(">PowerResourceManager::GetResourceState"));
1.577 + __KTRACE_OPT(KRESMANAGER, Kern::Printf("aClientId 0x%08x", aClientId));
1.578 + __KTRACE_OPT(KRESMANAGER, Kern::Printf("aResourceId 0x%08x", aResourceId));
1.579 + __KTRACE_OPT(KRESMANAGER, Kern::Printf("aCached 0x%08x", aCached));
1.580 + return TInterface::GetResourceState(aClientId, aResourceId, aCached, aCb);
1.581 + }
1.582 +
1.583 +/**
1.584 +@publishedPartner
1.585 +@prototype 9.5
1.586 +
1.587 +Cancel an asynchronous request(or its callback).
1.588 +
1.589 +@param aClientId ID of the client which is requesting the cancellation of the request.
1.590 +@param aResourceId ID for the resource which the request that is being cancelled operates
1.591 + upon.
1.592 +@param aCb A reference to the resource callback object specified with the request
1.593 + that is being cancelled.
1.594 +
1.595 +@return KErrCancel if the request was cancelled.
1.596 + KErrNotFound if this resource ID could not be found in the current list of
1.597 + controllable resources.
1.598 + KErrCompletion if request is no longer pending.
1.599 + KErrAccessDenied if the client ID could not be found in the current list of registered
1.600 + clients or if the client was registered to be thread relative and this API
1.601 + is not called from the same thread or if client is not the same that
1.602 + requested the resource state change.
1.603 + KErrInUse if the request cannot be cancelled as processing of the request already started
1.604 + and will run to completion.
1.605 +
1.606 +@pre Interrupts must be enabled
1.607 +@pre Kernel must be unlocked
1.608 +@pre No fast mutex can be held
1.609 +@pre Call in a thread context but not from null thread or DFC thread1
1.610 +@pre Can be used in a device driver
1.611 +*/
1.612 +EXPORT_C TInt PowerResourceManager::CancelAsyncRequestCallBack(TUint aClientId, TUint aResourceId, TPowerResourceCb& aCb)
1.613 + {
1.614 + __KTRACE_OPT(KRESMANAGER, Kern::Printf(">PowerResourceManager::CancelAsyncRequestCallback"));
1.615 + __KTRACE_OPT(KRESMANAGER, Kern::Printf("aClientId 0x%08x", aClientId));
1.616 + __KTRACE_OPT(KRESMANAGER, Kern::Printf("aResourceId 0x%08x", aResourceId));
1.617 + return TInterface::CancelAsyncRequestCallBack(aClientId, aResourceId, aCb);
1.618 + }
1.619 +
1.620 +/**
1.621 +@publishedPartner
1.622 +@prototype 9.5
1.623 +
1.624 +Request notification of changes to the state of a resource.
1.625 +
1.626 +NOTE: This API should return immediately; however the notification will
1.627 +only happen when a resource change occurs.Notification request is idempotent,
1.628 +if the same notification has already been requested for this resource ID,
1.629 +the API returns with no further action. Notifications remain queued until
1.630 +they are cancelled.
1.631 +
1.632 +@param aClientId ID of the client which is requesting the notification.
1.633 +@param aResourceId ID of the resource for which notification of state changes
1.634 + is being requested.
1.635 +@param aN A reference to a notification object which encapsulates a callback
1.636 + function to be called whenever a resource state change takes place.
1.637 + NOTE: The client must create the notification object in kernel heap
1.638 + or data section.
1.639 +
1.640 +@return KErrNone if the operation of requesting a notification was successful.
1.641 + KErrNotFound if this resource ID could not be found in the current list
1.642 + of controllable resources.
1.643 + KErrAccessDenied if the client ID could not be found in the current
1.644 + list of registered clients or if the client was registered to be thread
1.645 + relative and this API is not called from the same thread.
1.646 + KErrInUse if the passed notification object is used already.
1.647 +
1.648 +@pre Interrupts must be enabled
1.649 +@pre Kernel must be unlocked
1.650 +@pre No fast mutex can be held
1.651 +@pre Call in a thread context but not from null thread or DFC thread1
1.652 +@pre Can be used in a device driver
1.653 +*/
1.654 +EXPORT_C TInt PowerResourceManager::RequestNotification(TUint aClientId, TUint aResourceId, DPowerResourceNotification& aN)
1.655 + {
1.656 + __KTRACE_OPT(KRESMANAGER, Kern::Printf(">PowerResourceManager::RequestNotification"));
1.657 + __KTRACE_OPT(KRESMANAGER, Kern::Printf("aClientId 0x%08x", aClientId));
1.658 + __KTRACE_OPT(KRESMANAGER, Kern::Printf("aResourceId 0x%08x", aResourceId));
1.659 + return TInterface::RequestNotification(aClientId, aResourceId, aN);
1.660 + }
1.661 +
1.662 +/**
1.663 +@publishedPartner
1.664 +@prototype 9.5
1.665 +
1.666 +Request notification when the state of a resource reaches a specified threshold or
1.667 +goes above or below that threshold (for multilevel resource only) based on direction.
1.668 +In other words it is issued when a threshold on the specified resource state is crossed
1.669 +in the direction specified.
1.670 +
1.671 +NOTE:This API should return immediately; however the notification will only
1.672 +happen when a resource change occurs. Notification request is idempotent,
1.673 +if the same notification has already been requested for this resource ID,
1.674 +the API returns with no further action. Notification remain queued until
1.675 +they are cancelled.
1.676 +
1.677 +@param aClientId ID of the client which is requesting the notification.
1.678 +@param aResourceId ID for the resource whose notification of state changes is
1.679 + being requested.
1.680 +@param aN A reference to a notification object which encapsulates a callback
1.681 + function to be called whenever the conditions to issue the notification
1.682 + (specified in the API) are met.
1.683 + NOTE: The client must create the notification object in kernel heap
1.684 + or data section.
1.685 +@param aThreshold The level of the resource state that will trigger the notification
1.686 + when reached.
1.687 +@param aDirection Specifies the direction of change of the resource state that will
1.688 + trigger a notification. EFalse means the notification will be issued
1.689 + when the resource state change to a specified threshold value or below
1.690 + the specified threshold, ETrue means the notification will be issued
1.691 + when the resource state change to a specified threshold value or above
1.692 + the specified threshold.
1.693 +
1.694 +@return KErrNone if the operation of requesting a notification was successful.
1.695 + KErrNotFound if this resource ID could not be found in the current list
1.696 + of controllable reosurces.
1.697 + KErrAccessDenied if the client ID could not be found in the list of
1.698 + registered clients or if the client was registered to be
1.699 + thread relative and this API is not called from the same thread.
1.700 + KErrInUse if the passed notification object is used already.
1.701 + KErrArgument if the specified threshold is out of range.
1.702 +
1.703 +@pre Interrupts must be enabled
1.704 +@pre Kernel must be unlocked
1.705 +@pre No fast mutex can be held
1.706 +@pre Call in a thread context but not from null thread or DFC thread1
1.707 +@pre Can be used in a device driver
1.708 +*/
1.709 +EXPORT_C TInt PowerResourceManager::RequestNotification(TUint aClientId, TUint aResourceId, DPowerResourceNotification& aN,
1.710 + TInt aThreshold, TBool aDirection)
1.711 + {
1.712 + __KTRACE_OPT(KRESMANAGER, Kern::Printf(">PowerResourceManager::RequestNotification"));
1.713 + __KTRACE_OPT(KRESMANAGER, Kern::Printf("aClientId 0x%08x", aClientId));
1.714 + __KTRACE_OPT(KRESMANAGER, Kern::Printf("aResourceId 0x%08x", aResourceId));
1.715 + __KTRACE_OPT(KRESMANAGER, Kern::Printf("aThreshold 0x%08x", aThreshold));
1.716 + __KTRACE_OPT(KRESMANAGER, Kern::Printf("aDirection 0x%08x", aDirection));
1.717 + return TInterface::RequestNotification(aClientId, aResourceId, aN, aThreshold, aDirection);
1.718 + }
1.719 +
1.720 +/**
1.721 +@publishedPartner
1.722 +@prototype 9.5
1.723 +
1.724 +Cancel and remove from queue a previously issued request for notification on a
1.725 +resource state change.
1.726 +
1.727 +@param aClientId ID of the client which is requesting to cancel the notification
1.728 +@param aResourceId ID of the resource whose pending notification of state changes
1.729 + is being cancelled.
1.730 +@param aN A reference to the notification object that was associated with
1.731 + the notification request that is being cancelled. This will be
1.732 + used to identify the notification that is being cancelled.
1.733 +
1.734 +@return KErrCancel if the notification request was successfully cancelled.
1.735 + KErrNotFound if the specified notification object is not found in the current list
1.736 + of notification objects for the specified resource.
1.737 + KErrAccessDenied if the client requesting the cancellation is not the same
1.738 + which registered the notification or if the resource id does not
1.739 + match or if the client ID could not be found in the list of
1.740 + registered clients or if the client was registered to be
1.741 + thread relative and this API is not called from the same thread.
1.742 +
1.743 +@pre Interrupts must be enabled
1.744 +@pre Kernel must be unlocked
1.745 +@pre No fast mutex can be held
1.746 +@pre Call in a thread context but not from null thread or DFC thread1
1.747 +@pre Can be used in a device driver
1.748 +*/
1.749 +EXPORT_C TInt PowerResourceManager::CancelNotification(TUint aClientId, TUint aResourceId, DPowerResourceNotification& aN)
1.750 + {
1.751 + __KTRACE_OPT(KRESMANAGER, Kern::Printf(">PowerResourceManager::CancelNotification"));
1.752 + __KTRACE_OPT(KRESMANAGER, Kern::Printf("aClientId 0x%08x", aClientId));
1.753 + __KTRACE_OPT(KRESMANAGER, Kern::Printf("aResourceId 0x%08x", aResourceId));
1.754 + return TInterface::CancelNotification(aClientId, aResourceId, aN);
1.755 + }
1.756 +
1.757 +/**
1.758 +@publishedPartner
1.759 +@prototype 9.5
1.760 +
1.761 +Request pre-allocation of specified number of client level and request message objects.
1.762 +
1.763 +@param aClientId ID of the client which is requesting the pre-allocation.
1.764 +@param aNumCl Number of client level objects that needs to be pre-allocated
1.765 + for this client.
1.766 +@param aNumRm Number of request message objects that needs to be pre-allocated
1.767 + for this client.
1.768 +
1.769 +@return KErrNone if the allocation was successful
1.770 + KErrAccessDenied if the client ID could not be found in the list of
1.771 + registered clients or if the client was registered to be
1.772 + thread relative and this API is not called from the same thread.
1.773 + KErrNoMemory if there is no sufficient memory for allocation of requested
1.774 + number of objects.
1.775 +
1.776 +@pre Interrupts must be enabled
1.777 +@pre Kernel must be unlocked
1.778 +@pre No fast mutex can be held
1.779 +@pre Call in a thread context but not from null thread or DFC thread1
1.780 +@pre Can be used in a device driver
1.781 +*/
1.782 +EXPORT_C TInt PowerResourceManager::AllocReserve(TUint aClientId, TUint8 aNumCl, TUint8 aNumRm)
1.783 + {
1.784 + __KTRACE_OPT(KRESMANAGER, Kern::Printf(">PowerResourceManager::AllocReserve"));
1.785 + __KTRACE_OPT(KRESMANAGER, Kern::Printf("aClientId 0x%08x", aClientId));
1.786 + __KTRACE_OPT(KRESMANAGER, Kern::Printf("aNumCl 0x%02x", aNumCl));
1.787 + __KTRACE_OPT(KRESMANAGER, Kern::Printf("aNumRm 0x%02x", aNumRm));
1.788 + return TInterface::AllocReserve(aClientId, aNumCl, aNumRm);
1.789 + }
1.790 +
1.791 +/**
1.792 +@publishedPartner
1.793 +@prototype 9.5
1.794 +
1.795 +Request to deregister client level from the specified resource for the specified client.
1.796 +
1.797 +@param aClientId ID of the client which is requesting the deregistration of client level.
1.798 +@param aResourceId ID of the resource from which to remove the specified clients 'client level'.
1.799 +
1.800 +@return KErrNone if successful
1.801 + KErrAccessDenied if the client ID could not be found in the list of registered clients or
1.802 + if the client was registered to be thread relative and this API is not
1.803 + called from the same thread.
1.804 + KErrNotFound if the resource ID could not be found in the current list of controllable
1.805 + resources or if the client is not holding any level with the specified
1.806 + resource (no client level found for the specified client).
1.807 +
1.808 +@pre Interrupts must be enabled
1.809 +@pre Kernel must be unlocked
1.810 +@pre No fast mutex can be held
1.811 +@pre Call in a thread context but not from null thread or DFC thread1
1.812 +@pre Can be used in a device driver.
1.813 +*/
1.814 +EXPORT_C TInt PowerResourceManager::DeRegisterClientLevelFromResource(TUint aClientId, TUint aResourceId)
1.815 + {
1.816 + __KTRACE_OPT(KRESMANAGER, Kern::Printf(">PowerResourceManager::DeRegisterClientLevelFromResource"));
1.817 + __KTRACE_OPT(KRESMANAGER, Kern::Printf("aClientId 0x%08x", aClientId));
1.818 + __KTRACE_OPT(KRESMANAGER, Kern::Printf("aResourceId 0x%08x", aResourceId));
1.819 + return TInterface::DeRegisterClientLevelFromResource(aClientId, aResourceId);
1.820 + }
1.821 +
1.822 +/**
1.823 +@publishedPartner
1.824 +@prototype 9.5
1.825 +
1.826 +Interface to provide extended functionality.This provides support
1.827 +to register and deregister dynamic resources and handling of resource dependency, registering
1.828 +and deregistering resource dependency.
1.829 +This is not supported in basic version
1.830 +It is used for getting version (supported in both version).
1.831 +
1.832 +@pre Interrupts must be enabled
1.833 +@pre Kernel must be unlocked
1.834 +@pre No fast mutex can be held
1.835 +@pre Call in a thread context but not from null thread or DFC thread1
1.836 +@pre Can be used in a device driver.
1.837 +*/
1.838 +EXPORT_C TInt PowerResourceManager::ControlIO(TUint aClientId, TUint aFunction, TAny* aParam1, TAny* aParam2,
1.839 + TAny* aParam3)
1.840 + {
1.841 + __KTRACE_OPT(KRESMANAGER, Kern::Printf(">PowerResourceManager::ControlIO"));
1.842 + __KTRACE_OPT(KRESMANAGER, Kern::Printf("aClientId 0x%08x", aClientId));
1.843 + __KTRACE_OPT(KRESMANAGER, Kern::Printf("aFunction %d", aFunction));
1.844 + return TInterface::ControlIO(aClientId, aFunction, aParam1, aParam2, aParam3);
1.845 + }
1.846 +
1.847 +