en/devices/architecture/hidl-cpp/packages.html - platform/docs/source.android.com - Git at Google

 <html devsite>
   <head>
     <title>Packages</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 class=note><strong>Note:</strong> This section uses sample <code>.hal</code>
 files to illustrate how HIDL language constructs map to C++.</p>

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

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

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

 <pre class="prettyprint">
 package android.hardware.samples@1.0;
 interface IFoo {
     struct Foo {
        int64_t someValue;
        handle  myHandle;
     };

     someMethod() generates (vec&lt;uint32_t&gt;);
     anotherMethod(Foo foo) generates (int32_t ret);
 };
 </pre>

 <h2 id=generated-files>Generated files</h2>

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

 <p><img src="../images/treble_cpp_compiler_generated_files.png"></p>
 <p><strong>Figure 1.</strong> Files generated by compiler.</p>

 <ul>
 <li><code><strong>IFoo.h</code></strong>. Describes the pure <code>IFoo</code>
 interface in a C++ class; it contains the methods and types defined in the
 <code>IFoo</code> interface in the <code>IFoo.hal</code> file, translated to C++
 types where necessary. <strong>Does not contain</strong> details related to the
 RPC mechanism (e.g., <code>HwBinder</code>) used to implement this interface.
 The class is namespaced with the package and version, e.g.
 <code>::android::hardware::samples::IFoo::V1_0</code>. Both clients and servers
 include this header: Clients for calling methods on it and servers for
 implementing those methods.</li>
 <li><code><strong>IHwFoo.h</code></strong>. Header file that contains
 declarations for functions that serialize data types used in the interface.
 Developers should never include his header directly (it does not contain any
 classes).</li>
 <li><code><strong>BpFoo.h</code></strong>. A class that inherits from
 <code>IFoo</code> and describes the <code>HwBinder</code> proxy (client-side)
 implementation of the interface. Developers should never refer to this class
 directly.</li>
 <li><code><strong>BnFoo.h</code></strong>.<strong> </strong>A class that holds a
 reference to an <code>IFoo</code> implementation and describes the
 <code>HwBinder</code> stub (server-side) implementation of the interface.
 Developers should never refer to this class directly.</li>
 <li><code><strong>FooAll.cpp</code></strong>. A class that contains the
 implementations for both the <code>HwBinder</code> proxy and the
 <code>HwBinder</code> stub. When a client calls an interface method, the proxy
 automatically marshals the arguments from the client and sends the transaction
 to the binder kernel driver, which delivers the transaction to the stub on the
 other side (which then calls the actual server implementation).</li>
 </ul>

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

 <p class=note><strong>Note</strong>: HwBinder is only one possible transport;
 new transports may be added in the future.</p>

 <h2 id=link-libraries>Linking to shared libraries</h2>
 <p>A client or server that uses any interface in a package must include the
 shared library of that package in <strong>one (1)</strong> of the following
 locations:</p>

 <ul>
 <li>In <strong>Android.mk</strong>:
 <pre class="prettyprint">
 LOCAL_SHARED_LIBRARIES += android.hardware.samples@1.0
 </pre>
 </li>

 <li>In <strong>Android.bp</strong>:
 <pre class="prettyprint">
 shared_libs: [
     /* ... */
     "android.hardware.samples@1.0",
 ],
 </pre>
 </li>
 </ul>

 <p>For specific libraries:</p>

 <table>

 <tr>
 <th><code>libhidlbase</code></th>
 <td>Includes standard HIDL data-types. Unless your interface consists only of
 primitives that map directly to C++ primitives, you must also link this library:
 <pre class="prettyprint">
 LOCAL_SHARED_LIBRARIES += libhidlbase
 </pre>
 </td>
 </tr>

 <tr>
 <th><code>libhidltransport</code></th>
 <td>Handles the transport of HIDL calls over different RPC/IPC mechanisms. You
 must always link this library:
 <pre class="prettyprint">
 LOCAL_SHARED_LIBRARIES += libhidltransport
 </pre>
 </td>
 </tr>

 <tr>
 <th><code>libhwbinder</code></th>
 <td>You must also link to this library:
 <pre class="prettyprint">
 LOCAL_SHARED_LIBRARIES += libhwbinder
 </pre>
 </td>
 </tr>

 <tr>
 <th><code>libfmq</code></th>
 <td>To use Fast Message Queue IPC, you must also link to this library.
 <pre class="prettyprint">
 LOCAL_SHARED_LIBRARIES += libfmq
 </pre>
 </td>
 </tr>

 </tbody>
 </table>

 <h2 id=namespaces>Namespaces</h2>
 <p>HIDL functions and types such as <code>Return&lt;T&gt;</code> and
 <code>Void()</code> are declared in namespace <code>::android::hardware</code>.
 The C++ namespace of a package is determined by the package name and version.
 For example, a package <strong>mypackage</strong> with version 1.2 under
 <code>hardware/interfaces</code> has the following qualities:</p>

 <ul>
 <li><strong>C++ namespace</strong> is
 <code>::android::hardware::mypackage::V1_2</code></li>
 <li><strong>Fully qualified name </strong>of <code>IMyInterface</code> in that
 package is: <code>::android::hardware::mypackage::V1_2::IMyInterface</code>.
 (<code>IMyInterface</code> is an identifier, not part of the namespace).</li>
 <li><strong>Types</strong> defined in the package's <code>types.hal</code> file
 are identified as:
 <code>::android::hardware::mypackage::V1_2::MyPackageType</code></li>
 </ul>

   </body>
 </html>
	<html devsite>
	<head>
	<title>Packages</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 class=note><strong>Note:</strong> This section uses sample <code>.hal</code>
	files to illustrate how HIDL language constructs map to C++.</p>

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

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

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

	<pre class="prettyprint">
	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);
	};
	</pre>

	<h2 id=generated-files>Generated files</h2>

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

	<p><img src="../images/treble_cpp_compiler_generated_files.png"></p>
	<p><strong>Figure 1.</strong> Files generated by compiler.</p>

	<ul>
	<li><code><strong>IFoo.h</code></strong>. Describes the pure <code>IFoo</code>
	interface in a C++ class; it contains the methods and types defined in the
	<code>IFoo</code> interface in the <code>IFoo.hal</code> file, translated to C++
	types where necessary. <strong>Does not contain</strong> details related to the
	RPC mechanism (e.g., <code>HwBinder</code>) used to implement this interface.
	The class is namespaced with the package and version, e.g.
	<code>::android::hardware::samples::IFoo::V1_0</code>. Both clients and servers
	include this header: Clients for calling methods on it and servers for
	implementing those methods.</li>
	<li><code><strong>IHwFoo.h</code></strong>. Header file that contains
	declarations for functions that serialize data types used in the interface.
	Developers should never include his header directly (it does not contain any
	classes).</li>
	<li><code><strong>BpFoo.h</code></strong>. A class that inherits from
	<code>IFoo</code> and describes the <code>HwBinder</code> proxy (client-side)
	implementation of the interface. Developers should never refer to this class
	directly.</li>
	<li><code><strong>BnFoo.h</code></strong>.<strong> </strong>A class that holds a
	reference to an <code>IFoo</code> implementation and describes the
	<code>HwBinder</code> stub (server-side) implementation of the interface.
	Developers should never refer to this class directly.</li>
	<li><code><strong>FooAll.cpp</code></strong>. A class that contains the
	implementations for both the <code>HwBinder</code> proxy and the
	<code>HwBinder</code> stub. When a client calls an interface method, the proxy
	automatically marshals the arguments from the client and sends the transaction
	to the binder kernel driver, which delivers the transaction to the stub on the
	other side (which then calls the actual server implementation).</li>
	</ul>

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

	<p class=note><strong>Note</strong>: HwBinder is only one possible transport;
	new transports may be added in the future.</p>

	<h2 id=link-libraries>Linking to shared libraries</h2>
	<p>A client or server that uses any interface in a package must include the
	shared library of that package in <strong>one (1)</strong> of the following
	locations:</p>

	<ul>
	<li>In <strong>Android.mk</strong>:
	<pre class="prettyprint">
	LOCAL_SHARED_LIBRARIES += android.hardware.samples@1.0
	</pre>
	</li>

	<li>In <strong>Android.bp</strong>:
	<pre class="prettyprint">
	shared_libs: [
	/* ... */
	"android.hardware.samples@1.0",
	],
	</pre>
	</li>
	</ul>

	<p>For specific libraries:</p>

	<table>

	<tr>
	<th><code>libhidlbase</code></th>
	<td>Includes standard HIDL data-types. Unless your interface consists only of
	primitives that map directly to C++ primitives, you must also link this library:
	<pre class="prettyprint">
	LOCAL_SHARED_LIBRARIES += libhidlbase
	</pre>
	</td>
	</tr>

	<tr>
	<th><code>libhidltransport</code></th>
	<td>Handles the transport of HIDL calls over different RPC/IPC mechanisms. You
	must always link this library:
	<pre class="prettyprint">
	LOCAL_SHARED_LIBRARIES += libhidltransport
	</pre>
	</td>
	</tr>

	<tr>
	<th><code>libhwbinder</code></th>
	<td>You must also link to this library:
	<pre class="prettyprint">
	LOCAL_SHARED_LIBRARIES += libhwbinder
	</pre>
	</td>
	</tr>

	<tr>
	<th><code>libfmq</code></th>
	<td>To use Fast Message Queue IPC, you must also link to this library.
	<pre class="prettyprint">
	LOCAL_SHARED_LIBRARIES += libfmq
	</pre>
	</td>
	</tr>

	</tbody>
	</table>

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

	<ul>
	<li><strong>C++ namespace</strong> is
	<code>::android::hardware::mypackage::V1_2</code></li>
	<li><strong>Fully qualified name </strong>of <code>IMyInterface</code> in that
	package is: <code>::android::hardware::mypackage::V1_2::IMyInterface</code>.
	(<code>IMyInterface</code> is an identifier, not part of the namespace).</li>
	<li><strong>Types</strong> defined in the package's <code>types.hal</code> file
	are identified as:
	<code>::android::hardware::mypackage::V1_2::MyPackageType</code></li>
	</ul>

	</body>
	</html>