Merge changes from topic "ch_hal_v4" into main

* changes:
  Update contexhub stub impl to V4
  Introduce new endpoint lifecycle interfaces for ContextHub v4
  Introduce new interfaces for ContextHub v4
This commit is contained in:
Treehugger Robot
2024-11-07 03:15:18 +00:00
committed by Gerrit Code Review
25 changed files with 1153 additions and 10 deletions

View File

@@ -194,7 +194,7 @@
</hal>
<hal format="aidl">
<name>android.hardware.contexthub</name>
<version>3</version>
<version>3-4</version>
<interface>
<name>IContextHub</name>
<instance>default</instance>

View File

@@ -52,8 +52,6 @@ aidl_interface {
version: "3",
imports: [],
},
],
frozen: true,
frozen: false,
}

View File

@@ -0,0 +1,41 @@
/*
* Copyright (C) 2024 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
///////////////////////////////////////////////////////////////////////////////
// THIS FILE IS IMMUTABLE. DO NOT EDIT IN ANY CASE. //
///////////////////////////////////////////////////////////////////////////////
// This file is a snapshot of an AIDL file. Do not edit it manually. There are
// two cases:
// 1). this is a frozen version file - do not edit this in any case.
// 2). this is a 'current' file. If you make a backwards compatible change to
// the interface (from the latest frozen version), the build system will
// prompt you to update this file with `m <name>-update-api`.
//
// You must not make a backward incompatible change to any AIDL file built
// with the aidl_interface module type with versions property set. The module
// type is used to build AIDL files in a way that they can be used across
// independently updatable components of the system. If a device is shipped
// with such a backward incompatible change, it has a high risk of breaking
// later when a module using the interface is updated, e.g., Mainline modules.
package android.hardware.contexthub;
@VintfStability
parcelable EndpointId {
long id;
long hubId;
const long ENDPOINT_ID_INVALID = 0;
const long ENDPOINT_ID_RESERVED = (-1) /* -1 */;
}

View File

@@ -0,0 +1,52 @@
/*
* Copyright (C) 2024 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
///////////////////////////////////////////////////////////////////////////////
// THIS FILE IS IMMUTABLE. DO NOT EDIT IN ANY CASE. //
///////////////////////////////////////////////////////////////////////////////
// This file is a snapshot of an AIDL file. Do not edit it manually. There are
// two cases:
// 1). this is a frozen version file - do not edit this in any case.
// 2). this is a 'current' file. If you make a backwards compatible change to
// the interface (from the latest frozen version), the build system will
// prompt you to update this file with `m <name>-update-api`.
//
// You must not make a backward incompatible change to any AIDL file built
// with the aidl_interface module type with versions property set. The module
// type is used to build AIDL files in a way that they can be used across
// independently updatable components of the system. If a device is shipped
// with such a backward incompatible change, it has a high risk of breaking
// later when a module using the interface is updated, e.g., Mainline modules.
package android.hardware.contexthub;
@VintfStability
parcelable EndpointInfo {
android.hardware.contexthub.EndpointId id;
android.hardware.contexthub.EndpointInfo.EndpointType type;
String name;
int version;
@nullable String tag;
String[] requiredPermissions;
android.hardware.contexthub.Service[] services;
@Backing(type="int") @VintfStability
enum EndpointType {
FRAMEWORK = 1,
APP = 2,
NATIVE = 3,
NANOAPP = 4,
GENERIC = 5,
}
}

View File

@@ -0,0 +1,45 @@
/*
* Copyright (C) 2024 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
///////////////////////////////////////////////////////////////////////////////
// THIS FILE IS IMMUTABLE. DO NOT EDIT IN ANY CASE. //
///////////////////////////////////////////////////////////////////////////////
// This file is a snapshot of an AIDL file. Do not edit it manually. There are
// two cases:
// 1). this is a frozen version file - do not edit this in any case.
// 2). this is a 'current' file. If you make a backwards compatible change to
// the interface (from the latest frozen version), the build system will
// prompt you to update this file with `m <name>-update-api`.
//
// You must not make a backward incompatible change to any AIDL file built
// with the aidl_interface module type with versions property set. The module
// type is used to build AIDL files in a way that they can be used across
// independently updatable components of the system. If a device is shipped
// with such a backward incompatible change, it has a high risk of breaking
// later when a module using the interface is updated, e.g., Mainline modules.
package android.hardware.contexthub;
@VintfStability
parcelable HubInfo {
long hubId;
android.hardware.contexthub.HubInfo.HubDetails hubDetails;
const long HUB_ID_INVALID = 0;
const long HUB_ID_RESERVED = (-1) /* -1 */;
union HubDetails {
android.hardware.contexthub.ContextHubInfo contextHubInfo;
android.hardware.contexthub.VendorHubInfo vendorHubInfo;
}
}

View File

