diff options
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 | 191 | ||||
-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, 0 insertions, 590 deletions
diff --git a/en/devices/architecture/hidl-java/constants.html b/en/devices/architecture/hidl-java/constants.html deleted file mode 100644 index 30c55b95..00000000 --- a/en/devices/architecture/hidl-java/constants.html +++ /dev/null @@ -1,87 +0,0 @@ -<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 deleted file mode 100644 index f98d1b64..00000000 --- a/en/devices/architecture/hidl-java/index.html +++ /dev/null @@ -1,191 +0,0 @@ -<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_STATIC_JAVA_LIBRARIES += android.hardware.foo-V1.0-java</pre> - -<strong>OR</strong><br> -</li> - -<li>Add the following to Android.bp: -<pre class="prettyprint"> -static_libs: [ - /* … */ - "android.hardware.foo-V1.0-java", -], -</pre> -</li> -</ul> -</li> -<li>Add the following to your Java file: -<pre class="prettyprint"> -import android.hardware.foo.V1_0.IFoo; -... -// retry to wait until the service starts up if it is in the manifest -IFoo server = IFoo.getService(true /* retry */); // throws NoSuchElementException if not available -IFoo anotherServer = IFoo.getService("second_impl", true /* retry */); -server.doSomething(…); -</pre> -<p class=caution><strong>Warning</strong>: Java <code>getService</code> with no arguments will not -wait for the service to start.</p> -</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 class=warning><strong>Warning</strong>: Java drivers must be in a separate -process from their clients (same process communication is not supported).</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</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 IFooCallback.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(true /* retry */); // throws NoSuchElementException 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 = IFoo.getService(true /* retry */); // throws NoSuchElementException if not available -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 deleted file mode 100644 index 024b64ce..00000000 --- a/en/devices/architecture/hidl-java/interfaces.html +++ /dev/null @@ -1,151 +0,0 @@ -<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 deleted file mode 100644 index 8cc2d258..00000000 --- a/en/devices/architecture/hidl-java/types.html +++ /dev/null @@ -1,161 +0,0 @@ -<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> |