From fc5fc0e74df003b0ee454d3418b88cd722282c49 Mon Sep 17 00:00:00 2001 From: Gina Dimino Date: Mon, 12 Jul 2021 16:35:38 -0700 Subject: Remove obsolete sync directories for SAC Test: N/A Change-Id: I5245330990d722ad4d15a0600532943840f30830 --- en/devices/architecture/hidl-cpp/functions.html | 153 ----------- en/devices/architecture/hidl-cpp/index.html | 148 ----------- en/devices/architecture/hidl-cpp/interfaces.html | 271 ------------------- en/devices/architecture/hidl-cpp/packages.html | 202 -------------- en/devices/architecture/hidl-cpp/types.html | 323 ----------------------- 5 files changed, 1097 deletions(-) delete mode 100644 en/devices/architecture/hidl-cpp/functions.html delete mode 100644 en/devices/architecture/hidl-cpp/index.html delete mode 100644 en/devices/architecture/hidl-cpp/interfaces.html delete mode 100644 en/devices/architecture/hidl-cpp/packages.html delete mode 100644 en/devices/architecture/hidl-cpp/types.html (limited to 'en/devices/architecture/hidl-cpp') diff --git a/en/devices/architecture/hidl-cpp/functions.html b/en/devices/architecture/hidl-cpp/functions.html deleted file mode 100644 index 5d52b31d..00000000 --- a/en/devices/architecture/hidl-cpp/functions.html +++ /dev/null @@ -1,153 +0,0 @@ - - - Functions - - - - - - -

Functions in a HIDL interface are mapped to methods in the autogenerated -IFoo C++ class declaration. The name of each function remains the -same in C++; the following sections describe how HIDL arguments and return -values are translated to C++.

- -

Function parameters

-

The arguments listed in the .hal file map to C++ data types. -Arguments that do not map to a primitive C++ type are passed by const -reference.

- -

For every HIDL function that has a return value (has a generates -statement), the C++ parameter list for that function has an additional argument: -a callback function that is called with the return values of the HIDL function. -There is one exception: If the generates clause -contains a single parameter that directly maps to a C++ primitive, callback -elision is used (the callback is removed and the return value is -returned from the function through a normal return statement).

- -

Function return values

-

The following functions have return values.

- -

Transport errors and return type

-

The generates statement can result in three types of function -signatures:

- - - -

RPC calls can occasionally encounter transport errors, e.g. when the server -dies, when transport resources are insufficient to complete the call, or when -the parameters passed do not permit completing the call (such as missing a -required callback function). Return objects store transport error -indications as well as a T value (except -Return<void>).

- -

As the client-side and server-side functions have the same signature, the -server-side function must return a Return type even though its -implementation does not signal transport errors. Return<T> -objects are constructed with Return(myTValue) (or can be implicitly -constructed from mTValue, such as in return -statements) and Return<void> objects are constructed with -Void().

- -

Return<T> objects have implicit conversion to and from -their T value. The Return object can be checked for -transport errors by calling its isOk() method. This check is not -required; however, if an error occurs and is not checked by the time the -Return object is destroyed, or a T value conversion is -attempted, the client process will be killed and an error logged. If -isOk() indicates a transport error or a call failure due to a logic -error in developer code (such as passing nullptr as a synchronous -callback), then description() can be called on the Return object to -return a string suitable for logging. In such cases, there is no way to -determine how much code may have executed on the server as a result of the -failed call. The method isDeadObject() is also provided. This -method indicates that !isOk() is because the remote object has -crashed or no longer exists. isDeadObject() always implies -!isOk().

- -

Return by value

-

If the generates statement maps to a single C++ primitive, no -callback parameter is in the parameter list. Instead, an implementation provides -the return value T in a Return<T> object, which -can be implicitly generated from the primitive type T. For -example:

- -
-Return<uint32_t> someMethod() {
-    uint32_t return_data = ...; // Compute return_data
-    return return_data;
-};
-
- -

The method Return<*>::withDefault is also provided. This -method provides a value in cases where the return value is !isOk(). -This method also automatically marks the return object as okay so the client -process will not be killed.

- -

Return using callback parameter

-

