diff options
| author | Android Partner Docs <noreply@android.com> | 2017-08-22 10:41:24 -0700 |
|---|---|---|
| committer | Clay Murphy <claym@google.com> | 2017-08-22 15:01:44 -0700 |
| commit | f16c42333aa6b2de30a344dd68246d4a33d93e7d (patch) | |
| tree | 311af599312cacb21c888aeae828cae59b0d64a1 /en/devices/architecture/hidl-cpp/interfaces.html | |
| parent | 04426e67ca3ee557a0083f9b3c6ba789021bd7a0 (diff) | |
| download | source.android.com-f16c42333aa6b2de30a344dd68246d4a33d93e7d.tar.gz | |
Docs: Changes to source.android.com
- 166080694 Devsite localized content from translation request a3d5a7... by Android Partner Docs <noreply@android.com>
- 166079245 Remove duplicate TOC entry to oob-users.html. by mheco <mheco@google.com>
- 166002955 Update builds for Oreo by Android Partner Docs <noreply@android.com>
- 165977566 Fixing bad conversion by hvm <hvm@google.com>
- 165977199 Edit links to point to public source files in AOSP. by cqn <cqn@google.com>
- 165962883 Add codename to CTS downloads page. by gdimino <gdimino@google.com>
- 165955117 Integration of O branch into mainline. by gdimino <gdimino@google.com>
- 165638251 Update July public Android security bulletin to remove QC... by Android Partner Docs <noreply@android.com>
- 165638198 Update June public Android security bulletin to remove QC... by Android Partner Docs <noreply@android.com>
- 165638174 Update May public Android security bulletin to remove QC ... by Android Partner Docs <noreply@android.com>
- 165638096 Update April public Android security bulletin to remove Q... by Android Partner Docs <noreply@android.com>
- 165528993 Update to Keymaster 2 and remove requirements language by daroberts <daroberts@google.com>
- 165511119 Add Bluetooth verification / debug information by cqn <cqn@google.com>
- 165491345 Fixed link broken by file rename. by cqn <cqn@google.com>
- 165381648 Fixed broken image paths and renamed HCI Requirements file. by cqn <cqn@google.com>
- 165365185 Created high-level Bluetooth directory and added HTML ver... by cqn <cqn@google.com>
- 165335694 Devsite localized content from translation request 66a39c... by Android Partner Docs <noreply@android.com>
- 165246927 Update August 2017 bulletin with CVE-2017-0687 by daroberts <daroberts@google.com>
PiperOrigin-RevId: 166080694
Change-Id: I2d3a8d77fa6a66c2099f13ba2e864545328fd17a
Diffstat (limited to 'en/devices/architecture/hidl-cpp/interfaces.html')
| -rw-r--r-- | en/devices/architecture/hidl-cpp/interfaces.html | 271 |
1 files changed, 271 insertions, 0 deletions
diff --git a/en/devices/architecture/hidl-cpp/interfaces.html b/en/devices/architecture/hidl-cpp/interfaces.html new file mode 100644 index 00000000..5047e8d0 --- /dev/null +++ b/en/devices/architecture/hidl-cpp/interfaces.html @@ -0,0 +1,271 @@ +<html devsite> + <head> + <title>Interfaces</title> + <meta name="project_path" value="/_project.yaml" /> + <meta name="book_path" value="/_book.yaml" /> + </head> + <body> + <!-- + Copyright 2017 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. + --> + +<p>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:</p> + +<ul> +<li><strong>Servers</strong> implement interfaces.</li> +<li><strong>Clients</strong> call methods on interfaces.</li> +</ul> + +<p>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.</p> + +<h2 id=server>Server implementation</h2> +<p>A server implementing the <code>IFoo</code> interface must include the +<code>IFoo</code> header file that was autogenerated:</p> + +<pre class="prettyprint"> +#include <android/hardware/samples/1.0/IFoo.h> +</pre> + +<p>The header is automatically exported by the shared library of the +<code>IFoo</code> interface to link against. Example <code>IFoo.hal</code>:</p> + +<pre class="prettyprint"> +// IFoo.hal +interface IFoo { + someMethod() generates (vec<uint32_t>); + ... +} +</pre> + +<p>Example skeleton for a server implementation of the IFoo interface:</p> + +<pre class="prettyprint"> +// 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(); + } + ... +}; +</pre> + +<p>To make the implementation of a server interface available to a client, you +can:</p> + +<ol> +<li><strong>Register</strong> the interface implementation with the +<code>hwservicemanager</code> (see details below), +<br><br> +OR<br><br> +</li> +<li><strong>Pass</strong> the interface implementation as an argument of an +interface method (for detals, see <a href="#asynchronous">Asynchronous +callbacks</a>).</li> +</ol> + +<p>When registering the interface implementation, the +<code>hwservicemanager</code> 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 +<code>android.hidl.manager@1.0::IServiceManager</code>.</p> + +<p>Each auto-generated HIDL interface header file (such as <code>IFoo.h</code>) +has a <code>registerAsService()</code> method that can be used to register the +interface implementation with the <code>hwservicemanager</code>. The only +required argument is the name of the interface implementations as clients will +use this name to retrieve the interface from the <code>hwservicemanager</code> +later:</p> + +<pre class="prettyprint"> +::android::sp<IFoo> myFoo = new FooImpl(); +::android::sp<IFoo> myFoo = new FooAnotherImpl(); +myFoo->registerAsService(); +mySecondFoo->registerAsService("another_foo"); +</pre> + +<p>The <code>hwservicemanager</code> treats the combination of +<code>[package@version::interface, instance_name]</code> as unique to enable +different interfaces (or different versions of the same interface) to register +with identical instance names without conflicts. If you call +<code>registerAsService()</code> with the exact same package version, interface, +and instance name, the <code>hwservicemanager</code> drops its reference to the +previously registered service and uses the new one.</p> + +<h2 id=client>Client implementation</h2> +<p>Just as the server does, a client must <code>#include</code> every interface +it refers to:</p> + +<pre class="prettyprint"> +#include <android/hardware/samples/1.0/IFoo.h> +</pre> + +<p>A client can obtain an interface in two ways:</p> + +<ul> +<li>Through <code>I<InterfaceName>::getService</code> (via the +<code>hwservicemanager</code>)</li> +<li>Through an interface method</li> +</ul> + +<p>Each autogenerated interface header file has a static <code>getService</code> +method that can be used to retrieve a service instance from the +<code>hwservicemanager</code>:</p> + +<pre class="prettyprint"> +// getService will return nullptr if the service can't be found +sp<IFoo> myFoo = IFoo::getService(); +sp<IFoo> myAlternateFoo = IFoo::getService("another_foo"); +</pre> + +<p>Now the client has an an <code>IFoo</code> 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 <code>getService</code> on an +<code>IFoo</code> object included from version <code>1.0 </code>of the package, +the <code>hwservicemanager</code> returns a server implementation only if that +implementation is compatible with <code>1.0</code> clients. In practice, this +means only server implementations with version <code>1.n</code> (version +<code>x.(y+1)</code> of an interface must extend (inherit from) +<code>x.y</code>).</p> + +<p>Additionally the method <code>castFrom</code> 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 <code>nullptr</code> is +returned.</p> + +<pre class="prettyprint"> +sp<V1_0::IFoo> foo1_0 = V1_0::IFoo::getService(); +sp<V1_1::IFoo> foo1_1 = V1_1::IFoo::castFrom(foo1_0); +</pre> + +<h2 id=asynchronous>Asynchronous callbacks</h2> +<p>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.</p> + +<p>Example interface file <code>IFooCallback.hal</code>:</p> + +<pre class="prettyprint"> +package android.hardware.samples@1.0; +interface IFooCallback { + sendEvent(uint32_t event_id); + sendData(hidl_vec<uint8_t> data); +} +</pre> + +<p>Example new method in <code>IFoo</code> that takes an +<code>IFooCallback</code> parameter:</p> + +<pre class="prettyprint"> +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); +}; +</pre> + +<p>The <em>client</em> using the <code>IFoo</code> interface is the +<em>server</em> of the <code>IFooCallback</code> interface; it provides an +implementation of <code>IFooCallback</code>:</p> + +<pre class="prettyprint"> +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 + } +}; +</pre> + +<p>It can also simply pass that over an existing instance of the +<code>IFoo</code> interface:</p> +<pre class="prettyprint"> +sp<IFooCallback> myFooCallback = new FooCallback(); +myFoo.registerCallback(myFooCallback); +</pre> + +<p>The server implementing <code>IFoo</code> receives this as an +<code>sp<IFooCallback></code> object. It can store the callback, and call +back into the client whenever it wants to use this interface.</p> + +<h2 id=death>Death recipients</h2> +<p>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 (<code>isOK()</code> will return false). The only way to +recover from such a failure is to request a new instance of the service by +calling <code>I<InterfaceName>::getService()</code>. This works only if +the process that crashed has restarted and re-registered its services with the +<code>servicemanager</code> (which is generally true for HAL implementations). +</p> + +<p>Instead of dealing with this reactively, clients of an interface can also +register a <em>death recipient</em> to get a notification when a service dies. +To register for such notifications on a retrieved <code>IFoo</code> interface, a +client can do the following:</p> + +<pre class="prettyprint"> +foo->linkToDeath(recipient, 1481 /* cookie */); +</pre> + +<p>The <code>recipient</code> parameter must be an implementation of the +<code>android::hardware::hidl_death_recipient</code> interface provided by HIDL, +which contains a single method <code>serviceDied()</code> that will be called +from a thread in the RPC threadpool when the process hosting the interface dies: +</p> + +<pre class="prettyprint"> +class MyDeathRecipient : 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 + } +} +</pre> + +<p>The <code>cookie</code> parameter contains the cookie that was passed in with +<code>linkToDeath()</code>, whereas the <code>who</code> parameter contains a +weak pointer to the object representing the service in the client. With the +sample call given above, <code>cookie</code> equals 1481, and <code>who</code> +equals <code>foo</code>.</p> + +<p>It's also possible to unregister a death recipient after registering it:</p> + +<pre class="prettyprint"> +foo->unlinkToDeath(recipient); +</pre> + + </body> +</html> |