@@ -49,5 +49,16 @@ interface IContextHub {
void onNanSessionStateChanged(in android.hardware.contexthub.NanSessionStateUpdate update);
void setTestMode(in boolean enable);
void sendMessageDeliveryStatusToHub(in int contextHubId, in android.hardware.contexthub.MessageDeliveryStatus messageDeliveryStatus);
List<android.hardware.contexthub.HubInfo> getHubs();
List<android.hardware.contexthub.EndpointInfo> getEndpoints();
void registerEndpoint(in android.hardware.contexthub.EndpointInfo endpoint);
void unregisterEndpoint(in android.hardware.contexthub.EndpointInfo endpoint);
void registerEndpointCallback(in android.hardware.contexthub.IEndpointCallback callback);
int[] requestSessionIdRange(int size);
void openEndpointSession(int sessionId, in android.hardware.contexthub.EndpointId destination, in android.hardware.contexthub.EndpointId initiator, in @nullable String serviceDescriptor);
void sendMessageToEndpoint(int sessionId, in android.hardware.contexthub.Message msg);
void sendMessageDeliveryStatusToEndpoint(int sessionId, in android.hardware.contexthub.MessageDeliveryStatus msgStatus);
void closeEndpointSession(int sessionId, in android.hardware.contexthub.Reason reason);
void endpointSessionOpenComplete(int sessionId);
const int EX_CONTEXT_HUB_UNSPECIFIED = (-1) /* -1 */;
}

View File

