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
diff --git a/include/hardware/activity_recognition.h b/include/hardware/activity_recognition.h
index 3d3c1bd..ecac856 100644
--- a/include/hardware/activity_recognition.h
+++ b/include/hardware/activity_recognition.h
@@ -103,6 +103,12 @@
} activity_event_t;
typedef struct activity_recognition_module {
+ /**
+ * Common methods of the activity recognition module. This *must* be the first member of
+ * activity_recognition_module as users of this structure will cast a hw_module_t to
+ * activity_recognition_module pointer in contexts where it's known the hw_module_t
+ * references an activity_recognition_module.
+ */
hw_module_t common;
/*
@@ -126,6 +132,12 @@
} activity_recognition_callback_procs_t;
typedef struct activity_recognition_device {
+ /**
+ * Common methods of the activity recognition device. This *must* be the first member of
+ * activity_recognition_device as users of this structure will cast a hw_device_t to
+ * activity_recognition_device pointer in contexts where it's known the hw_device_t
+ * references an activity_recognition_device.
+ */
hw_device_t common;
/*
diff --git a/include/hardware/audio.h b/include/hardware/audio.h
index b53cbff..6c28def 100644
--- a/include/hardware/audio.h
+++ b/include/hardware/audio.h
@@ -260,6 +260,11 @@
*/
struct audio_stream_out {
+ /**
+ * Common methods of the audio stream out. This *must* be the first member of audio_stream_out
+ * as users of this structure will cast a audio_stream to audio_stream_out pointer in contexts
+ * where it's known the audio_stream references an audio_stream_out.
+ */
struct audio_stream common;
/**
@@ -383,6 +388,11 @@
typedef struct audio_stream_out audio_stream_out_t;
struct audio_stream_in {
+ /**
+ * Common methods of the audio stream in. This *must* be the first member of audio_stream_in
+ * as users of this structure will cast a audio_stream to audio_stream_in pointer in contexts
+ * where it's known the audio_stream references an audio_stream_in.
+ */
struct audio_stream common;
/** set the input gain for the audio driver. This method is for
@@ -439,6 +449,11 @@
};
struct audio_hw_device {
+ /**
+ * Common methods of the audio device. This *must* be the first member of audio_hw_device
+ * as users of this structure will cast a hw_device_t to audio_hw_device pointer in contexts
+ * where it's known the hw_device_t references an audio_hw_device.
+ */
struct hw_device_t common;
/**
diff --git a/include/hardware/audio_policy.h b/include/hardware/audio_policy.h
index cbaa31d..0e88361 100644
--- a/include/hardware/audio_policy.h
+++ b/include/hardware/audio_policy.h
@@ -423,6 +423,12 @@
} audio_policy_module_t;
struct audio_policy_device {
+ /**
+ * Common methods of the audio policy device. This *must* be the first member of
+ * audio_policy_device as users of this structure will cast a hw_device_t to
+ * audio_policy_device pointer in contexts where it's known the hw_device_t references an
+ * audio_policy_device.
+ */
struct hw_device_t common;
int (*create_audio_policy)(const struct audio_policy_device *device,
diff --git a/include/hardware/camera_common.h b/include/hardware/camera_common.h
index 2508022..15b3b19 100644
--- a/include/hardware/camera_common.h
+++ b/include/hardware/camera_common.h
@@ -254,6 +254,12 @@
} camera_module_callbacks_t;
typedef struct camera_module {
+ /**
+ * Common methods of the camera module. This *must* be the first member of
+ * camera_module as users of this structure will cast a hw_module_t to
+ * camera_module pointer in contexts where it's known the hw_module_t references a
+ * camera_module.
+ */
hw_module_t common;
/**
diff --git a/include/hardware/consumerir.h b/include/hardware/consumerir.h
index 5adf6be..15334c1 100644
--- a/include/hardware/consumerir.h
+++ b/include/hardware/consumerir.h
@@ -32,10 +32,22 @@
} consumerir_freq_range_t;
typedef struct consumerir_module {
+ /**
+ * Common methods of the consumer IR module. This *must* be the first member of
+ * consumerir_module as users of this structure will cast a hw_module_t to
+ * consumerir_module pointer in contexts where it's known the hw_module_t references a
+ * consumerir_module.
+ */
struct hw_module_t common;
} consumerir_module_t;
typedef struct consumerir_device {
+ /**
+ * Common methods of the consumer IR device. This *must* be the first member of
+ * consumerir_device as users of this structure will cast a hw_device_t to
+ * consumerir_device pointer in contexts where it's known the hw_device_t references a
+ * consumerir_device.
+ */
struct hw_device_t common;
/*
diff --git a/include/hardware/fb.h b/include/hardware/fb.h
index 135e4aa..9df9416 100644
--- a/include/hardware/fb.h
+++ b/include/hardware/fb.h
@@ -36,6 +36,12 @@
/*****************************************************************************/
typedef struct framebuffer_device_t {
+ /**
+ * Common methods of the framebuffer device. This *must* be the first member of
+ * framebuffer_device_t as users of this structure will cast a hw_device_t to
+ * framebuffer_device_t pointer in contexts where it's known the hw_device_t references a
+ * framebuffer_device_t.
+ */
struct hw_device_t common;
/* flags describing some attributes of the framebuffer */
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 @@
/* 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 @@
} 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;
diff --git a/include/hardware/hdmi_cec.h b/include/hardware/hdmi_cec.h
index f049952..1906153 100644
--- a/include/hardware/hdmi_cec.h
+++ b/include/hardware/hdmi_cec.h
@@ -211,6 +211,11 @@
typedef void (*event_callback_t)(const hdmi_event_t* event, void* arg);
typedef struct hdmi_cec_module {
+ /**
+ * Common methods of the HDMI CEC module. This *must* be the first member of
+ * hdmi_cec_module as users of this structure will cast a hw_module_t to hdmi_cec_module
+ * pointer in contexts where it's known the hw_module_t references a hdmi_cec_module.
+ */
struct hw_module_t common;
} hdmi_module_t;
@@ -218,6 +223,11 @@
* HDMI-CEC HAL interface definition.
*/
typedef struct hdmi_cec_device {
+ /**
+ * Common methods of the HDMI CEC device. This *must* be the first member of
+ * hdmi_cec_device as users of this structure will cast a hw_device_t to hdmi_cec_device
+ * pointer in contexts where it's known the hw_device_t references a hdmi_cec_device.
+ */
struct hw_device_t common;
/*
diff --git a/include/hardware/hwcomposer.h b/include/hardware/hwcomposer.h
index afb4e99..049edea 100644
--- a/include/hardware/hwcomposer.h
+++ b/include/hardware/hwcomposer.h
@@ -471,10 +471,22 @@
/*****************************************************************************/
typedef struct hwc_module {
+ /**
+ * Common methods of the hardware composer module. This *must* be the first member of
+ * hwc_module as users of this structure will cast a hw_module_t to
+ * hwc_module pointer in contexts where it's known the hw_module_t references a
+ * hwc_module.
+ */
struct hw_module_t common;
} hwc_module_t;
typedef struct hwc_composer_device_1 {
+ /**
+ * Common methods of the hardware composer device. This *must* be the first member of
+ * hwc_composer_device_1 as users of this structure will cast a hw_device_t to
+ * hwc_composer_device_1 pointer in contexts where it's known the hw_device_t references a
+ * hwc_composer_device_1.
+ */
struct hw_device_t common;
/*
diff --git a/include/hardware/keymaster.h b/include/hardware/keymaster.h
index 12158bf..8c5ff14 100644
--- a/include/hardware/keymaster.h
+++ b/include/hardware/keymaster.h
@@ -83,6 +83,12 @@
};
struct keystore_module {
+ /**
+ * Common methods of the keystore module. This *must* be the first member of
+ * keystore_module as users of this structure will cast a hw_module_t to
+ * keystore_module pointer in contexts where it's known the hw_module_t references a
+ * keystore_module.
+ */
hw_module_t common;
};
@@ -166,6 +172,12 @@
* The parameters that can be set for a given keymaster implementation.
*/
struct keymaster_device {
+ /**
+ * Common methods of the keymaster device. This *must* be the first member of
+ * keymaster_device as users of this structure will cast a hw_device_t to
+ * keymaster_device pointer in contexts where it's known the hw_device_t references a
+ * keymaster_device.
+ */
struct hw_device_t common;
/**
@@ -282,4 +294,3 @@
__END_DECLS
#endif // ANDROID_HARDWARE_KEYMASTER_H
-
diff --git a/include/hardware/local_time_hal.h b/include/hardware/local_time_hal.h
index 6b6a317..946e799 100644
--- a/include/hardware/local_time_hal.h
+++ b/include/hardware/local_time_hal.h
@@ -55,6 +55,12 @@
};
struct local_time_hw_device {
+ /**
+ * Common methods of the local time hardware device. This *must* be the first member of
+ * local_time_hw_device as users of this structure will cast a hw_device_t to
+ * local_time_hw_device pointer in contexts where it's known the hw_device_t references a
+ * local_time_hw_device.
+ */
struct hw_device_t common;
/**
diff --git a/include/hardware/nfc.h b/include/hardware/nfc.h
index 09523b3..3edfeb6 100644
--- a/include/hardware/nfc.h
+++ b/include/hardware/nfc.h
@@ -210,6 +210,12 @@
#define NFC_PN544_CONTROLLER "pn544"
typedef struct nfc_module_t {
+ /**
+ * Common methods of the NFC NXP PN544 module. This *must* be the first member of
+ * nfc_module_t as users of this structure will cast a hw_module_t to
+ * nfc_module_t pointer in contexts where it's known the hw_module_t references an
+ * nfc_module_t.
+ */
struct hw_module_t common;
} nfc_module_t;
@@ -227,6 +233,12 @@
} nfc_pn544_linktype;
typedef struct {
+ /**
+ * Common methods of the NFC NXP PN544 device. This *must* be the first member of
+ * nfc_pn544_device_t as users of this structure will cast a hw_device_t to
+ * nfc_pn544_device_t pointer in contexts where it's known the hw_device_t references an
+ * nfc_pn544_device_t.
+ */
struct hw_device_t common;
/* The number of EEPROM registers to write */
diff --git a/include/hardware/nfc_tag.h b/include/hardware/nfc_tag.h
index 72028f4..040a07d 100644
--- a/include/hardware/nfc_tag.h
+++ b/include/hardware/nfc_tag.h
@@ -32,10 +32,22 @@
#define NFC_TAG_ID "tag"
typedef struct nfc_tag_module_t {
+ /**
+ * Common methods of the NFC tag module. This *must* be the first member of
+ * nfc_tag_module_t as users of this structure will cast a hw_module_t to
+ * nfc_tag_module_t pointer in contexts where it's known the hw_module_t references a
+ * nfc_tag_module_t.
+ */
struct hw_module_t common;
} nfc_tag_module_t;
typedef struct nfc_tag_device {
+ /**
+ * Common methods of the NFC tag device. This *must* be the first member of
+ * nfc_tag_device_t as users of this structure will cast a hw_device_t to
+ * nfc_tag_device_t pointer in contexts where it's known the hw_device_t references a
+ * nfc_tag_device_t.
+ */
struct hw_device_t common;
/**
diff --git a/include/hardware/vibrator.h b/include/hardware/vibrator.h
index 795d23e..92b1fd0 100644
--- a/include/hardware/vibrator.h
+++ b/include/hardware/vibrator.h
@@ -35,7 +35,13 @@
struct vibrator_device;
typedef struct vibrator_device {
- struct hw_device_t common;
+ /**
+ * Common methods of the vibrator device. This *must* be the first member of
+ * vibrator_device as users of this structure will cast a hw_device_t to
+ * vibrator_device pointer in contexts where it's known the hw_device_t references a
+ * vibrator_device.
+ */
+ struct hw_device_t common;
/** Turn on vibrator
*