Telematics SDK - API Reference
v1.64.0
|
Data Structures | |
class | telux::power::PowerFactory |
PowerFactory allows creation of TCU-activity manager instance. More... | |
struct | telux::power::ClientInstanceConfig |
class | telux::power::ITcuActivityListener |
Listener class for getting notifications related to TCU-activity state and also the updates related to TCU-activity service status. The client needs to implement these methods as briefly as possible and avoid blocking calls in it. The methods in this class can be invoked from multiple different threads. Client needs to make sure that the implementation is thread-safe. More... | |
class | telux::power::ITcuActivityManager |
ITcuActivityManager provides interface to register and de-register listeners to get TCU-activity state updates. And also API to initiate TCU-activity state transition. More... | |
Typedefs | |
typedef std::pair< std::string, std::string > | telux::power::ClientInfo |
Variables | |
static const std::string | telux::power::ALL_MACHINES = "ALL_MACHINES" |
static const std::string | telux::power::LOCAL_MACHINE = "LOCAL_MACHINE" |
This section contains APIs related to TCU activity state management.
class telux::power::PowerFactory |
PowerFactory allows creation of TCU-activity manager instance.
Public Member Functions | |
virtual std::shared_ptr< ITcuActivityManager > | getTcuActivityManager (ClientInstanceConfig config, telux::common::InitResponseCb callback=nullptr)=0 |
virtual std::shared_ptr< ITcuActivityManager > | getTcuActivityManager (ClientType clientType=ClientType::SLAVE, common::ProcType procType=common::ProcType::LOCAL_PROC, telux::common::InitResponseCb callback=nullptr)=0 |
Static Public Member Functions | |
static PowerFactory & | getInstance () |
|
static |
API to get the factory instance for TCU-activity management
|
pure virtual |
Gets the TCU-activity manager instance.
[in] | config | TCU-activity manager configuration |
[in] | callback | Optional callback pointer to get the response of the manager initialization. |
|
pure virtual |
Gets the TCU-activity manager instance.
[in] | clientType | Type of the client that is going to access ITcuActivityManager APIs ClientType |
[in] | procType | Required processor type on which the operations will be performed telux::common::ProcType telux::common::ProcType::REMOTE_PROC is not supported |
[in] | callback | Optional callback pointer to get the response of the manager initialization. |
struct telux::power::ClientInstanceConfig |
TCU-activity Manager configuration
Data Fields | ||
---|---|---|
ClientType | clientType |
Type of the client that is going to access ITcuActivityManager APIs ClientType. There will be a single ClientType::MASTER across all available machines. |
string | clientName |
Identifies the client that is retrieving an instance of the TcuActivityManager. This is a mandatory field and it needs to be unique across all TcuActivityManager clients across all machines in the system. To make it unique, one example could be machineName_ProcessName_ProcessId. This field will be used to provide a list of client names to the master via ITcuActivityListener::onSlaveAckStatusUpdate in case any slave client does not acknowledge or provide a nack via ITcuActivityManager::sendActivityStateAck for state transition triggered by the master via ITcuActivityManager::setActivityState |
string | machineName |
This field is unnecessary for clients of type ClientType::MASTER. For clients of type ClientType::SLAVE this field specifies whether the slave is interested in the power state transition of all machines or only the machine where the slave is running. For interest in all machines, this field should be assigned ALL_MACHINES and for local machine assign LOCAL_MACHINE. For slaves, if this field is not provided, then the local machine name will be used as the default. |
class telux::power::ITcuActivityListener |
Listener class for getting notifications related to TCU-activity state and also the updates related to TCU-activity service status. The client needs to implement these methods as briefly as possible and avoid blocking calls in it. The methods in this class can be invoked from multiple different threads. Client needs to make sure that the implementation is thread-safe.
Public Member Functions | |
virtual void | onTcuActivityStateUpdate (TcuActivityState state, std::string machineName) |
virtual void | onSlaveAckStatusUpdate (const telux::common::Status status, const std::string machineName, const std::vector< ClientInfo > unresponsiveClients, const std::vector< ClientInfo > nackResponseClients) |
virtual void | onMachineUpdate (const std::string machineName, const MachineEvent machineEvent) |
virtual void | onSlaveAckStatusUpdate (telux::common::Status status) |
virtual void | onTcuActivityStateUpdate (TcuActivityState state) |
virtual | ~ITcuActivityListener () |
|
virtual |
Destructor of ITcuActivityListener
|
virtual |
This function is called when the TCU activity state of the machine(that the client is registered for) is going to change. When the master triggers state change of a machine using ITcuActivityManager::setActivityState, the slave clients interested in that machine will receive this notification. This notification will not be received by the Master. State change of ALL_MACHINES via ITcuActivityManager::setActivityState could lead to an individual machine's state change, resulting in a notification to clients of all machines. Slave clients who got this indication must acknowledge it with ITcuActivityManager::sendActivityStateAck.
[in] | state | TCU-activity state that the machine is about to enter |
[in] | machineName | Machine name that is undergoing the state change. Assigned ALL_MACHINES for a global state change and LOCAL_MACHINE for a local state change. |
|
virtual |
Informs the master with the consolidated acknowledgement from all slave clients for the state change previously triggered by the master client.
This API will be invoked only for the MASTER client.
On platforms with access control enabled, the client needs to have TELUX_POWER_CONTROL_STATE permission for this listener API to be invoked.
[in] | status | This is the status of acknowledgements corresponding to a particular request. If any slave doesn't acknowledge within the configured timeout, then Status::EXPIRED is reported. If any slave sends a negative acknowledgement, then Status::NOTREADY is reported. If both types of acknowledgement errors exist, then the status code corresponding to most number of clients is reported. |
[in] | machineName | Machine name that is undergoing the state change. Assigned ALL_MACHINES for a global state change and LOCAL_MACHINE for a local state change. |
[in] | unresponsiveClients | List of client and respective machine names that have not responded via sendActivityStateAck for state transitions of suspend or shutdown triggered by the master via ITcuActivityManager::setActivityState. |
[in] | nackResponseClients | List of client and respective machine name who responded with TcuActivityStateChangeResponse::NACK for state transitions of suspend or shutdown triggered by the master via ITcuActivityManager::setActivityState. |
|
virtual |
This API will be invoked if any machine availability changes with respect to power management.
User can use ITcuActivityManager::getAllMachineNames() to get all updated available machines. It will be useful for the master client if they are interested in setting the TCUActivityState of a specific machine ITcuActivityManager::setActivityState().
This API is meant for clients that have instantiated the ITcuActivityManager instance using ClientType::MASTER
[in] | machineName | Name of the machine |
[in] | machineEvent | Machine event ( MachineEvent) |
|
virtual |
This function is called with the overall acknowledgement status from all the SLAVE clients, for state change triggered previously by MASTER client.
This API will be invoked only for the MASTER client. If at least one SLAVE client does not acknowledge within the configured timeout, then Status::EXPIRED would be reported.
On platforms with Access control enabled, the client needs to have TELUX_POWER_CONTROL_STATE permission for this listener API to be invoked.
[in] | status | Status of the SLAVE clients' acknowledgements |
|
virtual |
This function is called when the TCU-activity state is going to change.
[in] | state | TCU-activity state that system is about to enter |
class telux::power::ITcuActivityManager |
ITcuActivityManager provides interface to register and de-register listeners to get TCU-activity state updates. And also API to initiate TCU-activity state transition.
An application can get the appropriate TCU-activity manager (i.e. ClientType::SLAVE or ClientType::MASTER) object from the power factory. The TCU-activity manager configured as the ClientType::MASTER is responsible for triggering state transitions. TCU-activity manager configured as a ClientType::SLAVE is responsible for listening to state change indications and acknowledging when it performs necessary tasks and prepares for the state transition. A machine in this power management framework represents an application processor subsystem or a host/guest virtual machine on hypervisor based platforms.
When the application is notified about the service being unavailable, the TCU-activity state notifications will be inactive. After the service becomes available, the existing listener registrations will be maintained.
|
virtual |
Destructor of ITcuActivityManager
|
pure virtual |
This status indicates whether the ITcuActivityManager object is in a usable state.
|
pure virtual |
Register a listener for updates on TCU-activity state changes.
[in] | listener | Pointer of ITcuActivityListener object that processes the notification |
|
pure virtual |
Remove a previously registered listener.
[in] | listener | Previously registered ITcuActivityListener that needs to be removed |
|
pure virtual |
Register a listener for updates on TCU-activity management service status.
[in] | listener | Pointer of IServiceStatusListener object that processes the notification |
|
pure virtual |
Remove a previously registered listener for service status updates.
[in] | listener | Previously registered IServiceStatusListener that needs to be removed |
|
pure virtual |
This API allows the caller to get the machine name where the client is running. It is intended to identify the local machine name on a platform where multiple machines are available in the power framework.
[out] | machineName | Machine name where the process is running |
|
pure virtual |
Enumerates all machines in the system that are available and ready to be managed by the power framework.
This API is meant for clients that have instantiated the ITcuActivityManager instance using ClientType::MASTER. If the platform has multiple machines available, knowing their names will be useful if the master is interested in individually modifying the activity state of any available machine using setActivityState.
[out] | machineNames | List of machine names that are available for power management. |
|
pure virtual |
Initiates a TCU-activity state transition.
This API also initiates the relevant internal operation if the platform is configured to change the modem activity state automatically when the TCU activity state changes.
This API needs to be used cautiously, as it could change the power-state of the system and may affect other processes. For example, if a master sets the SUSPEND state, all SLAVE processes will suspend their activity, allowing the system to suspend.
This API can only be invoked by clients that have instantiated the ITcuActivityManager instance using ClientType::MASTER.
Based on the final acknowledgements from all the slaves ITcuActivityListener::onSlaveAckStatusUpdate,
On platforms with Access control enabled, Caller needs to have TELUX_POWER_CONTROL_STATE permission to invoke this API successfully.
[in] | state | TCU-activity state that the system is intended to enter |
[in] | machineName | Machine name if the state transition is intended for the specific machine only. If assigned to ALL_MACHINES, then the state applies to the whole system. |
[in] | callback | Optional callback to get the response for the TCU-activity state transition command |
|
pure virtual |
Get the current TCU-activity state.
|
pure virtual |
Sends the acknowledgement after processing a TCU-activity state notification. This indicates that the client is prepared for the state transition. Only one acknowledgement should be sent per ClientType::SLAVE instance of ITcuActivityManager, even if multiple listeners are registered with that instance.
All slave clients that received a state change notification via TcuActivityListener::onTcuActivityStateUpdate must acknowledge using this API.
[in] | ack | Acknowledgement for a TCU-activity state notification StateChangeResponse. |
[in] | state | Represents the TCU activity state transition event corresponding to this acknowledgement. |
|
pure virtual |
Explicitly sets the modem state change.
The platform could be configured to automatically manage the modem state when setTcuActivityState is called. For example, when suspend is called, the implementation will also set the modem to suspend. In that case, this API need not be invoked after setting the TCU state.
This API needs to be used cautiously, as it could affect WWAN functionalities.
This API is meant for clients that have instantiated the ITcuActivityManager instance using ClientType::MASTER
On platforms with Access control enabled, Caller needs to have TELUX_POWER_CONTROL_STATE permission to invoke this API successfully.
[in] | state | Activity state that the modem is intended to enter TcuActivityState SUSPEND - Reduce/Throttle the modem activities RESUME - Restore the activities that were throttled earlier Any other input is considered invalid. |
|
pure virtual |
Checks the status of TCU-activity services, if other APIs are ready for use, and returns the results.
|
pure virtual |
Waits for TCU-activity services to be ready.
|
pure virtual |
Initiates a TCU-activity state transition. If platform is configured to change modem activity state automatically when TCU activity state is changed, this API initiates the relevant internal operation.
This API needs to be used cautiously, as it could change the power-state of the system and may affect other processes.
This API should only be invoked by a client that has instantiated the ITcuActivityManager instance using ClientType::MASTER
On platforms with access control enabled, the caller needs to have TELUX_POWER_CONTROL_STATE permission to invoke this API successfully.
[in] | state | TCU-activity state that the system is intended to enter |
[in] | callback | Optional callback to get the response for the TCU-activity state transition command |
|
pure virtual |
Sends acknowledgement after processing a TCU activity state notification. This indicates that the client is prepared for state transition. Only one acknowledgement is expected from a single client process, although it may have multiple listeners.
All slave clients that received a state change notification via TcuActivityListener::onTcuActivityStateUpdate must acknowledge using this API.
[in] | ack | Acknowledgement for a TCU-activity state notification. |
typedef std::pair<std::string, std::string> telux::power::ClientInfo |
Client information includes the client's name and the machine name on which the client is registered. Client name is the first item in the pair, followed by machine name.
|
strong |
|
strong |
Defines the acknowledgements to TCU-activity state transition. The client process sends this response via ITcuActivityManager::sendActivityStateAck after processing the TCU-activity state change notification received via ITcuActivityListener::onTcuActivityStateUpdate.
The framework does not require slave clients to respond when changing the state to TcuActivityState::RESUME.
Enumerator | |
---|---|
ACK |
Processed TCU-activity state change |
NACK |
Not prepared/ready for TCU-activity state change |
|
strong |
Defines the type of client that would be using the ITcuActivityManager APIs. Client that just needs the TcuActivityState notifications needs to choose ClientType::SLAVE. And the client that determines the TcuActivityState would choose ClientType::MASTER. Only a Master client can set the TcuActivityState. In a system, there should be a single Master client.
The ClientType needs to be chosen while instantiating the ITcuActivityManager, using the API PowerFactory::getTcuActivityManager
Enumerator | |
---|---|
SLAVE |
Client is a slave and interested in state change notification |
MASTER |
Client makes the decision on when the TcuActivityState should change |
|
strong |
Defines the type of event with respect to machine availability. This only represents the availability of the machine to manage its activity state and not whether the machine itself is enabled.
ITcuActivityListener::onMachineUpdate() can be used to listen to changes in machine availability.
Enumerator | |
---|---|
AVAILABLE |
New machine available for power management |
UNAVAILABLE |
machine unavailable for power management |
|
strong |
Defines the acknowledgements to TCU-activity states. The client process sends this after processing the TcuActivityState notification, indicating that it is prepared for state transition
Acknowledgement for TcuActivityState::RESUME is not required, as the state transition has already happened.
Enumerator | |
---|---|
SUSPEND_ACK |
processed TcuActivityState::SUSPEND notification |
SHUTDOWN_ACK |
processed TcuActivityState::SHUTDOWN notification |
|
static |
This special name represents all the machines on the platform. A client could specify this name when using ClientInstanceConfig::machineName to mean all machines as opposed to a specific machine name.
|
static |
This special name represents the machine name where the process is running. A client could specify this name when using ClientInstanceConfig::machineName to mean local machine's name. "LOCAL_MACHINE" in case of a hypervisor environment specifies that the client is interested in the virtual machine the client is running on.