@@ -0,0 +1,44 @@
/*
* Copyright (C) 2024 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
///////////////////////////////////////////////////////////////////////////////
// THIS FILE IS IMMUTABLE. DO NOT EDIT IN ANY CASE. //
///////////////////////////////////////////////////////////////////////////////
// This file is a snapshot of an AIDL file. Do not edit it manually. There are
// two cases:
// 1). this is a frozen version file - do not edit this in any case.
// 2). this is a 'current' file. If you make a backwards compatible change to
// the interface (from the latest frozen version), the build system will
// prompt you to update this file with `m <name>-update-api`.
//
// You must not make a backward incompatible change to any AIDL file built
// with the aidl_interface module type with versions property set. The module
// type is used to build AIDL files in a way that they can be used across
// independently updatable components of the system. If a device is shipped
// with such a backward incompatible change, it has a high risk of breaking
// later when a module using the interface is updated, e.g., Mainline modules.
package android.hardware.contexthub;
@VintfStability
interface IEndpointCallback {
void onEndpointStarted(in android.hardware.contexthub.EndpointInfo[] endpointInfos);
void onEndpointStopped(in android.hardware.contexthub.EndpointId[] endpointIds, android.hardware.contexthub.Reason reason);
void onMessageReceived(int sessionId, in android.hardware.contexthub.Message msg);
void onMessageDeliveryStatusReceived(int sessionId, in android.hardware.contexthub.MessageDeliveryStatus msgStatus);
void onEndpointSessionOpenRequest(int sessionId, in android.hardware.contexthub.EndpointId destination, in android.hardware.contexthub.EndpointId initiator, in @nullable String serviceDescriptor);
void onCloseEndpointSession(int sessionId, in android.hardware.contexthub.Reason reason);
void onEndpointSessionOpenComplete(int sessionId);
}

View File

@@ -0,0 +1,43 @@
/*
* Copyright (C) 2024 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
///////////////////////////////////////////////////////////////////////////////
// THIS FILE IS IMMUTABLE. DO NOT EDIT IN ANY CASE. //
///////////////////////////////////////////////////////////////////////////////
// This file is a snapshot of an AIDL file. Do not edit it manually. There are
// two cases:
// 1). this is a frozen version file - do not edit this in any case.
// 2). this is a 'current' file. If you make a backwards compatible change to
// the interface (from the latest frozen version), the build system will
// prompt you to update this file with `m <name>-update-api`.
//
// You must not make a backward incompatible change to any AIDL file built
// with the aidl_interface module type with versions property set. The module
// type is used to build AIDL files in a way that they can be used across
// independently updatable components of the system. If a device is shipped
// with such a backward incompatible change, it has a high risk of breaking
// later when a module using the interface is updated, e.g., Mainline modules.
package android.hardware.contexthub;
@VintfStability
parcelable Message {
int flags;
int sequenceNumber;
String[] permissions;
int type;
byte[] content;
const int FLAG_REQUIRES_DELIVERY_STATUS = 1;
}

View File

@@ -0,0 +1,46 @@
/*
* Copyright (C) 2023 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
///////////////////////////////////////////////////////////////////////////////
// THIS FILE IS IMMUTABLE. DO NOT EDIT IN ANY CASE. //
///////////////////////////////////////////////////////////////////////////////
// This file is a snapshot of an AIDL file. Do not edit it manually. There are
// two cases:
// 1). this is a frozen version file - do not edit this in any case.
// 2). this is a 'current' file. If you make a backwards compatible change to
// the interface (from the latest frozen version), the build system will
// prompt you to update this file with `m <name>-update-api`.
//
// You must not make a backward incompatible change to any AIDL file built
// with the aidl_interface module type with versions property set. The module
// type is used to build AIDL files in a way that they can be used across
// independently updatable components of the system. If a device is shipped
// with such a backward incompatible change, it has a high risk of breaking
// later when a module using the interface is updated, e.g., Mainline modules.
package android.hardware.contexthub;
@Backing(type="byte") @VintfStability
enum Reason {
UNSPECIFIED = 0,
OUT_OF_MEMORY,
TIMEOUT,
OPEN_ENDPOINT_SESSION_REQUEST_REJECTED,
CLOSE_ENDPOINT_SESSION_REQUESTED,
ENDPOINT_INVALID,
ENDPOINT_GONE,
ENDPOINT_CRASHED,
HUB_RESET,
}

View File

@@ -0,0 +1,48 @@
/*
* Copyright (C) 2024 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
///////////////////////////////////////////////////////////////////////////////
// THIS FILE IS IMMUTABLE. DO NOT EDIT IN ANY CASE. //
///////////////////////////////////////////////////////////////////////////////
// This file is a snapshot of an AIDL file. Do not edit it manually. There are
// two cases:
// 1). this is a frozen version file - do not edit this in any case.
// 2). this is a 'current' file. If you make a backwards compatible change to
// the interface (from the latest frozen version), the build system will
// prompt you to update this file with `m <name>-update-api`.
//
// You must not make a backward incompatible change to any AIDL file built
// with the aidl_interface module type with versions property set. The module
// type is used to build AIDL files in a way that they can be used across
// independently updatable components of the system. If a device is shipped
// with such a backward incompatible change, it has a high risk of breaking
// later when a module using the interface is updated, e.g., Mainline modules.
package android.hardware.contexthub;
@VintfStability
parcelable Service {
android.hardware.contexthub.Service.RpcFormat format;
String serviceDescriptor;
int majorVersion;
int minorVersion;
ParcelableHolder extendedInfo;
@Backing(type="int") @VintfStability
enum RpcFormat {
CUSTOM = 0,
AIDL = 1,
PW_RPC_PROTOBUF = 2,
}
}

View File

@@ -0,0 +1,40 @@
/*
* Copyright (C) 2024 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
///////////////////////////////////////////////////////////////////////////////
// THIS FILE IS IMMUTABLE. DO NOT EDIT IN ANY CASE. //
///////////////////////////////////////////////////////////////////////////////
// This file is a snapshot of an AIDL file. Do not edit it manually. There are
// two cases:
// 1). this is a frozen version file - do not edit this in any case.
// 2). this is a 'current' file. If you make a backwards compatible change to
// the interface (from the latest frozen version), the build system will
// prompt you to update this file with `m <name>-update-api`.
//
// You must not make a backward incompatible change to any AIDL file built
// with the aidl_interface module type with versions property set. The module
// type is used to build AIDL files in a way that they can be used across
// independently updatable components of the system. If a device is shipped
// with such a backward incompatible change, it has a high risk of breaking
// later when a module using the interface is updated, e.g., Mainline modules.
package android.hardware.contexthub;
@VintfStability
parcelable VendorHubInfo {
String name;
int version;
ParcelableHolder extendedInfo;
}

View File

@@ -0,0 +1,48 @@
/*
* Copyright (C) 2024 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package android.hardware.contexthub;
/* This structure is a unique identifier for an endpoint */
@VintfStability
parcelable EndpointId {
/**
* Invalid endpoint ID.
*/
const long ENDPOINT_ID_INVALID = 0;
/**
* Reserved endpoint ID.
*/
const long ENDPOINT_ID_RESERVED = -1;
/**
* Nanoapp ID or randomly generated ID (depending on type). This value uniquely identifies the
* endpoint within a single hub.
*
* ENDPOINT_ID_INVALID(0) is an invalid id and should never be used.
* ENDPOINT_ID_RESERVED(-1) is reserved for future use.
* For static/compile-time-generated IDs, topmost bit should be 0.
* For dynamic/runtime-generated IDs, topmost bit should be 1.
*/
long id;
/**
* Hub ID of the hub hosting this endpoint. A pair of (hubId, id) uniquely identifies the
* endpoint globally.
*/
long hubId;
}

View File

