From 91556d2de8081ff5325dfe6aa7c2995e0d039281 Mon Sep 17 00:00:00 2001 From: Android Partner Docs Date: Mon, 22 Jan 2018 12:11:12 -0800 Subject: Docs: Changes to source.android.com - 182815898 Add persistent link to China mirror on home page by Clay Murphy - 182789083 Devsite localized content from translation request 46370c... by Android Partner Docs - 182789077 Devsite localized content from translation request 6133ed... by Android Partner Docs - 182597042 Updating English for translation fixes by Heidi von Markham - 182578621 Add verification HTML page for Search Console to try and ... by Christina Nguyen - 182560649 Devsite localized content from translation request ac6bc4... by Android Partner Docs - 182560639 Devsite localized content from translation request 4b21f6... by Android Partner Docs - 182560630 Devsite localized content from translation request 907a58... by Android Partner Docs - 182559954 Devsite localized content from translation request 277f34... by Android Partner Docs - 182559754 Devsite localized content from translation request 9f4f3f... by Android Partner Docs - 182559744 Devsite localized content from translation request 34815b... by Android Partner Docs PiperOrigin-RevId: 182815898 Change-Id: I1fe7673e8fe6dd116e3f2ac0e6283a953e22510b --- en/devices/architecture/hidl/fmq.html | 49 ++++++++++++++++------------ en/devices/architecture/hidl/types.html | 32 +++++++++--------- en/devices/architecture/hidl/versioning.html | 24 +++++++------- 3 files changed, 58 insertions(+), 47 deletions(-) (limited to 'en/devices') diff --git a/en/devices/architecture/hidl/fmq.html b/en/devices/architecture/hidl/fmq.html index db4055b5..1573b071 100644 --- a/en/devices/architecture/hidl/fmq.html +++ b/en/devices/architecture/hidl/fmq.html @@ -35,7 +35,7 @@ message queue.

Fast Message Queues are supported only in C++.

MessageQueue types

-

Android supports two queue types:

+

Android supports two queue types (known as flavors):

  • Unsynchronized queues are allowed to overflow, and can have many readers; each reader must read data in time or lose it. @@ -136,14 +136,15 @@ for the queue.
    • MQDescriptor object obtained from the first side. The MQDescriptor object is sent over a HIDL RPC call to the process that will hold the second end of the message queue. The -MQDescriptor contains information about the queue:

    +MQDescriptor contains information about the queue, including:

    • Information to map the buffer and write pointer.
      • -
    • If the queue is synchronized, information to map the read pointer.
      • -
    • If the queue is blocking, information to map the event flag word.
      • -
    • The object type is made into a template with the HIDL-defined type of queue -elements and the flavor (synchronized or unsynchronized).
      • +
    • Information to map the read pointer (if the queue is synchronized).
      • +
    • Information to map the event flag word (if the queue is blocking).
      • +
    • Object type (<T, flavor>), which includes the +HIDL-defined type of +queue elements and the queue flavor (synchronized or unsynchronized).

    The MQDescriptor object can be used to construct a @@ -172,8 +173,15 @@ of blocking read/write calls:

  • Short form, with three parameters (data pointer, number of items, timeout). Supports blocking on individual read/write operations on a single queue. When using this form, the queue will handle the event flag and bitmasks -internally, and the first message queue object must be initialized with a -second parameter of true.
    • +internally, and the first message queue object must +be initialized with a second parameter of true. For example: +
    +// For an unsynchronized FMQ that supports blocking
+mFmqUnsynchronizedBlocking =
+  new (std::nothrow) MessageQueue<uint16_t, kUnsynchronizedWrite>
+      (kNumElementsInQueue, true /* enable blocking operations */);
+
    +
 
  • Long form, with six parameters (includes event flag and bitmasks).
 Supports using a shared EventFlag object between multiple queues
 and allows specifying the notification bit masks to be used. In this case, the
@@ -285,12 +293,12 @@ notification bits. Similarly, writeblocking() will fail if
 
    To wait on multiple queues at once, use an EventFlag object's
 wait() method to wait on a bitmask of notifications. The
 wait() method returns a status word with the bits that caused the
-wake up set. Using the information, the user can then check the corresponding
-queue to see whether it has enough space or data for the desired write or read
-operation and perform a nonblocking read()/write()
-followed by a call to the EventFlag's wake() method if
-a notification is desired after the same. For a definition of the
-EventFlag abstraction, refer to
+wake up set. This information is then used to verify the corresponding queue has
+enough space or data for the desired write/read operation and perform a
+nonblocking write()/read(). To get a post operation
+notification, use another call to the EventFlag's
+wake() method. For a definition of the EventFlag
+abstraction, refer to
 system/libfmq/include/fmq/EventFlag.h.
 
    
 
@@ -299,9 +307,9 @@ a notification is desired after the same. For a definition of the
 read/write/readBlocking/writeBlocking()
 APIs take a pointer to an input/output buffer as an argument and use
 memcpy() calls internally to copy data between the same and the
-FMQ ring buffer. To improve performance, Android O includes a set of APIs that
-provide direct pointer access into the ring buffer, eliminating the need to use
-memcpy calls.
    
+FMQ ring buffer. To improve performance, Android 8.0 and higher include a set of
+APIs that provide direct pointer access into the ring buffer, eliminating the
+need to use memcpy calls.
    
 
 
    Use the following public APIs for zero copy FMQ operations:
    
 
@@ -323,8 +331,9 @@ read/write is possible. If the read or write is possible the memTx
 struct is populated with base pointers that can be used for direct pointer
 access into the ring buffer shared memory.
    • 
 
  • The MemRegion struct contains details about a block of memory,
-i.e. a base pointer and length in terms of T(where the FMQ is
-templatized to T).
    • 
