Status/Return: document expected usage.

The intention for most HIDL users is to declare error codes in HIDL
interfaces and use those. Transport errors are much more rare and in
most cases can just be ignored so that init can restart the process
in question.

This also means that HIDL implementations shouldn't construct the
Status object directly.

Bug: 124861676
Bug: 121004730
Test: N/A
Change-Id: I4a5d79cf453345025c9d0b64c29a4486cc51fab4

1 files changed, 26 insertions, 22 deletions

diff --git a/base/include/hidl/Status.h b/base/include/hidl/Status.h
index b69d4e4..765f0f7 100644
--- a/base/include/hidl/Status.h
+++ b/base/include/hidl/Status.h
@@ -27,32 +27,36 @@
 namespace android {
 namespace hardware {
 
-// An object similar in function to a status_t except that it understands
-// how exceptions are encoded in the prefix of a Parcel. Used like:
+// HIDL formally separates transport error codes from interface error codes. When developing a HIDL
+// interface, errors relevant to a service should be placed in the interface design for that HAL.
 //
-//     Parcel data;
-//     Parcel reply;
-//     status_t status;
-//     binder::Status remote_exception;
-//     if ((status = data.writeInterfaceToken(interface_descriptor)) != OK ||
-//         (status = data.writeInt32(function_input)) != OK) {
-//         // We failed to write into the memory of our local parcel?
-//     }
-//     if ((status = remote()->transact(transaction, data, &reply)) != OK) {
-//        // Something has gone wrong in the binder driver or libbinder.
-//     }
-//     if ((status = remote_exception.readFromParcel(reply)) != OK) {
-//         // The remote didn't correctly write the exception header to the
-//         // reply.
-//     }
-//     if (!remote_exception.isOk()) {
-//         // The transaction went through correctly, but the remote reported an
-//         // exception during handling.
-//     }
+// For instance:
 //
+//     interface I* {
+//         enum FooStatus { NO_FOO, NO_BAR }; // service-specific errors
+//         doFoo(...) generates (FooStatus foo);
+//     };
+//
+// When calling into this interface, a Return<*> (in this case Return<FooStatus> object will be
+// returned). For most clients, it's expected that they'll just get the result from this function
+// and use it directly. If there is a transport error, the process will just abort. In general,
+// transport errors are expected only in extremely rare circumstances (bug in the
+// code/cosmic radiation/etc..). Aborting allows process to restart using their normal happy path
+// code.
+//
+// For certain processes though which are critical to the functionality of the phone (e.g.
+// hwservicemanager/init), these errors must be handled. Return<*>::isOk and
+// Return<*>::isDeadObject are provided for these cases. Whenever this is done, special attention
+// should be paid to testing the unhappy paths to make sure that error handling is handled
+// properly.
+
+// Transport implementation detail. HIDL implementors, see Return below. HAL implementations should
+// return HIDL-defined errors rather than use this.
 class Status final {
 public:
-    // Keep the exception codes in sync with android/os/Parcel.java.
+    // Note: forked from
+    // - frameworks/base/core/java/android/os/android/os/Parcel.java.
+    // - frameworks/native/libs/binder/include/binder/Status.h
     enum Exception {
         EX_NONE = 0,
         EX_SECURITY = -1,