A callback can pass the return value of the HIDL function back to the caller. -The prototype of the callback is a std::function object with -parameters (taken from the generates statement) mapped to C++ -types. Its return value is void—the callback itself doesn't return a value.

- -

The return value of a C++ function with a callback parameter has type -Return<void>. The server implementation is responsible only -for providing the return value. As the return values are already transferred -using the callback, the T template parameter is void: -

- -
-Return<void> someMethod(someMethod_cb _cb);
-
- -

From their C++ implementation, server implementations should return -Void(), which is a static inlined function returning a -Return<void> object. Example of a typical server method -implementation with a callback parameter:

- -
-Return<void> someMethod(someMethod_cb _cb) {
-    // Do some processing, then call callback with return data
-    hidl_vec<uint32_t> vec = ...
-    _cb(vec);
-    return Void();
-};
-
- -

Functions without return values

-

The C++ signature of a function without a generates statement -will not have a callback parameter in the parameter list. Its return type will -be Return<void>.

- -

Oneway functions

-

Functions marked with the oneway keyword are asynchronous -functions (clients won't block on their execution) and do not have return -values. The C++ signature of a oneway function will not have a -callback parameter in the parameter list, and its C++ return value will be -Return<void>.

- - - diff --git a/en/devices/architecture/hidl-cpp/index.html b/en/devices/architecture/hidl-cpp/index.html deleted file mode 100644 index 340d5766..00000000 --- a/en/devices/architecture/hidl-cpp/index.html +++ /dev/null @@ -1,148 +0,0 @@ - - - HIDL C++ - - - - - - -

Android O re-architects the Android OS to define clear interfaces between the -device-independent Android platform and device- and vendor-specific code. -Android already defines many such interfaces in the form of HAL interfaces, -defined as C headers in hardware/libhardware. HIDL replaces these -HAL interfaces with stable, versioned interfaces, which can be client- and -server-side HIDL interfaces in C++ (described below) or -Java.

- -

The pages in this section describe C++ implementations of HIDL interfaces, -including details about the files auto-generated from the HIDL .hal -files by the hidl-gen compiler, how these files are packaged, and -how to integrate these files with the C++ code that uses them.

- -

Client & server implementations

-

HIDL interfaces have client and server implementations:

- - - -

In transitioning from libhardware HALs to HIDL HALs, the HAL -implementation becomes the server and the process calling into the HAL becomes -the client. Default implementations can serve both passthrough and binderized -HALs, and can change over time:

- -

-

Figure 1. Development progression for legacy HALs.

- -

Creating the HAL client

-

Start by including the HAL libraries in the makefile:

- - - -

Next, include the HAL header files:

- -
-#include <android/hardware/nfc/1.0/IFoo.h>
-…
-// in code:
-sp<IFoo> client = IFoo::getService();
-client->doThing();
-
- -

Creating the HAL server

-

To create the HAL implementation, you must have the .hal files -that represent your HAL and have already generated makefiles for your HAL using --Lmakefile or -Landroidbp on hidl-gen -(./hardware/interfaces/update-makefiles.sh does this for internal -HAL files and is a good reference). When transferring over HALs from -libhardware, you can do a lot of this work easily using c2hal.

- -

To create the necessary files to implement your HAL:

- -
-PACKAGE=android.hardware.nfc@1.0
-LOC=hardware/interfaces/nfc/1.0/default/
-m -j hidl-gen
-hidl-gen -o $LOC -Lc++-impl -randroid.hardware:hardware/interfaces \
-    -randroid.hidl:system/libhidl/transport $PACKAGE
-hidl-gen -o $LOC -Landroidbp-impl -randroid.hardware:hardware/interfaces \
-    -randroid.hidl:system/libhidl/transport $PACKAGE
-
- -

For the HAL to work in passthrough mode (for legacy devices), you must have -the function HIDL_FETCH_IModuleName residing in -/(system|vendor|...)/lib(64)?/hw/android.hardware.package@3.0-impl($OPTIONAL_IDENTIFIER).so -where $OPTIONAL_IDENTIFIER is a string identifying the passthrough -implementation. The passthrough mode requirements are met automatically by the -above commands, which also create the android.hardware.nfc@1.0-impl -target, but any extension can be used. For instance -android.hardware.nfc@1.0-impl-foo uses -foo to -differentiate itself.

- -

Next, fill out the stubs with functionality and setup a daemon. Example -daemon code (supporting passthrough):

- -
-#include <hidl/LegacySupport.h>
-
-int main(int /* argc */, char* /* argv */ []) {
-    return defaultPassthroughServiceImplementation<INfc>("nfc");
-}
-
- -

defaultPassthroughServiceImplementation will -dlopen() the provided -impl library and provide it as -a binderized service. Example daemon code (for pure binderized service):

- -
-int main(int /* argc */, char* /* argv */ []) {
-    // This function must be called before you join to ensure the proper
-    // number of threads are created. The threadpool will never exceed
-    // size one because of this call.
-    ::android::hardware::configureRpcThreadpool(1 /*threads*/, true /*willJoin*/);
-
-    sp nfc = new Nfc();
-    const status_t status = nfc->registerAsService();
-    if (status != ::android::OK) {
-        return 1; // or handle error
-    }
-
-    // Adds this thread to the threadpool, resulting in one total
-    // thread in the threadpool. We could also do other things, but
-    // would have to specify 'false' to willJoin in configureRpcThreadpool.
-    ::android::hardware::joinRpcThreadpool();
-    return 1; // joinRpcThreadpool should never return
-}
-
- -

This daemon usually lives in $PACKAGE + "-service-suffix" (for -example, android.hardware.nfc@1.0-service), but it could be anywhere. -The sepolicy for a specific -class of HALs is the attribute hal_<module> (for instance, -hal_nfc). This attribute must be applied to the daemon that runs a -particular HAL (if the same process serves multiple HALs, multiple attributes -can be applied to it).

- - - diff --git a/en/devices/architecture/hidl-cpp/interfaces.html b/en/devices/architecture/hidl-cpp/interfaces.html deleted file mode 100644 index c236a171..00000000 --- a/en/devices/architecture/hidl-cpp/interfaces.html +++ /dev/null @@ -1,271 +0,0 @@ - - - Interfaces - - - - - - -

Every interface defined in a HIDL package has its own autogenerated C++ class -inside its package's namespace. Clients and servers deal with interfaces in -different ways:

- - - -

Interfaces can either be registered by name by the server or passed as -parameters to HIDL-defined methods. For example, framework code may serve an -interface to receive asynchronous messages from the HAL and pass that interface -directly to the HAL without registering it.

- -

Server implementation

-

A server implementing the IFoo interface must include the -IFoo header file that was autogenerated:

- -
-#include <android/hardware/samples/1.0/IFoo.h>
-
- -

The header is automatically exported by the shared library of the -IFoo interface to link against. Example IFoo.hal:

- -
-// IFoo.hal
-interface IFoo {
-    someMethod() generates (vec<uint32_t>);
-    ...
-}
-
- -

Example skeleton for a server implementation of the IFoo interface:

- -
-// From the IFoo.h header
-using android::hardware::samples::V1_0::IFoo;
-
-class FooImpl : public IFoo {
-    Return<void> someMethod(foo my_foo, someMethod_cb _cb) {
-        vec<uint32_t> return_data;
-        // Compute return_data
-        _cb(return_data);
-        return Void();
-    }
-    ...
-};
-
- -

To make the implementation of a server interface available to a client, you -can:

- -
    -
  1. Register the interface implementation with the -hwservicemanager (see details below), -

    -OR

    -
    2. -
  2. Pass the interface implementation as an argument of an -interface method (for detals, see Asynchronous -callbacks).
    3. -
- -

When registering the interface implementation, the -hwservicemanager process keeps track of registered HIDL interfaces -running on the device by name and version. Servers can register a HIDL interface -implementation by name and clients can request service implementations by name -and version. This process serves the HIDL interface -android.hidl.manager@1.0::IServiceManager.

- -

Each auto-generated HIDL interface header file (such as IFoo.h) -has a registerAsService() method that can be used to register the -interface implementation with the hwservicemanager. The only -required argument is the name of the interface implementations as clients will -use this name to retrieve the interface from the hwservicemanager -later:

- -
-::android::sp<IFoo> myFoo = new FooImpl();
-::android::sp<IFoo> mySecondFoo = new FooAnotherImpl();
-status_t status = myFoo->registerAsService();
-status_t anotherStatus = mySecondFoo->registerAsService("another_foo");
-
- -

The hwservicemanager treats the combination of -[package@version::interface, instance_name] as unique to enable -different interfaces (or different versions of the same interface) to register -with identical instance names without conflicts. If you call -registerAsService() with the exact same package version, interface, -and instance name, the hwservicemanager drops its reference to the -previously registered service and uses the new one.

- -

Client implementation

-

Just as the server does, a client must #include every interface -it refers to:

- -
-#include <android/hardware/samples/1.0/IFoo.h>
-
- -

A client can obtain an interface in two ways:

- - - -

Each autogenerated interface header file has a static getService -method that can be used to retrieve a service instance from the -hwservicemanager:

- -
-// getService will return nullptr if the service can't be found
-sp<IFoo> myFoo = IFoo::getService();
-sp<IFoo> myAlternateFoo = IFoo::getService("another_foo");
-
- -

Now the client has an an IFoo interface, and can call methods to -it as if it were a local class implementation. In reality, the implementation -may run in the same process, a different process, or even on another device -(with HAL remoting). Because the client called getService on an -IFoo object included from version 1.0 of the package, -the hwservicemanager returns a server implementation only if that -implementation is compatible with 1.0 clients. In practice, this -means only server implementations with version 1.n (version -x.(y+1) of an interface must extend (inherit from) -x.y).

- -

Additionally the method castFrom is provided to cast between -different interfaces. This method works by making an IPC call to the remote -interface to make sure the underlying type is the same as the type that is being -requested. If the requested type is unavailable, then nullptr is -returned.

- -
-sp<V1_0::IFoo> foo1_0 = V1_0::IFoo::getService();
-sp<V1_1::IFoo> foo1_1 = V1_1::IFoo::castFrom(foo1_0);
-
- -

Asynchronous callbacks

-

Many existing HAL implementations talk to asynchronous hardware, which means -they need an asynchronous way to notify clients of new events that have -occurred. A HIDL interface can be used as an asynchronous callback because HIDL -interface functions can take HIDL interface objects as parameters.

- -

Example interface file IFooCallback.hal:

- -
-package android.hardware.samples@1.0;
-interface IFooCallback {
-    sendEvent(uint32_t event_id);
-    sendData(hidl_vec<uint8_t> data);
-}
-
- -

Example new method in IFoo that takes an -IFooCallback parameter:

- -
-package android.hardware.samples@1.0;
-interface IFoo {
-    struct Foo {
-       int64_t some_value;
-       Handle my_handle;
-    };
-
-    someMethod(Foo foo) generates (int32_t ret);
-    another_method() generates (hidl_vec<uint32_t>);
-    register_callback(IFooCallback callback);
-};
-
- -

The client using the IFoo interface is the -server of the IFooCallback interface; it provides an -implementation of IFooCallback:

- -
-class FooCallback : public IFooCallback {
-    Return<void> sendEvent(uint32_t event_id) {
-        // process the event from the HAL
-    }
-    Return<void> sendData(hidl_vec<uint8_t> data) {
-        // process data from the HAL
-    }
-};
-
- -

It can also simply pass that over an existing instance of the -IFoo interface:

-
-sp<IFooCallback> myFooCallback = new FooCallback();
-myFoo.registerCallback(myFooCallback);
-
- -

The server implementing IFoo receives this as an -sp<IFooCallback> object. It can store the callback, and call -back into the client whenever it wants to use this interface.

- -

Death recipients

-

As service implementations can run in a different process, it can happen -that the process implementing an interface dies while the client stays alive. -Any calls on an interface object hosted in a process that has died will fail -with a transport error (isOK() will return false). The only way to -recover from such a failure is to request a new instance of the service by -calling I<InterfaceName>::getService(). This works only if -the process that crashed has restarted and re-registered its services with the -servicemanager (which is generally true for HAL implementations). -

- -

Instead of dealing with this reactively, clients of an interface can also -register a death recipient to get a notification when a service dies. -To register for such notifications on a retrieved IFoo interface, a -client can do the following:

- -
-foo->linkToDeath(recipient, 1481 /* cookie */);
-
- -

The recipient parameter must be an implementation of the -android::hardware::hidl_death_recipient interface provided by HIDL, -which contains a single method serviceDied() that will be called -from a thread in the RPC threadpool when the process hosting the interface dies: -

- -
-class MyDeathRecipient : public android::hardware::hidl_death_recipient {
-    virtual void serviceDied(uint64_t cookie, const android::wp<::android::hidl::base::V1_0::IBase>& who) {
-       // Deal with the fact that the service died
-    }
-}
-
- -

The cookie parameter contains the cookie that was passed in with -linkToDeath(), whereas the who parameter contains a -weak pointer to the object representing the service in the client. With the -sample call given above, cookie equals 1481, and who -equals foo.

- -

It's also possible to unregister a death recipient after registering it:

- -
-foo->unlinkToDeath(recipient);
-
- - - diff --git a/en/devices/architecture/hidl-cpp/packages.html b/en/devices/architecture/hidl-cpp/packages.html deleted file mode 100644 index 2c8e096d..00000000 --- a/en/devices/architecture/hidl-cpp/packages.html +++ /dev/null @@ -1,202 +0,0 @@ - - - Packages - - - - - - -

Note: This section uses sample .hal -files to illustrate how HIDL language constructs map to C++.

- -

With few exceptions, HIDL interface packages are located in -hardware/interfaces or the vendor/ directory. The -hardware/interfaces top-level maps directly to the -android.hardware package namespace; the version is a subdirectory -under the package (not interface) namespace.

- -

The hidl-gen compiler compiles the .hal files into -a set of a .h and .cpp files. From these autogenerated -files a shared library that client/server implementations link against is built. -The Android.bp file that builds this shared library is -autogenerated by the hardware/interfaces/update-makefiles.sh -script. Every time you add a new package to hardware/interfaces, or -add/remove .hal files to/from an existing package, you must rerun -the script to ensure the generated shared library is up-to-date.

- -

For example, the IFoo.hal sample file should be located in -hardware/interfaces/samples/1.0. The sample -IFoo.hal file creates an IFoo interface in the -samples package:

- -
-package android.hardware.samples@1.0;
-interface IFoo {
-    struct Foo {
-       int64_t someValue;
-       handle  myHandle;
-    };
-
-    someMethod() generates (vec<uint32_t>);
-    anotherMethod(Foo foo) generates (int32_t ret);
-};
-
- -

Generated files

- -

Autogenerated files in a HIDL package are linked into a single shared -library with the same name as the package (for example, -android.hardware.samples@1.0). The shared library also exports a -single header, IFoo.h, which can be included by clients and -servers. Using the hidl-gen compiler with the IFoo.hal -interface file as an input, binderized mode has the following autogenerated -files:

- -

-

Figure 1. Files generated by compiler.

- - - -

The files are structured similarly to the files generated by -aidl-cpp (for details, see "Passthrough mode" in the -HIDL Overview). The only -autogenerated file that is independent of the RPC mechanism used by HIDL is -IFoo.h; all other files are tied to the HwBinder RPC mechanism used -by HIDL. Therefore, client and server implementations should never -directly refer to anything other than IFoo. To achieve -this, include only IFoo.h and link against the generated shared -library.

- -

Note: HwBinder is only one possible transport; -new transports may be added in the future.

- - -

A client or server that uses any interface in a package must include the -shared library of that package in one (1) of the following -locations:

- - - -

For specific libraries:

- - - - - - - - - - - - - - - - - - - - - - - - -
libhidlbaseIncludes standard HIDL data-types. Unless your interface consists only of -primitives that map directly to C++ primitives, you must also link this library: -
-LOCAL_SHARED_LIBRARIES += libhidlbase
-
-
libhidltransportHandles the transport of HIDL calls over different RPC/IPC mechanisms. You -must always link this library: -
-LOCAL_SHARED_LIBRARIES += libhidltransport
-
-
libhwbinderYou must also link to this library: -
-LOCAL_SHARED_LIBRARIES += libhwbinder
-
-
libfmqTo use Fast Message Queue IPC, you must also link to this library. -
-LOCAL_SHARED_LIBRARIES += libfmq
-
-
- -

Namespaces

-

HIDL functions and types such as Return<T> and -Void() are declared in namespace ::android::hardware. -The C++ namespace of a package is determined by the package name and version. -For example, a package mypackage with version 1.2 under -hardware/interfaces has the following qualities:

- - - - - diff --git a/en/devices/architecture/hidl-cpp/types.html b/en/devices/architecture/hidl-cpp/types.html deleted file mode 100644 index 1d93df74..00000000 --- a/en/devices/architecture/hidl-cpp/types.html +++ /dev/null @@ -1,323 +0,0 @@ - - - Data Types - - - - - - -

HIDL data declarations generate C++ standard-layout data structures. These -structures can be placed anywhere that feels natural (on the stack, at file or -global scope, or on the heap) and can be composed in the same fashion. Client -code calls HIDL proxy code passing in const references and primitive types, -while the stub and proxy code hides the details of serialization.

- -

Note: At no point is developer-written code -required to explicitly serialize or deserialize data structures.

- -

The table below maps HIDL primitives to C++ data types:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
HIDL TypeC++ TypeHeader/Library
enum
enum class
uint8_t..uint64_t
uint8_t..uint64_t
<stdint.h>
int8_t..int64_t
int8_t..int64_t
<stdint.h>
float
float
double
double
vec<T>
hidl_vec<T>
libhidlbase
T[S1][S2]...[SN]
T[S1][S2]...[SN]
string
hidl_string
libhidlbase
handle
hidl_handle
libhidlbase
opaque
uint64_t
<stdint.h>
-
struct
struct
union
union
fmq_sync
MQDescriptorSync
libhidlbase
fmq_unsync
MQDescriptorUnsync
libhidlbase
- -

The sections below describe data types in more detail.

- -

enum

-

An enum in HIDL becomes an enum in C++. For example:

-
-enum Mode : uint8_t { WRITE = 1 << 0, READ = 1 << 1 };
-
- -

… becomes:

-
-enum class Mode : uint8_t { WRITE = 1, READ = 2 };
-
- -

bitfield<T>

-

bitfield<T> (where T is a user-defined enum) -becomes the underlying type of that enum in C++. In the above example, -bitfield<Mode> becomes uint8_t.

- -

vec<T>

-

The hidl_vec<T> class template is part of -libhidlbase and can be used to pass a vector of any HIDL type with -an arbitrary size. The comparable fixed size container is -hidl_array. A hidl_vec<T> can also be -initialized to point to an external data buffer of type T, using -the hidl_vec::setToExternal() function.

- -

In addition to emitting/inserting the struct appropriately in the generated -C++ header, the use of vec<T> generates some convenience -functions to translate to/from std::vector and bare T -pointers. If the vec<T> is used as a parameter, the function -using it will be overloaded (two prototypes will be generated) to accept and -pass both the HIDL struct and a std::vector<T> type for that -parameter.

- -

array

-

Constant arrays in hidl are represented by the hidl_array class -in libhidlbase. A hidl_array<T, S1, S2, …, -SN> represents an N dimensional fixed size array -T[S1][S2]…[SN].

- -

string

-

The hidl_string class (part of libhidlbase) can be -used to pass strings over HIDL interfaces and is defined in -/system/libhidl/base/include/hidl/HidlSupport.h. The first storage -location in the class is a pointer to its character buffer.

- -

hidl_string knows how to convert to and from -std::string and char* (C-style string) using -operator=, implicit casts, and .c_str() function. -HIDL string structs has the appropriate copy constructors and assignment -operators to:

- - - -

In addition, HIDL strings have conversion constructors so C strings -(char *) and C++ strings (std::string) can be used on -methods that take a HIDL string.

- -

struct

-

A struct in HIDL can contain only fixed-size data types and no -functions. HIDL struct definitions map directly to standard-layout -structs in C++, ensuring that structs have a -consistent memory layout. A struct can include HIDL types, including -handle, string, and vec<T>, that -point to separate variable-length buffers.

- -

handle

- -

WARNING: Addresses of any kind (even physical -device addresses) must never be part of a native handle. Passing this -information between processes is dangerous and makes them susceptible to attack. -Any values passed between processes must be validated before being used to look -up allocated memory within a process. Otherwise, bad handles may cause bad -memory access or memory corruption.

- -

The handle type is represented by the hidl_handle -structure in C++, which is a simple wrapper around a pointer to a -const native_handle_t object (this has been present in Android for -a long time).

- -
-typedef struct native_handle
-{
-    int version;        /* sizeof(native_handle_t) */
-    int numFds;         /* number of file descriptors at &data[0] */
-    int numInts;        /* number of ints at &data[numFds] */
-    int data[0];        /* numFds + numInts ints */
-} native_handle_t;
-
- -

By default, hidl_handle does not take ownership -of the native_handle_t pointer it wraps. It merely exists to safely -store a pointer to a native_handle_t such that it can be used in -both 32- and 64-bit processes.

- -

Scenarios in which the hidl_handle does own its enclosed file -descriptors include:

- - -

hidl_handle provides both implicit and explicit conversions -to/from native_handle_t* objects. The main use for the -handle type in HIDL is to pass file descriptors over HIDL -interfaces. A single file descriptor is therefore represented by a -native_handle_t with no ints and a single -fd. If the client and server live in a different process, the RPC -implementation will automatically take care of the file descriptor to ensure -both processes can operate on the same file.

- -

Although a file descriptor received in a hidl_handle by a -process will be valid in that process, it will not persist beyond the receiving -function (it will be closed once the function returns). A process that wants to -retain persistent access to the file descriptor must dup() the -enclosed file descriptors, or copy the entire hidl_handle object. -

- -

memory

-

The HIDL memory type maps to the hidl_memory class -in libhidlbase, which represents unmapped shared memory. This is -the object that must be passed between processes to share memory in HIDL. To -use shared memory:

- -
    -
  1. Obtain an instance of IAllocator (currently only instance -"ashmem" is available) and use it to allocate shared memory.
    2. -
  2. IAllocator::allocate() returns a hidl_memory -object that can be passed through HIDL RPC and be mapped into a process using -libhidlmemory's mapMemory function.
    3. -
  3. mapMemory returns a reference to an -sp<IMemory> object that can be used to access the memory. -(IMemory and IAllocator are defined in -android.hidl.memory@1.0.)
    4. -
- -

An instance of IAllocator can be used to allocate memory:

-
-#include <android/hidl/allocator/1.0/IAllocator.h>
-#include <android/hidl/memory/1.0/IMemory.h>
-#include <hidlmemory/mapping.h>
-using ::android::hidl::allocator::V1_0::IAllocator;
-using ::android::hidl::memory::V1_0::IMemory;
-using ::android::hardware::hidl_memory;
-....
-  sp<IAllocator> ashmemAllocator = IAllocator::getService("ashmem");
-  ashmemAllocator->allocate(2048, [&](bool success, const hidl_memory& mem) {
-        if (!success) { /* error */ }
-        // now you can use the hidl_memory object 'mem' or pass it around
-  }));
-
- -

Actual changes to the memory must be done through an IMemory -object, either on the side that created mem or on the side that -receives it over HIDL RPC.

- -
-// Same includes as above
-
-sp<IMemory> memory = mapMemory(mem);
-void* data = memory->getPointer();
-memory->update();
-// update memory however you wish after calling update and before calling commit
-data[0] = 42;
-memory->commit();
-// …
-memory->update(); // the same memory can be updated multiple times
-// …
-memory->commit();
-
- -

interface

-

Interfaces can be passed as objects. The word interface can be used -as syntactic sugar for the type android.hidl.base@1.0::IBase; -in addition, the current interface and any imported interfaces will be defined -as a type.

- -

Variables that hold Interfaces should be strong pointers: -sp<IName>. HIDL functions that take interface parameters -will convert raw pointers to strong pointers, causing non-intuitive behavior -(the pointer can be cleared unexpectedly). To avoid problems, always store HIDL -interfaces as a sp<>.

- - - -- cgit v1.2.3