@@ -0,0 +1,101 @@
/*
* Copyright (C) 2024 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package android.hardware.contexthub;
import android.hardware.contexthub.EndpointId;
import android.hardware.contexthub.Service;
/* This structure is a unified superset of NanoAppInfo and HostEndpointInfo. */
@VintfStability
parcelable EndpointInfo {
/** Unique identifier of this endpoint. */
EndpointId id;
/** Type of this endpoint. */
EndpointType type;
/**
* Name of this endpoint. Endpoint may use this field to identify the initiator of the session
* request.
*
* Depending on type of the endpoint, the following values are used:
* - Framework: package name of the process registering this endpoint
* - App: package name of the process registering this endpoint
* - Native: name of the process registering this endpoint, supplied by client for debugging
* purpose.
* - Nanoapp: name of the nanoapp, for debugging purpose
* - Generic: name of the generic endpoint, for debugging purpose
*/
String name;
/**
* Monotonically increasing version number. The two sides of an endpoint session can use this
* version number to identify the other side and determine compatibility with each other.
* The interpretation of the version number is specific to the implementation of an endpoint.
* The version number should not be used to compare endpoints implementation freshness for
* different endpoint types.
*
* Depending on type of the endpoint, the following values are used:
* - Framework: android.os.Build.VERSION.SDK_INT_FULL (populated by ContextHubService)
* - App: versionCode (populated by ContextHubService)
* - Native: unspecified format (supplied by endpoint code)
* - Nanoapp: nanoapp version, typically following 0xMMmmpppp scheme where
* MM = major version, mm = minor version, pppp = patch version
* - Generic: unspecified format (supplied by endpoint code), following nanoapp versioning
* scheme is recommended
*/
int version;
/**
* Tag for this particular endpoint. Optional string that further identifies the submodule
* that created this endpoint.
*/
@nullable String tag;
/**
* Represents the minimally required permissions in order to message this endpoint. Further
* permissions may be required on a message-by-message basis.
*/
String[] requiredPermissions;
/**
* List of services provided by this endpoint. Service list should be fixed for the
* lifetime of an endpoint.
*/
Service[] services;
@VintfStability
@Backing(type="int")
enum EndpointType {
/**
* This endpoint is from the Android framework
*/
FRAMEWORK = 1,
/** This endpoint is an Android app. */
APP = 2,
/** This endpoint is from an Android native program. */
NATIVE = 3,
/** This endpoint is from a nanoapp. */
NANOAPP = 4,
/** This endpoint is a generic endpoint (not from a nanoapp). */
GENERIC = 5,
}
}

View File

@@ -0,0 +1,54 @@
/*
* Copyright (C) 2024 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package android.hardware.contexthub;
import android.hardware.contexthub.ContextHubInfo;
import android.hardware.contexthub.VendorHubInfo;
@VintfStability
parcelable HubInfo {
/**
* Invalid hub ID.
*/
const long HUB_ID_INVALID = 0;
/**
* Reserved hub ID.
*/
const long HUB_ID_RESERVED = -1;
/**
* Hub ID (depending on type). This is a globally unique identifier.
*
* HUB_ID_INVALID(0) is an invalid id and should never be used.
* HUB_ID_RESERVED(-1) is reserved for future use.
*/
long hubId;
/**
* A hub can be either a ContextHub or a VendorHub.
*/
union HubDetails {
ContextHubInfo contextHubInfo;
VendorHubInfo vendorHubInfo;
}
/**
* Detail information about the hub.
*/
HubDetails hubDetails;
}

View File