+including the base pointer (base address of the memory block) and the length in
+terms of T (length of the memory block in terms of the HIDL-defined
+type of the message queue).
 
  • The MemTransaction struct contains two MemRegion
 structs, first and second as a read or write into
 the ring buffer may require a wrap around to the beginning of the queue. This
@@ -404,7 +413,7 @@ event flag pointer (using getEventFlagWord()) from a
 use that flag to create the necessary EventFlag object.
    • 
 
  • Use the MessageQueue getDesc() method to get a
 descriptor object.
    • 
-
  • In the .hal file, give a method a parameter of type
+
  • In the .hal file, give the method a parameter of type
 fmq_sync or fmq_unsync where T is a
 suitable HIDL-defined type. Use this to send the object returned by
 getDesc() to the receiving process.
    • 
diff --git a/en/devices/architecture/hidl/types.html b/en/devices/architecture/hidl/types.html
index 1f36262d..943d355e 100644
--- a/en/devices/architecture/hidl/types.html
+++ b/en/devices/architecture/hidl/types.html
@@ -95,14 +95,14 @@ can be attached to the same item.
    
 
    Forward declarations
    
 
    In HIDL, structs may not be forward-declared, making user-defined,
 self-referential data types impossible (e.g., you cannot describe a linked list
-or a tree in HIDL). Most existing (pre-Android O) HALs have limited use of
+or a tree in HIDL). Most existing (pre-Android 8.x) HALs have limited use of
 forward declarations, which can be removed by rearranging data structure
 declarations.
    
 
 
    This restriction allows data structures to be copied by-value with a simple
 deep-copy, rather than keeping track of pointer values that may occur multiple
 times in a self-referential data structure. If the same data is passed twice,
-such as with two method parameters or vec<T>'s that point to
+such as with two method parameters or vec<T>s that point to
 the same data, two separate copies are made and delivered.
    
 
 
    Nested declarations
    
@@ -255,7 +255,7 @@ allocated native_handle_t.
    
 
    In earlier versions of Android, native handles were created using the same
 functions present in
 libcutils.
-In Android O, these functions are now copied to the
+In Android 8.0 and higher, these functions are now copied to the
 android::hardware::hidl namespace or moved to the NDK. HIDL
 autogenerated code serializes and deserializes these functions automatically,
 without involvement from user-written code.
    
@@ -266,18 +266,20 @@ without involvement from user-written code.
    
 the ownership of the file descriptors contained in it is as follows:
    
 
 
      
-
    • When passing a hidl_handle object as an argument, the caller
-retains ownership of the file descriptors contained in the
-native_handle_t it wraps, and must close them when it is done with
-them. Likewise, when returning a hidl_handle object (by passing it
-into a _cb function), the process returning it retains ownership of
-the file descriptors contained in the native_handle_t it wraps, and
-must close them when it is done with them.
      • 
-
    • When receiving a hidl_handle object, the
-transport owns the file descriptors inside the
-native_handle_t it wraps; the receiver can use them as-is during
-the transaction callback, but must clone the native handle if it wants to keep
-using its file descriptors beyond the callback. The transport will automatically
+
    • The caller passing a hidl_handle object as an
+argument retains ownership of the file descriptors contained in the
+native_handle_t it wraps; the caller must close these file
+descriptors when it is done with them.
      • 
+
    • The process returning a hidl_handle
+object (by passing it into a _cb function) retains ownership of the
+file descriptors contained in the native_handle_t wrapped by the
+object; the process must close these file descriptors when it is done with them.
+
      • 
+
    • A transport that receives a hidl_handle has
+ownership of the file descriptors inside the native_handle_t
+wrapped by the object; the receiver can use these file descriptors as-is during
+the transaction callback, but must clone the native handle to use the file
+descriptors beyond the callback. The transport will automatically
 close() the file descriptors when the transaction is done.
      • 
 
    
 
diff --git a/en/devices/architecture/hidl/versioning.html b/en/devices/architecture/hidl/versioning.html
index 20ea34b4..fbfd60fa 100644
--- a/en/devices/architecture/hidl/versioning.html
+++ b/en/devices/architecture/hidl/versioning.html
@@ -388,14 +388,14 @@ via import android.hardware.foo@1.0;).

types.hal

-

Every HIDL package contains a types.hal file with UDTs share -among all interfaces participating in that package. HIDL types are always -public; regardless of whether a UDT is declared in types.hal or -within an interface declaration, these types are accessible outside of the scope -where they are defined. types.hal is not meant to describe the -public API of a package, but rather to host UDTs used by all interfaces within -the package. Due to the nature of HIDL, all UDTs are a part of the interface. -

+

Every HIDL package contains a types.hal file containing UDTs +that are shared among all interfaces participating in that package. HIDL types +are always public; regardless of whether a UDT is declared in +types.hal or within an interface declaration, these types are +accessible outside of the scope where they are defined. types.hal +is not meant to describe the public API of a package, but rather to host UDTs +used by all interfaces within the package. Due to the nature of HIDL, all UDTs +are a part of the interface.

types.hal consists of UDTs and import statements. Because types.hal is made available to every interface of the @@ -584,13 +584,13 @@ redundant.

fromFooToBar() it inherits from @1.0::IQuux; it simply lists the new method it adds fromBarToFoo(). In HIDL, inherited methods may not be declared again in the child interfaces, so -for IQuux it would not be an option to declare -fromFooToBar() explicitly.

+the IQuux interface cannot declare the fromFooToBar() +method explicitly.

+If a method implementation needs to fall back to the method implementation of +the base class, the fallback must be in the implementation.

Uprev conventions

Sometimes interface names must rename the extending interface. We recommend -- cgit v1.2.3