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-java | |
| 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-java')
| -rw-r--r-- | en/devices/architecture/hidl-java/constants.html | 87 | ||||
| -rw-r--r-- | en/devices/architecture/hidl-java/index.html | 186 | ||||
| -rw-r--r-- | en/devices/architecture/hidl-java/interfaces.html | 151 | ||||
| -rw-r--r-- | en/devices/architecture/hidl-java/types.html | 161 |
4 files changed, 585 insertions, 0 deletions
diff --git a/en/devices/architecture/hidl-java/constants.html b/en/devices/architecture/hidl-java/constants.html new file mode 100644 index 00000000..30c55b95 --- /dev/null +++ b/en/devices/architecture/hidl-java/constants.html @@ -0,0 +1,87 @@ +<html devsite> + <head> + <title>Exporting Constants</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>In cases where an interface is not Java-compatible (because it uses unions +for example) it may still be desirable to export the constants (enum values) to +the Java world. This scenario is supported by <code>hidl-gen -Ljava-constants +…</code> which extracts annotated enum declarations from the interface +file(s) in a package and produces a java library named +<code>[PACKAGE-NAME]-V[PACKAGE-VERSION]-java-constants</code>. Annotate each +enum declaration to be exported as follows:</p> + +<pre class="prettyprint"> +@export +enum Foo : int32_t { + SOME_VALUE, + SOME_OTHER_VALUE, +}; +</pre> + +<p>If necessary, the name under which this type is exported to the Java world +can be different from that chosen in the interface declaration by adding the +annotation-parameter <code>name</code>:</p> + +<pre class="prettyprint"> +@export(name="JavaFoo") +enum Foo : int32_t { + SOME_VALUE, + SOME_OTHER_VALUE, +}; +</pre> + +<p>If Java conventions or personal preference ask for a common prefix to be +added to the enum type's values, use the annotation-parameter +<code>value_prefix</code>:</p> + +<pre class="prettyprint"> +// File "types.hal". + +package android.hardware.bar@1.0; + +@export(name="JavaFoo", value_prefix="JAVA_") +enum Foo : int32_t { + SOME_VALUE, + SOME_OTHER_VALUE, +}; +</pre> + +<p>The resulting Java class appears as follows:</p> + +<pre class="prettyprint"> +package android.hardware.bar.V1_0; + +public class Constants { + public final class JavaFoo { + public static final int JAVA_SOME_VALUE = 0; + public static final int JAVA_SOME_OTHER_VALUE = 1; + }; +}; +</pre> + +<p>Finally, Java type declaration for enum types declared in +<code>types.hal</code> are grouped inside a class <code>Constants</code> in the +given package. Enum types declared as children of an interface will be grouped +under that interface's Java class declaration.</p> + + </body> +</html> diff --git a/en/devices/architecture/hidl-java/index.html b/en/devices/architecture/hidl-java/index.html new file mode 100644 index 00000000..3b94247e --- /dev/null +++ b/en/devices/architecture/hidl-java/index.html @@ -0,0 +1,186 @@ +<html devsite> + <head> + <title>HIDL Java</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>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 <code>hardware/libhardware</code>. HIDL replaces these +HAL interfaces with stable, versioned interfaces, which can be in Java +(described below) or as client- and server-side HIDL interfaces in +<a href="/devices/architecture/hidl-cpp/index.html">C++</a>.</p> + +<p>HIDL interfaces are intended to be used primarily from native code, and as a +result HIDL is focused on the auto-generation of efficient code in C++. However, +HIDL interfaces must also be able to be used directly from Java as some Android +subsystems (such as Telephony) will most likely have Java HIDL interfaces.</p> + +<p>The pages in this section describe the Java frontend for HIDL interfaces, +detail how to create, register, and use services, and explain how HALs and HAL +clients written in Java interact with the HIDL RPC system.</p> + +<h2 id=client>Being a client</h2> +<p>To access an interface IFoo in package <code>android.hardware.foo</code> +version 1.0 that is registered as service name <code>foo-bar</code>:</p> + +<ol> +<li>Add libraries: + +<ul> +<li>Add the following to Android.mk: +<pre class="prettyprint">LOCAL_JAVA_LIBRARIES += android.hardware.foo-V1.0-java</pre> + +<strong>OR</strong><br> +</li> + +<li>Add the following to Android.bp: +<pre class="prettyprint"> +shared_libs: [ + /* … */ + "android.hardware.foo-V1.0-java", +], +</pre> +The static version of the library is also available as +<code>android.hardware.foo-V1.0-java-static</code>.</li> +</ul> +</li> +<li>Add the following to your Java file: +<pre class="prettyprint"> +import android.hardware.foo.V1_0.IFoo; +... +IFoo server = IFoo.getService(); // throws exception if not available +IFoo anotherServer = IFoo.getService("second_impl"); +server.doSomething(…); +</pre> +</li> +</ol> + +<h2 id=service>Providing a service</h2> +<p>Framework code in Java may need to serve interfaces to receive asynchronous +callbacks from HALs.</p> + +<p class=warning><strong>Warning</strong>: Do not implement a driver (HAL) in +Java. We strongly recommend you implement drivers in C++.</p> + +<p>For interface <code>IFooCallback</code> in version 1.0 of package +<code>android.hardware.foo</code>, you can implement your interface in Java +using the following steps:</p> + +<ol> +<li>Define your interface in HIDL.</li> +<li>Open <code>/tmp/android/hardware/foo/IFooCallback.java</code> as a +reference.</li> +<li>Create a new module for your Java implementation.</li> +<li>Examine the abstract class +<code>android.hardware.foo.V1_0.IFooCallback.Stub</code>, then write a new class +to extend it and implement the abstract methods.</li> +</ol> + +<h3 id=autogen>Viewing auto-generated files</h3> +<p>To view the automatically-generated files, run:</p> +<pre class="prettyprint"> +hidl-gen -o /tmp -Ljava \ + -randroid.hardware:hardware/interfaces \ + -randroid.hidl:system/libhidl/transport android.hardware.foo@1.0 +</pre> + +<p>These commands generate the directory +<code>/tmp/android/hardware/foo/1.0</code>. For the file +<code>hardware/interfaces/foo/1.0/IFooCallback.hal</code>, this generates the +file <code>/tmp/android/hardware/foo/1.0/IFooCallback.java</code>, which +encapsulates the Java interface, the proxy code, and the stubs (both proxy and +stubs conform to the interface).</p> + +<p><code>-Lmakefile</code> generates the rules that run this command at build +time and allow you to include +<code>android.hardware.foo-V1.0-java(-static)?</code> and link against the +appropriate files. A script that automatically does this for a project full of +interfaces can be found at <code>hardware/interfaces/update-makefiles.sh</code>. +The paths in this example are relative; hardware/interfaces can be a temporary +directory under your code tree to enable you to develop a HAL prior to +publishing it.</p> + +<h2 id=service>Running a service</h2> +<p>The HAL provides an interface <code>IFoo</code>, which must make asynchronous +callbacks to the framework over interface <code>IFooCallback</code>. The +<code>IFooCallback</code> interface is not registered by name as a discoverable +service; instead, <code>IFoo</code> must contain a method such as +<code>setFooCallback(IFooCallback x)</code>.</p> + +<p>To set up <code>IFooCallback</code> from version 1.0 of package +<code>android.hardware.foo</code>, add +<code>android.hardware.foo-V1.0-java</code> to <code>Android.mk</code>. The code +to run the service is:</p> + +<pre class="prettyprint"> +import android.hardware.foo.V1_0.IFoo; +import android.hardware.foo.V1_0.IFooCallback.Stub; +.... +class FooCallback extends IFoo.Stub { + // implement methods +} +.... +// Get the service you will be receiving callbacks from. +// This also starts the threadpool for your callback service. +IFoo server = IFoo.getService(); // throws exception if not available +.... +// This must be a persistent instance variable, not local, +// to avoid premature garbage collection. +FooCallback mFooCallback = new FooCallback(); +.... +// Do this once to create the callback service and tell the "foo-bar" service +server.setFooCallback(mFooCallback); +</pre> + +<h2 id=extensions>Interface extensions</h2> +<p>Assuming a given service implements an interface <code>IFoo</code> across all +devices, it's possible that on a particular device the service may provide +additional capabilities implemented in an interface extension +<code>IBetterFoo</code>, i.e.:</p> + +<pre class="prettyprint"> +interface IFoo { + ... +}; + +interface IBetterFoo extends IFoo { + ... +}; +</pre> + +<p>Calling code aware of the extended interface can use the +<code>castFrom()</code> Java method to safely cast the base interface to the +extended interface:</p> + +<pre class="prettyprint"> +IFoo baseService = Foo.getService(); +IBetterFoo extendedService = IBetterFoo.castFrom(baseService); +if (extendedService != null) { + // The service implements the extended interface. +} else { + // The service only implements the base interface. +} +</pre> + + </body> +</html> diff --git a/en/devices/architecture/hidl-java/interfaces.html b/en/devices/architecture/hidl-java/interfaces.html new file mode 100644 index 00000000..024b64ce --- /dev/null +++ b/en/devices/architecture/hidl-java/interfaces.html @@ -0,0 +1,151 @@ +<html devsite> + <head> + <title>Interface Methods & Errors</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>This section details interface methods and errors.</p> + +<h2 id=void>Void methods</h2> +<p>Methods that do not return results are translated into Java methods that +return <code>void</code>. For example, the HIDL declaration:</p> + +<pre class="prettyprint"> +doThisWith(float param); +</pre> + +<p>… becomes:</p> + +<pre class="prettyprint"> +void doThisWith(float param); +</pre> + +<h2 id=single-result>Single-result methods</h2> +<p>Methods that return a single result are translated into their Java +equivalents also returning a single result. For example, the following:</p> + +<pre class="prettyprint"> +doQuiteABit(int32_t a, int64_t b, + float c, double d) generates (double something); +</pre> + +<p>… becomes:</p> + +<pre class="prettyprint"> +double doQuiteABit(int a, long b, float c, double d); +</pre> + + +<h2 id=multiple-result>Multiple-result methods</h2> +<p>For each method that returns more than one result, a callback class is +generated that supplies all the results in its <code>onValues</code> method. +That callback acts as an additional parameter to the method. For example, the +following:</p> + +<pre class="prettyprint"> +oneProducesTwoThings(SomeEnum x) generates (double a, double b); +</pre> + +<p>… becomes:</p> + +<pre class="prettyprint"> +public interface oneProducesTwoThingsCallback { + public void onValues(double a, double b); +} +void oneProducesTwoThings(byte x, oneProducesTwoThingsCallback cb); +</pre> + +<p>A caller of <code>oneProducesTwoThings()</code> would typically use an +anonymous inner class or lambda to implement the callback locally:</p> + +<pre class="prettyprint"> +someInstanceOfFoo.oneProducesTwoThings( + 5 /* x */, + new IFoo.oneProducesTwoThingsCallback() { + @Override + void onValues(double a, double b) { + // do something interesting with a and b. + ... + }}); +</pre> + +<p>or:</p> + +<pre class="prettyprint"> +someInstanceOfFoo.oneProducesTwoThings(5 /* x */, + (a, b) -> a > 3.0 ? f(a, b) : g(a, b))); +</pre> + +<p>You can also define a class to use as a callback … </p> + +<pre class="prettyprint"> +class MyCallback implements oneProducesTwoThingsCallback { + public void onValues(double a, double b) { + // do something interesting with a and b. + } +} +</pre> + +<p>… and pass an instance of <code>MyCallback</code> as the third parameter to +<code>oneProducesTwoThings()</code>.</p> + +<h2 id=errors>Transport errors and death recipients</h2> +<p>Because service implementations can run in a different process, in some cases +the client can stay alive even when the process implementing an interface dies. +Calls on an interface object hosted in a dead process fail with a transport +error (a runtime exception thrown by the called method). Recovery from such a +failure is possible by requesting a new instance of the service by calling +<code>I<InterfaceName>.getService()</code>. However, this method works +only if the process that crashed has restarted and re-registered its services +with the servicemanager (which is generally true for HAL implementations).</p> + +<p>Clients of an interface can also register a <em>death recipient</em> to get a +notification when a service dies. Transport errors can still occur if a call is +made just as the server 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 +interface <code>HwBinder.DeathRecipient</code> provided by HIDL. The interface +contains a single method <code>serviceDied()</code> that is called when the +process hosting the interface dies.</p> + +<pre class="prettyprint"> +final class DeathRecipient implements HwBinder.DeathRecipient { + @Override + public void serviceDied(long cookie) { + // Deal with service going away + } +} +</pre> + +<p>The <code>cookie</code> parameter contains the cookie that was passed with +the call to <code>linkToDeath()</code>. It's also possible to unregister a death +recipient after registering it using:</p> + +<pre class="prettyprint"> +foo.unlinkToDeath(recipient); +</pre> + + </body> +</html> diff --git a/en/devices/architecture/hidl-java/types.html b/en/devices/architecture/hidl-java/types.html new file mode 100644 index 00000000..8cc2d258 --- /dev/null +++ b/en/devices/architecture/hidl-java/types.html @@ -0,0 +1,161 @@ +<html devsite> + <head> + <title>Data Types</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>Given a HIDL interface file, the Java HIDL backend generates Java interfaces, +Stub, and Proxy code. It supports all scalar HIDL types +([<code>u</code>]<code>int</code>{<code>8,16,32,64}_t, float, double,</code> and +<code>enum</code>s), as well as strings, interfaces, struct types, and arrays +and vectors of supported HIDL types. The Java HIDL backend <strong>does NOT +support union types, native handles, shared memory, and fmq types</strong>.</p> + +<p>As Java runtime does not support the concept of unsigned integers natively, +all unsigned types (and enums based on them) are silently treated as their +signed equivalents, i.e. <code>uint32_t</code> becomes an <code>int</code> in +the Java interface. No value conversion is performed; the implementor on the +Java side must use the signed values as if they were unsigned.</p> + +<h2 id=enum>Enums</h2> +<p>Enums do not generate Java enum classes but are instead translated into inner +classes containing a static constant definition for each enum case. If the enum +class derives from some other enum class, it inherits that class's storage type. +Enumerations based on an unsigned integer type are rewritten into their signed +equivalent.</p> + +<p>For example, a <code>SomeBaseEnum</code> with a type of +<code>uint8_t</code>:</p> + +<pre class="prettyprint"> +enum SomeBaseEnum : uint8_t { foo = 3 }; +enum SomeEnum : SomeBaseEnum { + quux = 33, + goober = 127 +}; +</pre> + +<p>… becomes:</p> + +<pre class="prettyprint"> +public final class SomeBaseEnum { public static final byte foo = 3; } +public final class SomeEnum { + public static final byte foo = 3; + public static final byte quux = 33; + public static final byte goober = 127; +} +</pre> + +<p>And:</p> + +<pre class="prettyprint"> +enum SomeEnum : uint8_t { + FIRST_CASE = 10, + SECOND_CASE = 192 +}; +</pre> + +<p>… is rewritten as:</p> + +<pre class="prettyprint"> +public final class SomeEnum { + static public final byte FIRST_CASE = 10; // no change + static public final byte SECOND_CASE = -64; +} +</pre> + +<h2 id=string>Strings</h2> +<p><code>String</code>s in Java are utf-8 or utf-16 but are converted to utf-8 +as the common HIDL type when transported. Additionally, a <code>String</code> +must not be null when passed into HIDL.</p> + +<h2 id=array-vect>Arrays and vectors</h2> +<p>Arrays are translated into Java arrays and vectors are translated into +<code>ArrayList<T></code> where T is the appropriate object type, possibly +wrapping scalar types such as <code>vec<int32_t> => +ArrayList<Integer></code>). For example:</p> + +<pre class="prettyprint"> +takeAnArray(int32_t[3] array); +returnAVector() generates (vec<int32_t> result); +</pre> + +<p>… becomes:</p> + +<pre class="prettyprint"> +void takeAnArray(int[] array); +ArrayList<Integer> returnAVector(); +</pre> + +<h2 id=struct>Structures</h2> +<p>Structures are translated into Java classes with a similar layout. For +example:</p> + +<pre class="prettyprint"> +struct Bar {vec<bool> someBools; + }; + struct Foo { + int32_t a; + int8_t b; + float[10] c; + Bar d; + }; +</pre> + +<p>… becomes:</p> + +<pre class="prettyprint"> +class Bar { + public final ArrayList<Boolean> someBools = new ArrayList(); +}; +class Foo { + public int a; + public byte b; + public final float[] c = new float[10]; + public final Bar d = new Bar(); +} +</pre> + +<h2 id=declared>Declared types</h2> +<p>Each top-level type declared in <code>types.hal</code> gets its own .java +output file (as required by Java). For example, the following +<code>types.hal</code> file results in two extra files being created (Foo.java +and Bar.java):</p> + +<pre class="prettyprint"> +struct Foo { + ... +}; + +struct Bar { + ... + + struct Baz { + }; + + ... +}; +</pre> + +<p>The definition of Baz lives in a static inner class of Bar (in Bar.java).</p> + + </body> +</html> |