@@ -18,12 +18,19 @@ package android.hardware.contexthub;
import android.hardware.contexthub.ContextHubInfo;
import android.hardware.contexthub.ContextHubMessage;
import android.hardware.contexthub.EndpointId;
import android.hardware.contexthub.EndpointInfo;
import android.hardware.contexthub.HostEndpointInfo;
import android.hardware.contexthub.HubInfo;
import android.hardware.contexthub.IContextHubCallback;
import android.hardware.contexthub.IEndpointCallback;
import android.hardware.contexthub.Message;
import android.hardware.contexthub.MessageDeliveryStatus;
import android.hardware.contexthub.NanSessionStateUpdate;
import android.hardware.contexthub.NanoappBinary;
import android.hardware.contexthub.NanoappInfo;
import android.hardware.contexthub.Reason;
import android.hardware.contexthub.Service;
import android.hardware.contexthub.Setting;
@VintfStability
@@ -221,7 +228,7 @@ interface IContextHub {
void onNanSessionStateChanged(in NanSessionStateUpdate update);
/**
* Puts the context hub in and out of test mode. Test mode is a clean state
* Puts the Context Hub in and out of test mode. Test mode is a clean state
* where tests can be executed in the same environment. If enable is true,
* this will enable test mode by unloading all nanoapps. If enable is false,
* this will disable test mode and reverse the actions of enabling test mode
@@ -231,7 +238,7 @@ interface IContextHub {
* @TestApi or development tools. This should not be used in a production
* environment.
*
* @param enable If true, put the context hub in test mode. If false, disable
* @param enable If true, put the Context Hub in test mode. If false, disable
* test mode.
*/
void setTestMode(in boolean enable);
@@ -256,4 +263,136 @@ interface IContextHub {
* value EX_SERVICE_SPECIFIC.
*/
const int EX_CONTEXT_HUB_UNSPECIFIED = -1;
/** Lists all the hubs, including the Context Hub and generic hubs. */
List<HubInfo> getHubs();
/** Lists all the endpoints, including the Context Hub nanoapps and generic endpoints. */
List<EndpointInfo> getEndpoints();
/**
* Publishes an endpoint from the calling side (e.g. Android). Endpoints must be registered
* prior to starting a session.
*/
void registerEndpoint(in EndpointInfo endpoint);
/**
* Teardown an endpoint from the calling side (e.g. Android). This endpoint must have already
* been published via registerEndpoint().
*/
void unregisterEndpoint(in EndpointInfo endpoint);
/**
* Attaches a callback interface to receive events targeted at endpoints registered by the
* caller.
*/
void registerEndpointCallback(in IEndpointCallback callback);
/**
* Request a range of session IDs for the caller to use when initiating sessions. This may be
* called more than once, but typical usage is to request a large enough range to accommodate
* the maximum expected number of concurrent sessions, but not overly large as to limit other
* clients.
*
* @param size The number of sessionId reserved for host-initiated sessions. This number should
* be less than or equal to 1024.
*
* @return An array with two elements representing the smallest and largest possible session id
* available for host.
*
* @throws EX_ILLEGAL_ARGUMENT if the size is invalid.
* @throws EX_SERVICE_SPECIFIC if the id range requested cannot be allocated.
*/
int[] requestSessionIdRange(int size);
/**
* Request to open a session for communication between an endpoint previously registered by the
* caller and a target endpoint found in getEndpoints(), optionally scoped to a service
* published by the target endpoint.
*
* Upon returning from this function, the session is in pending state, and the final result will
* be given by an asynchronous call to onEndpointSessionOpenComplete() on success, or
* onCloseEndpointSession() on failure.
*
* @param sessionId Caller-allocated session identifier, which must be unique across all active
* sessions, and must fall in a range allocated via requestSessionIdRange().
* @param destination The EndpointId representing the destination side of the session.
* @param initiator The EndpointId representing the initiating side of the session, which
* must've already been published through registerEndpoint().
* @param serviceDescriptor Descriptor for the service specification for scoping this session
* (nullable). Null indicates a fully custom marshalling scheme. The value should match
* a published descriptor for both destination and initiator.
*
* @return An integer identifying the session, the integer can be used to present
* the tuple of (destination, initiator, serviceDescriptor).
*
* @throws EX_ILLEGAL_ARGUMENT if any of the arguments are invalid, or the combination of the
* arguments is invalid.
* @throws EX_SERVICE_SPECIFIC on other errors
* - EX_CONTEXT_HUB_UNSPECIFIED if the request failed for other reasons.
*/
void openEndpointSession(int sessionId, in EndpointId destination, in EndpointId initiator,
in @nullable String serviceDescriptor);
/**
* Send a message from one endpoint to another on the (currently open) session.
*
* @param sessionId The integer representing the communication session, previously set in
* openEndpointSession() or onEndpointSessionOpenRequest().
* @param msg The Message object representing a message to endpoint from the endpoint on host.
*
* @throws EX_ILLEGAL_ARGUMENT if any of the arguments are invalid, or the combination of the
* arguments is invalid.
* @throws EX_SERVICE_SPECIFIC on other errors
* - EX_CONTEXT_HUB_UNSPECIFIED if the request failed for other reasons.
*/
void sendMessageToEndpoint(int sessionId, in Message msg);
/**
* Sends a message delivery status to the endpoint in response to receiving a Message with flag
* FLAG_REQUIRES_DELIVERY_STATUS. Each message with the flag should have a MessageDeliveryStatus
* response. This method sends the message delivery status back to the remote endpoint for a
* session.
*
* @param sessionId The integer representing the communication session, previously set in
* openEndpointSession() or onEndpointSessionOpenRequest().
* @param msgStatus The MessageDeliveryStatus object representing the delivery status for a
* specific message (identified by the sequenceNumber) within the session.
*
* @throws EX_UNSUPPORTED_OPERATION if ContextHubInfo.supportsReliableMessages is false for
* the hub involved in this session.
*/
void sendMessageDeliveryStatusToEndpoint(int sessionId, in MessageDeliveryStatus msgStatus);
/**
* Closes a session previously opened by openEndpointSession() or requested via
* onEndpointSessionOpenRequest(). Processing of session closure must be ordered/synchronized
* with message delivery, such that if this session was open, any messages previously passed to
* sendMessageToEndpoint() that are still in-flight must still be delivered before the session
* is closed. Any in-flight messages to the endpoint that requested to close the session will
* not be delivered.
*
* @param sessionId The integer representing the communication session, previously set in
* openEndpointSession() or onEndpointSessionOpenRequest().
* @param reason The reason for this close endpoint session request.
*
* @throws EX_ILLEGAL_ARGUMENT if any of the arguments are invalid, or the combination of the
* arguments is invalid.
* @throws EX_SERVICE_SPECIFIC on other errors
* - EX_CONTEXT_HUB_UNSPECIFIED if the request failed for other reasons.
*/
void closeEndpointSession(int sessionId, in Reason reason);
/**
* Notifies the HAL that the session requested by onEndpointSessionOpenRequest is ready to use.
*
* @param sessionId The integer representing the communication session, previously set in
* onEndpointSessionOpenRequest(). This id is assigned by the HAL.
*
* @throws EX_ILLEGAL_ARGUMENT if any of the arguments are invalid, or the combination of the
* arguments is invalid.
* @throws EX_SERVICE_SPECIFIC on other errors
* - EX_CONTEXT_HUB_UNSPECIFIED if the request failed for other reasons.
*/
void endpointSessionOpenComplete(int sessionId);
}

View File

@@ -0,0 +1,118 @@
/*
* Copyright (C) 2024 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package android.hardware.contexthub;
import android.hardware.contexthub.EndpointId;
import android.hardware.contexthub.EndpointInfo;
import android.hardware.contexthub.Message;
import android.hardware.contexthub.MessageDeliveryStatus;
import android.hardware.contexthub.Reason;
import android.hardware.contexthub.Service;
@VintfStability
interface IEndpointCallback {
/**
* Lifecycle event notification for endpoint starting from remote side. There is no need to
* report already started endpoint prior to the registration of an EndpointLifecycleCallbacks
* object. The EndpointInfo reported here should be consistent with values from getEndpoints().
*
* Endpoints added by registerEndpoint should not be included. registerEndpoint() should not
* cause this call.
*
* @param endpointInfos An array of EndpointInfo representing endpoints that just started.
*/
void onEndpointStarted(in EndpointInfo[] endpointInfos);
/**
* Lifecycle event notification for endpoint stopping from remote side. There is no need to
* report already stopped endpoint prior to the registration of an EndpointLifecycleCallbacks
* object. The EndpointId reported here should represent a previously started Endpoint.
*
* When a hub crashes or restart, events should be batched into be a single call (containing all
* the EndpointId that were impacted).
*
* Endpoints added by registerEndpoint should not be included. unregisterEndpoint() should not
* cause this call.
*
* @param endpointIds An array of EndpointId representing endpoints that just stopped.
* @param reason The reason for why the endpoints stopped.
*/
void onEndpointStopped(in EndpointId[] endpointIds, Reason reason);
/**
* Invoked when an endpoint sends message to another endpoint (on host) on the (currently open)
* session.
*
* @param sessionId The integer representing the communication session, previously set in
* openEndpointSession() or onEndpointSessionOpenRequest().
* @param msg The Message object representing a message from endpoint to an endpoint on host.
*/
void onMessageReceived(int sessionId, in Message msg);
/**
* Invoked when an endpoint sends the response for a message that requires delivery status.
*
* The response is the message delivery status of a recently sent message within a session. See
* sendMessageDeliveryStatusToEndpoint() for more details.
*
* @param sessionId The integer representing the communication session, previously set in
* openEndpointSession() or onEndpointSessionOpenRequest().
* @param msgStatus The MessageDeliveryStatus object representing the delivery status for a
* specific message (identified by the sequenceNumber) within the session.
*/
void onMessageDeliveryStatusReceived(int sessionId, in MessageDeliveryStatus msgStatus);
/**
* Invoked when session initiation is requested by a remote endpoint. The receiving host client
* must later call endpointSessionOpenComplete() to indicate successful connection and
* acceptance of the session, or closeEndpointSession() to indicate failure.
*
* @param sessionId Caller-allocated session identifier, which must be unique across all active
* sessions, and must not fall in a range allocated via requestSessionIdRange().
* @param destination The EndpointId representing the destination side of the session, which
* must've already been published through registerEndpoint().
* @param initiator The EndpointId representing the initiating side of the session.
* @param serviceDescriptor Descriptor for the service specification for scoping this session
* (nullable). Null indicates a fully custom marshalling scheme. The value should match
* a published descriptor for both endpoints.
*
* @throws EX_ILLEGAL_ARGUMENT if any of the arguments are invalid, or the combination of the
* arguments is invalid.
*/
void onEndpointSessionOpenRequest(int sessionId, in EndpointId destination,
in EndpointId initiator, in @nullable String serviceDescriptor);
/**
* Invoked when a session has either failed to open, or has been closed by the remote side.
* Upon receiving this callback, the session is closed and further messages on it will not be
* delivered.
*
* @param sessionId The integer representing the communication session, previously set in
* openEndpointSession() or onEndpointSessionOpenRequest().
* @param reason The reason for this close endpoint session notification.
*/
void onCloseEndpointSession(int sessionId, in Reason reason);
/**
* Callback when a session is opened. This callback is the status callback for a previous
* openEndpointSession().
*
* @param sessionId The integer representing the communication session, previously set in
* onEndpointSessionOpenRequest(). This id is assigned by the host.
*/
void onEndpointSessionOpenComplete(int sessionId);
}

