Table of Contents
IContextHubClientCallback.aidl
IContextHubTransactionCallback.aidl
IContextHubService.aidl
import android.hardware.location.ContextHubInfo;
import android.hardware.location.ContextHubMessage;
import android.hardware.location.NanoApp;
import android.hardware.location.NanoAppBinary;
import android.hardware.location.NanoAppFilter;
import android.hardware.location.NanoAppInstanceInfo;
import android.hardware.location.IContextHubCallback;
import android.hardware.location.IContextHubClient;
import android.hardware.location.IContextHubClientCallback;
import android.hardware.location.IContextHubTransactionCallback;
system service: contexthub向外提供的接口
interface IContextHubService {
int registerCallback(in IContextHubCallback callback);
int[] getContextHubHandles();
ContextHubInfo getContextHubInfo(int contextHubHandle);
NanoAppInstanceInfo getNanoAppInstanceInfo(int nanoAppHandle);
int[] findNanoAppOnHub(int contextHubHandle, in NanoAppFilter filter);
int sendMessage(int contextHubHandle, int nanoAppHandle, in ContextHubMessage msg);
IContextHubClient createClient(in IContextHubClientCallback client, int contextHubId);
List<ContextHubInfo> getContextHubs();
void loadNanoAppOnHub(
int contextHubId, in IContextHubTransactionCallback transactionCallback,
in NanoAppBinary nanoAppBinary);
void unloadNanoAppFromHub(
int contextHubId, in IContextHubTransactionCallback transactionCallback,
long nanoAppId);
void enableNanoApp(
int contextHubId, in IContextHubTransactionCallback transactionCallback,
long nanoAppId);
void disableNanoApp(
int contextHubId, in IContextHubTransactionCallback transactionCallback,
long nanoAppId);
void queryNanoApps(int contextHubId, in IContextHubTransactionCallback transactionCallback);
}
IContextHubClient.aidl
IContextHubClient提供的接口是sendMessageToNanoApp 和IContextHubService的sendMessage有什么区别?
import android.hardware.location.NanoAppMessage
interface IContextHubClient {
// Sends a message to a nanoapp
int sendMessageToNanoApp(in NanoAppMessage message);
// Closes the connection with the Context Hub
void close();
}
class NanoAppMessage
/**
* A class describing messages send to or from nanoapps through the Context Hub Service.
*
* The basis of the class is in the IContextHub.hal ContextHubMsg definition.
*
* @hide
*/
private NanoAppMessage(
long nanoAppId, int messageType, byte[] messageBody, boolean broadcasted) {
mNanoAppId = nanoAppId;
mMessageType = messageType;
mMessageBody = messageBody;
mIsBroadcasted = broadcasted;
}
struct ContextHubMsg {//来着IContextHub.hal
uint64_t appName; // Intended recipient (appId)
uint16_t hostEndPoint; // identifier for the endpoint. (also see enum HostEndPoint)
uint32_t msgType; // Identifier for message
vec<uint8_t> msg; // Message body
};
IContextHubCallback.aidl
import android.hardware.location.ContextHubMessage;
oneway interface IContextHubCallback {
void onMessageReceipt(int hubId, int nanoAppId, in ContextHubMessage msg);
}
class ContextHubMessage
* @deprecated Use {@link android.hardware.location.NanoAppMessage} instead to send messages with
* {@link android.hardware.location.ContextHubClient#sendMessageToNanoApp(
* NanoAppMessage)} and receive messages with
* {@link android.hardware.location.ContextHubClientCallback#onMessageFromNanoApp(
* ContextHubClient, NanoAppMessage)}.
NanoAppMessage替代ContextHubMessage, 用ContextHubClient#sendMessageToNanoApp发送消息,在ContextHubClientCallback#onMessageFromNanoApp中处理返回的消息。
IContextHubClientCallback.aidl
/**
* An interface used by the Context Hub Service to invoke callbacks for lifecycle notifications of a
* Context Hub and nanoapps, as well as for nanoapp messaging.
*
* @hide
*/
oneway interface IContextHubClientCallback {
// Callback invoked when receiving a message from a nanoapp.
void onMessageFromNanoApp(in NanoAppMessage message);
// Callback invoked when the attached Context Hub has reset.
void onHubReset();
// Callback invoked when a nanoapp aborts at the attached Context Hub.
void onNanoAppAborted(long nanoAppId, int abortCode);
// Callback invoked when a nanoapp is loaded at the attached Context Hub.
void onNanoAppLoaded(long nanoAppId);
// Callback invoked when a nanoapp is unloaded from the attached Context Hub.
void onNanoAppUnloaded(long nanoAppId);
// Callback invoked when a nanoapp is enabled at the attached Context Hub.
void onNanoAppEnabled(long nanoAppId);
// Callback invoked when a nanoapp is disabled at the attached Context Hub.
void onNanoAppDisabled(long nanoAppId);
}
IContextHubTransactionCallback.aidl
/**
* An interface used by the Context Hub Service to invoke callbacks notifying the complete of a
* transaction. The callbacks are unique for each type of transaction, and the service is
* responsible for invoking the correct callback.
*
* @hide
*/
oneway interface IContextHubTransactionCallback {
// Callback to be invoked when a query request completes
void onQueryResponse(int result, in List<NanoAppState> nanoappList);
// Callback to be invoked when a non-query request completes
void onTransactionComplete(int result);
}
IContexthub.hal
/**
* The Context Hub HAL provides an interface to a separate low-power processing
* domain that has direct access to contextual information, such as sensors.
* Native applications that run within a context hub are known as nanoapps, and
* they execute within the Context Hub Runtime Environment (CHRE), which is
* standardized via the CHRE API, defined elsewhere.
*/
interface IContexthub {
/**
* Enumerate all available context hubs on the system.
*
* @return hubs list of hubs on this system.
*/
getHubs() generates (vec<ContextHub> hubs);
/**
* Register a callback for the HAL implementation to send asynchronous
* messages to the service from a context hub. There can be a maximum of
* one callback registered with the HAL. A call to this function when a
* callback has already been registered must override the previous
* registration.
*
* @param hubId identifier for the hub
* callback an implementation of the IContextHubCallbacks
*
* @return result OK on success
* BAD_VALUE if parameters are not sane
*
*/
registerCallback(uint32_t hubId, IContexthubCallback cb) generates (Result result);
/**
* Send a message to a hub
*
* @param hubId identifier for hub to send message to
* msg message to be sent
*
* @return result OK if successful, error code otherwise
* BAD_VALUE if parameters are not sane
* TRANSACTION_FAILED if message send failed
*/
sendMessageToHub(uint32_t hubId, ContextHubMsg msg)
generates (Result result);
/**
* Loads a nanoApp. After loading, the nanoApp's init method must be called.
* After the init method for nanoApp returns success, this must be indicated
* to the service by an asynchronous call to handleTxnResult.
*
* Loading a nanoapp must not take more than 30 seconds.
*
* Depending on the implementation, nanoApps loaded via this API may or may
* not persist across reboots of the hub. If they do persist, the
* implementation must initially place nanoApps in the disabled state upon a
* reboot, and not start them until a call is made to enableNanoApp(). In
* this case, the app must also be unloaded upon a factory reset of the
* device.
*
* @param hubId identifer of the contextHub
* appBinary contains the binary representation of the nanoApp, plus
* metadata
* transactionId transactionId for this call
*
* @return result OK if transation started
* BAD_VALUE if parameters are not sane
* TRANSACTION_PENDING if hub is busy with another
* load/unload transaction
* TRANSACTION_FAILED if load failed synchronously
*
*/
loadNanoApp(uint32_t hubId,
NanoAppBinary appBinary,
uint32_t transactionId)
generates (Result result);
/**
* Unloads a nanoApp. Before the unload, the apps deinit method is called.
* After this, success must be indicated to the service through an
* asynchronous call to handleTxnResult.
*
* Unloading a nanoapp must not take more than 5 seconds.
*
* @param hubId identifer of the contextHub
* appId appIdentifier returned by the HAL
* msg message to be sent
*
* @return result OK if transation started
* BAD_VALUE if parameters are not sane
* TRANSACTION_PENDING if hub is busy with another
* load/unload transaction
* TRANSACTION_FAILED if unload failed synchronously
*
*/
unloadNanoApp(uint32_t hubId, uint64_t appId, uint32_t transactionId)
generates (Result result);
/**
* Enables a nanoApp. The app's init method is called.
* After this, success must be indicated to the service through an
* asynchronous message.
*
* Enabling a nanoapp must not take more than 5 seconds.
*
* @param hubId identifer of the contextHub
* appId appIdentifier returned by the HAL
* msg message to be sent
*
* @return result OK if transation started
* BAD_VALUE if parameters are not sane
* TRANSACTION_PENDING if hub is busy with another
* load/unload transaction
* FAILED_TRANSACTION if load fails immediately
*
*/
enableNanoApp(uint32_t hubId, uint64_t appId, uint32_t transactionId)
generates (Result result);
/**
* Disables a nanoApp. The app's deinit method is called.
* After this, success must be indicated to the service through an
* asynchronous message.
*
* Disabling a nanoapp must not take more than 5 seconds.
*
* @param hubId identifer of the contextHub
* appId appIdentifier returned by the HAL
* msg message to be sent
*
* @return result OK if transation started
* BAD_VALUE if parameters are not sane
* TRANSACTION_PENDING if hub is busy with another
* load/unload transaction
* FAILED_TRANSACTION if load fails immediately
*
*/
disableNanoApp(uint32_t hubId, uint64_t appId, uint32_t transactionId)
generates (Result result);
/**
* Queries for Loaded apps on the hub
*
* @param hubId identifer of the contextHub
*
* @return apps all nanoApps on the hub.
* All nanoApps that can be modified by the service must
* be returned. A non-modifiable nanoapps must not be
* returned. A modifiable nanoApp is one that can be
* unloaded/disabled/enabled by the service.
*
*/
queryApps(uint32_t hubId) generates (Result result);
};
IContexthubCallback.hal
interface IContexthubCallback {
/**
* This callback is passed by the Contexthub service to the HAL
* implementation to allow the HAL to send asynchronous messages back
* to the service and registered clients of the ContextHub service.
*
* @params msg : message
*
*/
handleClientMsg(ContextHubMsg msg);
/**
* This callback is passed by the Contexthub service to the HAL
* implementation to allow the HAL to send the response for a
* transaction.
*
* @params txnId : transaction id whose result is being sent
* passed in by the service at start of transacation.
* result: result of transaction.
*
*/
handleTxnResult(uint32_t txnId, TransactionResult result);
/**
* This callback is passed by the Contexthub service to the HAL
* implementation to allow the HAL to send an asynchronous event
* to the ContextHub service.
*
* @params msg : message
*
*/
handleHubEvent(AsyncEventType evt);
/**
* This callback is passed by the Contexthub service to the HAL
* implementation to allow the HAL to send a notification to the service
* that a nanp-app has aborted.
* This method must be called when a nanoapp invokes chreAbort(...)).
*
* @params appId : app identifier
* : abortCode code passed by the nanoApp.
*
* Also see chreAbort(...)
*
*/
handleAppAbort(uint64_t appId, uint32_t abortCode);
/**
* This callback is passed by the Contexthub service to the HAL
* implementation to allow the HAL to send information about the
* currently loaded and active nanoapps on the hub.
*
* @params appInfo : vector of HubAppinfo structure for each nanoApp
* on the hub that can be enabled, disabled and
* unloaded by the service. Any nanoApps that cannot
* be controlled by the service must not be reported.
* All nanoApps that can be controlled by the service
* must be reported.
*/
handleAppsInfo(vec<HubAppInfo> appInfo);
};
types.hal
enum Result : uint32_t {
OK, // Success
UNKNOWN_FAILURE, // Failure, unknown reason
BAD_PARAMS, // Parameters not sane
NOT_INIT, // Not initialized
TRANSACTION_FAILED, // Transaction failed
TRANSACTION_PENDING, // Pending transaction, cannot accept a new request
};
enum NanoAppFlags : uint32_t {
SIGNED = 1 << 0,
ENCRYPTED = 1 << 1,
};
struct NanoAppBinary {
uint64_t appId; // Nanoapp identifier
uint32_t appVersion; // Version of the app (semantics defined by app)
bitfield<NanoAppFlags> flags;
// The version of the CHRE API that this nanoApp was compiled against. See
// the CHRE API header file chre/version.h for more information. The hub
// implementation must use this to confirm compatibility before loading
// this nanoApp.
uint8_t targetChreApiMajorVersion;
uint8_t targetChreApiMinorVersion;
// Implementation-specific binary nanoapp data. This does not include the
// common nanoapp header that contains the app ID, etc., as this data is
// explicitly passed through the other fields in this struct.
vec<uint8_t> customBinary;
};
enum SensorType : uint32_t {
RESERVED,
ACCELEROMETER,
GYROSCOPE,
MAGNETOMETER,
BAROMETER,
PROXIMITY_SENSOR,
AMBIENT_LIGHT_SENSOR,
STATIONARY_DETECT,
INSTANT_MOTION_DETECT,
GPS = 0x100,
// Reserving this space for variants on GPS
WIFI = 0x200,
// Reserving this space for variants on WIFI
AUDIO = 0x300,
// Reserving this space for variants on Audio
CAMERA = 0x400,
// Reserving this space for variants on Camera
BLE = 0x500,
// Reserving this space for variants on Bluetooth Low Energy
WWAN = 0x600,
// Reserving this space for variants on WWAN
PRIVATE_SENSOR_BASE = 0x10000,
// Sensor types beyond PRIVATE_SENSOR_BASE are custom types
};
struct PhysicalSensor{
SensorType sensorType; // From the definitions above eg: 100
string type; // Type as a string. eg: "GPS"
string name; // Identifier eg: "Bosch BMI160"
string vendor; // Vendor : eg "STM"
uint32_t version; // Version : eg 0x1001
uint32_t fifoReservedCount; // Batching possible in hardware. Please
// note that here hardware does not include
// the context hub itself. Thus, this
// definition may be different from say the
// number advertised in the sensors HAL
// which allows for batching in a hub.
uint32_t fifoMaxCount; // Maximum number of batchable events.
uint64_t minDelayMs; // In milliseconds, corresponding to highest
// sampling freq.
uint64_t maxDelayMs; // In milliseconds, corresponds to minimum
// sampling frequency
float peakPowerMw; // At max frequency & no batching, power
// in milliwatts
};
struct ContextHub {
string name; // Descriptive name eg: "Awesome Hub #1"
string vendor; // Hub hardware vendor eg: "Qualcomm"
string toolchain; // Toolchain to make binaries eg: "gcc ARM"
uint32_t platformVersion; // Version of the hardware : eg 0x20
uint32_t toolchainVersion; // Version of the toolchain : eg: 0x484
uint32_t hubId; // A device unique ID for this hub
float peakMips; // Peak MIPS platform can deliver
float stoppedPowerDrawMw; // If stopped, retention power, milliwatts
float sleepPowerDrawMw; // If sleeping, retention power, milliwatts
float peakPowerDrawMw; // For a busy CPU, power in milliwatts
vec<PhysicalSensor> connectedSensors; // Array of connected sensors
uint32_t maxSupportedMsgLen;// This is the maximum size of the message that can
// be sent to the hub in one chunk (in bytes)
// Machine-readable CHRE platform ID, returned to nanoapps in the CHRE API
// function call chreGetPlatformId(). This field pairs with
// chreApiMajorVersion, chreApiMinorVersion, and chrePatchVersion to fully
// specify the CHRE implementation version. See also the CHRE API header
// file chre/version.h.
uint64_t chrePlatformId;
// The version of the CHRE implementation returned to nanoApps in the CHRE
// API function call chreGetVersion(). The major and minor version specify
// the implemented version of the CHRE API, while the patch version
// describes the implementation version within the scope of the platform
// ID. See also the CHRE API header file chre/version.h.
uint8_t chreApiMajorVersion;
uint8_t chreApiMinorVersion;
uint16_t chrePatchVersion;
};
enum HostEndPoint : uint16_t {
BROADCAST = 0xFFFF, // The message endpoint is a broadcast end point.
// This value must never be used for a message from
// the host to the hub.
// If BROADCAST is specified as a destination for a
// message from the context hub to the ContextHub
// service, the message must be broadcast to all
// registered clients by the Context Hub service.
UNSPECIFIED = 0xFFFE, // The message endpoint is unspecified. This value
// must not be used for messages from the hub to host.
// This value may be used for messages from the host
// to the hub.
};
struct ContextHubMsg {
uint64_t appName; // Intended recipient (appId)
uint16_t hostEndPoint; // identifier for the endpoint. (also see enum HostEndPoint)
uint32_t msgType; // Identifier for message
vec<uint8_t> msg; // Message body
};
enum HubMemoryType : uint32_t {
MAIN = 0, // Main memory
SECONDARY = 1, // Secondary memory
TCM = 2, // Tightly coupled memory
};
enum HubMemoryFlag : uint32_t {
READ = 1 << 0, // Readable
WRITE = 1 << 1, // Writable
EXEC = 1 << 2, // Executable
};
struct MemRange {
uint32_t totalBytes; // Total capacity in bytes
uint32_t freeBytes; // Free capacity in bytes
HubMemoryType type; // Type of memory, see HubMemoryType
bitfield<HubMemoryFlag> flags;
};
enum AsyncEventType : uint32_t {
RESTARTED = 1, // Hub restarted unexpectedly
};
enum TransactionResult : int32_t {
SUCCESS, // Successful completion of transaction
FAILURE, // Failed transaction
};
struct HubAppInfo {
uint64_t appId; // Identifier of the app
uint32_t version; // Version of the app
vec<MemRange> memUsage; // Memory used by this app
bool enabled; // true if the app is currently enabled and running,
// or false if in the loaded but disabled state
};