Described restrictions for common HAL object methods.

Inheritance of HAL object is performed by composing a child structure of a
single parent structure located at offset 0 followed by new data members
and function pointers in the child structure.

For example,

struct child {
  struct parent common;
  int a_data_member;
  void (*a_method)(struct child *c, int v);
};

HAL code assumes this layout when accessing child structures given a pointer
to a parent structure such that users write code like the following...

void child_method(struct *parent, int v) {
  struct child * c = (struct child*)parent;
  // do stuff with c
}

Code above will break if a member is added before "common" in "struct child".

This change adds comments that describe the restriction on the location of
parent HAL objects within a derived HAL object.  HAL objects that already
have comments that describe the required location of parent objects are not
modified.

Change-Id: Ibe4300275286ef275b2097534c84f1029d761d87

1 files changed, 12 insertions, 0 deletions

diff --git a/include/hardware/fingerprint.h b/include/hardware/fingerprint.h
index b295ebb..c1e29ef 100644
--- a/include/hardware/fingerprint.h
+++ b/include/hardware/fingerprint.h
@@ -69,6 +69,12 @@ typedef void (*fingerprint_notify_t)(fingerprint_msg_t msg);
 
 /* Synchronous operation */
 typedef struct fingerprint_device {
+    /**
+     * Common methods of the fingerprint device.  This *must* be the first member of
+     * fingerprint_device as users of this structure will cast a hw_device_t to
+     * fingerprint_device pointer in contexts where it's known the hw_device_t references a
+     * fingerprint_device.
+     */
     struct hw_device_t common;
 
     /*
@@ -121,6 +127,12 @@ typedef struct fingerprint_device {
 } fingerprint_device_t;
 
 typedef struct fingerprint_module {
+    /**
+     * Common methods of the fingerprint module.  This *must* be the first member of
+     * fingerprint_module as users of this structure will cast a hw_module_t to
+     * fingerprint_module pointer in contexts where it's known the hw_module_t references a
+     * fingerprint_module.
+     */
     struct hw_module_t common;
 } fingerprint_module_t;