View File

@@ -0,0 +1,51 @@
/*
* Copyright (C) 2024 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package android.hardware.contexthub;
@VintfStability
parcelable Message {
/**
* Bitmask for flags field if this message requires a MessageDeliveryStatus for the
* sequenceNumber within 1 second.
*/
const int FLAG_REQUIRES_DELIVERY_STATUS = 1;
/** Bitset of flags */
int flags;
/** Sequence number of this message */
int sequenceNumber;
/**
* Per message permission (used for app-op permission attribution).
*/
String[] permissions;
/**
* The type of this message payload, following a scheme specific to the service or sending
* endpoint's communication protocol. This value can be used to distinguish the handling of
* content (e.g. for decoding). This could also be used as the complete content of the message
* if no additional payload is needed.
*/
int type;
/**
* Content (payload) of the message. The format of the message is specific to the context of the
* message: the service or endpoints involved in the session, and the message type.
*/
byte[] content;
}

View File

@@ -21,7 +21,8 @@ import android.hardware.contexthub.ErrorCode;
@VintfStability
parcelable MessageDeliveryStatus {
/**
* The messageSequenceNumber of the ContextHubMessage to which this status applies.
* The messageSequenceNumber of the ContextHubMessage or Message to which this status is
* required.
*/
int messageSequenceNumber;

View File

@@ -0,0 +1,66 @@
/*
* Copyright (C) 2023 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package android.hardware.contexthub;
@VintfStability
@Backing(type="byte")
enum Reason {
/**
* Unspecified reason.
*/
UNSPECIFIED = 0,
/**
* Out of memory. There's not enough memory to perform this operation.
*/
OUT_OF_MEMORY,
/**
* Timeout. This operation timed out.
*/
TIMEOUT,
/**
* Endpoint rejected this openEndpointSession request.
*/
OPEN_ENDPOINT_SESSION_REQUEST_REJECTED,
/**
* Endpoint requested closeEndpointSession.
*/
CLOSE_ENDPOINT_SESSION_REQUESTED,
/**
* Invalid endpoint.
*/
ENDPOINT_INVALID,
/**
* Endpoint is now stopped.
*/
ENDPOINT_GONE,
/**
* Endpoint crashed.
*/
ENDPOINT_CRASHED,
/**
* Hub was reset or is resetting.
*/
HUB_RESET,
}

View File

@@ -0,0 +1,67 @@
/*
* Copyright (C) 2024 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package android.hardware.contexthub;
@VintfStability
parcelable Service {
/**
* Type of the Service. This field defines the messaging format used for this service.
* The format refers to how the data would be marhsalled in messages between host endpoint (on
* Android) and endpoint on the Context Hub or generic hub.
*/
RpcFormat format;
/**
* Uniquely identifies the interface (scoped to type). Conventions depend on interface type.
* Examples:
* 1. AOSP-defined AIDL: android.hardware.something.IFoo/default
* 2. Vendor-defined AIDL: com.example.something.IBar/default
* 3. Pigweed RPC with Protobuf: com.example.proto.ExampleService
*/
String serviceDescriptor;
/** Breaking changes should be a major version bump. */
int majorVersion;
/** Monotonically increasing minor version. */
int minorVersion;
/** Hook for additional detail in vendor-specific type */
ParcelableHolder extendedInfo;
/**
* Supported messaging format for the service between the host and the hubs.
*/
@VintfStability
@Backing(type="int")
enum RpcFormat {
/**
* Customized format for messaging. Fully customized and opaque messaging format.
*/
CUSTOM = 0,
/**
* Binder-based messaging. The host endpoint is defining this service in Stable AIDL.
* Messages between endpoints that uses this service will be using the binder marhsalling
* format.
*/
AIDL = 1,
/**
* Pigweed RPC messaging with Protobuf. This endpoint is a Pigweed RPC. Messages between
* endpoints will use Pigweed RPC marshalling format (protobuf).
*/
PW_RPC_PROTOBUF = 2,
}
}

View File

@@ -0,0 +1,33 @@
/*
* Copyright (C) 2024 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package android.hardware.contexthub;
/**
* A representation of a vendor-specific hub providing endpoints (with services). The hub does not
* run the Context Hub Runtime Environment, but exposes a similar messaging API.
*/
@VintfStability
parcelable VendorHubInfo {
/** Descriptive name of the basic hub */
String name;
/** Version of the hub */
int version;
/** Hook for additional detail in vendor-specific type */
ParcelableHolder extendedInfo;
}

View File

@@ -30,7 +30,7 @@ cc_library_static {
shared_libs: [
"libbase",
"libbinder_ndk",
"android.hardware.contexthub-V3-ndk",
"android.hardware.contexthub-V4-ndk",
],
export_include_dirs: ["include"],
srcs: [
@@ -51,7 +51,7 @@ cc_binary {
shared_libs: [
"libbase",
"libbinder_ndk",
"android.hardware.contexthub-V3-ndk",
"android.hardware.contexthub-V4-ndk",
],
static_libs: [
"libcontexthubexampleimpl",

View File

@@ -136,4 +136,83 @@ ScopedAStatus ContextHub::sendMessageDeliveryStatusToHub(
return ScopedAStatus::fromExceptionCode(EX_UNSUPPORTED_OPERATION);
}
ScopedAStatus ContextHub::getHubs(std::vector<HubInfo>* _aidl_return) {
ContextHubInfo hub = {};
hub.name = "Mock Context Hub";
hub.vendor = "AOSP";
hub.toolchain = "n/a";
hub.id = kMockHubId;
hub.peakMips = 1;
hub.maxSupportedMessageLengthBytes = 4096;
hub.chrePlatformId = UINT64_C(0x476f6f6754000000);
hub.chreApiMajorVersion = 1;
hub.chreApiMinorVersion = 6;
hub.supportsReliableMessages = false;
HubInfo hubInfo1 = {};
hubInfo1.hubId = hub.chrePlatformId;
hubInfo1.hubDetails = HubInfo::HubDetails::make<HubInfo::HubDetails::Tag::contextHubInfo>(hub);
VendorHubInfo vendorHub = {};
vendorHub.name = "Mock Vendor Hub";
vendorHub.version = 42;
HubInfo hubInfo2 = {};
hubInfo1.hubId = UINT64_C(0x1234567812345678);
hubInfo1.hubDetails =
HubInfo::HubDetails::make<HubInfo::HubDetails::Tag::vendorHubInfo>(vendorHub);
_aidl_return->push_back(hubInfo1);
_aidl_return->push_back(hubInfo2);
return ScopedAStatus::ok();
};
ScopedAStatus ContextHub::getEndpoints(std::vector<EndpointInfo>* /* _aidl_return */) {
return ScopedAStatus::fromExceptionCode(EX_UNSUPPORTED_OPERATION);
};
ScopedAStatus ContextHub::registerEndpoint(const EndpointInfo& /* in_endpoint */) {
return ScopedAStatus::fromExceptionCode(EX_UNSUPPORTED_OPERATION);
};
ScopedAStatus ContextHub::unregisterEndpoint(const EndpointInfo& /* in_endpoint */) {
return ScopedAStatus::fromExceptionCode(EX_UNSUPPORTED_OPERATION);
};
ScopedAStatus ContextHub::registerEndpointCallback(
const std::shared_ptr<IEndpointCallback>& /* in_callback */) {
return ScopedAStatus::fromExceptionCode(EX_UNSUPPORTED_OPERATION);
};
ScopedAStatus ContextHub::requestSessionIdRange(int32_t /* in_size */,
std::vector<int32_t>* /* _aidl_return */) {
return ScopedAStatus::fromExceptionCode(EX_UNSUPPORTED_OPERATION);
};
ScopedAStatus ContextHub::openEndpointSession(
int32_t /* in_sessionId */, const EndpointId& /* in_destination */,
const EndpointId& /* in_initiator */,
const std::optional<std::string>& /* in_serviceDescriptor */) {
return ScopedAStatus::fromExceptionCode(EX_UNSUPPORTED_OPERATION);
};
ScopedAStatus ContextHub::sendMessageToEndpoint(int32_t /* in_sessionId */,
const Message& /* in_msg */) {
return ScopedAStatus::fromExceptionCode(EX_UNSUPPORTED_OPERATION);
};
ScopedAStatus ContextHub::sendMessageDeliveryStatusToEndpoint(
int32_t /* in_sessionId */, const MessageDeliveryStatus& /* in_msgStatus */) {
return ScopedAStatus::fromExceptionCode(EX_UNSUPPORTED_OPERATION);
};
ScopedAStatus ContextHub::closeEndpointSession(int32_t /* in_sessionId */, Reason /* in_reason */) {
return ScopedAStatus::fromExceptionCode(EX_UNSUPPORTED_OPERATION);
};
ScopedAStatus ContextHub::endpointSessionOpenComplete(int32_t /* in_sessionId */) {
return ScopedAStatus::fromExceptionCode(EX_UNSUPPORTED_OPERATION);
};
} // namespace aidl::android::hardware::contexthub

View File

@@ -1,7 +1,7 @@
<manifest version="1.0" type="device">
<hal format="aidl">
<name>android.hardware.contexthub</name>
<version>3</version>
<version>4</version>
<interface>
<name>IContextHub</name>
<instance>default</instance>

View File

@@ -53,6 +53,24 @@ class ContextHub : public BnContextHub {
int32_t in_contextHubId,
const MessageDeliveryStatus& in_messageDeliveryStatus) override;
::ndk::ScopedAStatus getHubs(std::vector<HubInfo>* _aidl_return) override;
::ndk::ScopedAStatus getEndpoints(std::vector<EndpointInfo>* _aidl_return) override;
::ndk::ScopedAStatus registerEndpoint(const EndpointInfo& in_endpoint) override;
::ndk::ScopedAStatus unregisterEndpoint(const EndpointInfo& in_endpoint) override;
::ndk::ScopedAStatus registerEndpointCallback(
const std::shared_ptr<IEndpointCallback>& in_callback) override;
::ndk::ScopedAStatus requestSessionIdRange(int32_t in_size,
std::vector<int32_t>* _aidl_return) override;
::ndk::ScopedAStatus openEndpointSession(
int32_t in_sessionId, const EndpointId& in_destination, const EndpointId& in_initiator,
const std::optional<std::string>& in_serviceDescriptor) override;
::ndk::ScopedAStatus sendMessageToEndpoint(int32_t in_sessionId,
const Message& in_msg) override;
::ndk::ScopedAStatus sendMessageDeliveryStatusToEndpoint(
int32_t in_sessionId, const MessageDeliveryStatus& in_msgStatus) override;
::ndk::ScopedAStatus closeEndpointSession(int32_t in_sessionId, Reason in_reason) override;
::ndk::ScopedAStatus endpointSessionOpenComplete(int32_t in_sessionId) override;
private:
static constexpr uint32_t kMockHubId = 0;
std::shared_ptr<IContextHubCallback> mCallback;