Skip to content

Commit

Permalink
sensing: fix doxygen warnings
Browse files Browse the repository at this point in the history 
Add missing doxygen comments in various sensing headers.

Signed-off-by: Zhang Lixu <[email protected]>
  • Loading branch information
@lixuzha
lixuzha committed Apr 30, 2024
1 parent c059405 commit 8f5146b
Show file tree
Hide file tree
Showing 4 changed files with 266 additions and 106 deletions.
88 changes: 44 additions & 44 deletions include/zephyr/sensing/sensing.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -38,16 +38,20 @@ extern "C" {
*/
struct sensing_sensor_version {
union {
uint32_t value;
uint32_t value; /**< The version represented as a 32-bit value. */
struct {
uint8_t major;
uint8_t minor;
uint8_t hotfix;
uint8_t build;
uint8_t major; /**< The major version number. */
uint8_t minor; /**< The minor version number. */
uint8_t hotfix; /**< The hotfix version number. */
uint8_t build; /**< The build version number. */
};
};
};

/**
* @brief Macro to create a sensor version value.
*
*/
#define SENSING_SENSOR_VERSION(_major, _minor, _hotfix, _build) \
(FIELD_PREP(GENMASK(31, 24), _major) | \
FIELD_PREP(GENMASK(23, 16), _minor) | \
Expand Down Expand Up @@ -83,36 +87,36 @@ struct sensing_sensor_version {
*
*/
enum sensing_sensor_state {
SENSING_SENSOR_STATE_READY = 0,
SENSING_SENSOR_STATE_OFFLINE = 1,
SENSING_SENSOR_STATE_READY = 0, /**< The sensor is ready. */
SENSING_SENSOR_STATE_OFFLINE = 1, /**< The sensor is offline. */
};

/**
* @brief Sensing subsystem sensor config attribute
*
*/
enum sensing_sensor_attribute {
/** The interval attribute of a sensor configuration. */
SENSING_SENSOR_ATTRIBUTE_INTERVAL = 0,
/** The sensitivity attribute of a sensor configuration. */
SENSING_SENSOR_ATTRIBUTE_SENSITIVITY = 1,
/** The latency attribute of a sensor configuration. */
SENSING_SENSOR_ATTRIBUTE_LATENCY = 2,
/** The maximum number of attributes that a sensor configuration can have. */
SENSING_SENSOR_ATTRIBUTE_MAX,
};


/**
* @brief Define Sensing subsystem sensor handle
*
*/
typedef void *sensing_sensor_handle_t;


/**
* @brief Sensor data event receive callback.
*
* @param handle The sensor instance handle.
*
* @param buf The data buffer with sensor data.
*
* @param context User provided context pointer.
*/
typedef void (*sensing_data_event_t)(
Expand Down Expand Up @@ -151,41 +155,52 @@ struct sensing_sensor_info {
*
*/
struct sensing_callback_list {
sensing_data_event_t on_data_event;
void *context;
sensing_data_event_t on_data_event; /**< Callback function for a sensor data event. */
void *context; /**< Associated context with on_data_event */
};

/**
* @struct sensing_sensor_config
* @brief Sensing subsystem sensor configure, including interval, sensitivity, latency
*
*/
struct sensing_sensor_config {
enum sensing_sensor_attribute attri;
enum sensing_sensor_attribute attri; /**< Attribute of the sensor configuration. */

/** \ref SENSING_SENSITIVITY_INDEX_ALL */
int8_t data_field;
int8_t data_field; /**< Data field of the sensor configuration. */

union {
/** Interval between two sensor samples in microseconds (us). */
uint32_t interval;

/**
* Sensitivity threshold for reporting new data. A new sensor sample is reported
* only if the difference between it and the previous sample exceeds this
* sensitivity value.
*/
uint32_t sensitivity;

/**
* Maximum duration for batching sensor samples before reporting in
* microseconds (us). This defines how long sensor samples can be
* accumulated before they must be reported.
*/
uint64_t latency;
};
};


/**
* @brief Get all supported sensor instances' information.
*
* This API just returns read only information of sensor instances, pointer info will
* directly point to internal buffer, no need for caller to allocate buffer,
* no side effect to sensor instances.
*
* @param num_sensors Get number of sensor instances.
*
* @param info For receiving sensor instances' information array pointer.
*
* @return 0 on success or negative error value on failure.
*/
/**
* @brief Get all supported sensor instances' information.
*
* This API just returns read only information of sensor instances, pointer info will
* directly point to internal buffer, no need for caller to allocate buffer,
* no side effect to sensor instances.
*
* @param num_sensors Get number of sensor instances.
* @param info For receiving sensor instances' information array pointer.
* @return 0 on success or negative error value on failure.
*/
int sensing_get_sensors(int *num_sensors, const struct sensing_sensor_info **info);

/**
Expand All @@ -197,12 +212,9 @@ int sensing_get_sensors(int *num_sensors, const struct sensing_sensor_info **inf
* meanwhile, also register sensing callback list
*
* @param info The sensor info got from \ref sensing_get_sensors
*
* @param cb_list callback list to be registered to sensing, must have a static
* lifetime.
*
* @param handle The opened instance handle, if failed will be set to NULL.
*
* @return 0 on success or negative error value on failure.
*/
int sensing_open_sensor(
Expand All @@ -219,12 +231,9 @@ int sensing_open_sensor(
* meanwhile, also register sensing callback list.
*
* @param dev pointer device get from device tree.
*
* @param cb_list callback list to be registered to sensing, must have a static
* lifetime.
*
* @param handle The opened instance handle, if failed will be set to NULL.
*
* @return 0 on success or negative error value on failure.
*/
int sensing_open_sensor_by_dt(
Expand All @@ -235,7 +244,6 @@ int sensing_open_sensor_by_dt(
* @brief Close sensor instance.
*
* @param handle The sensor instance handle need to close.
*
* @return 0 on success or negative error value on failure.
*/
int sensing_close_sensor(
Expand All @@ -245,11 +253,8 @@ int sensing_close_sensor(
* @brief Set current config items to Sensing subsystem.
*
* @param handle The sensor instance handle.
*
* @param configs The configs to be set according to config attribute.
*
* @param count count of configs.
*
* @return 0 on success or negative error value on failure, not support etc.
*/
int sensing_set_config(
Expand All @@ -260,11 +265,8 @@ int sensing_set_config(
* @brief Get current config items from Sensing subsystem.
*
* @param handle The sensor instance handle.
*
* @param configs The configs to be get according to config attribute.
*
* @param count count of configs.
*
* @return 0 on success or negative error value on failure, not support etc.
*/
int sensing_get_config(
Expand All @@ -275,7 +277,6 @@ int sensing_get_config(
* @brief Get sensor information from sensor instance handle.
*
* @param handle The sensor instance handle.
*
* @return a const pointer to \ref sensing_sensor_info on success or NULL on failure.
*/
const struct sensing_sensor_info *sensing_get_sensor_info(
Expand All @@ -289,5 +290,4 @@ const struct sensing_sensor_info *sensing_get_sensor_info(
* @}
*/


#endif /*ZEPHYR_INCLUDE_SENSING_H_*/
42 changes: 31 additions & 11 deletions include/zephyr/sensing/sensing_datatypes.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -45,9 +45,9 @@
* system/chre/chre_api/include/chre_api/chre/sensor_types.h
*/
struct sensing_sensor_value_header {
/** base timestamp of this data readings, unit is micro seconds */
/** Base timestamp of this data readings, unit is micro seconds */
uint64_t base_timestamp;
/** count of this data readings */
/** Count of this data readings */
uint16_t reading_count;
};

Expand All @@ -65,19 +65,28 @@ struct sensing_sensor_value_header {
* q31 version
*/
struct sensing_sensor_value_3d_q31 {
/** Header of the sensor value data structure. */
struct sensing_sensor_value_header header;
int8_t shift;
int8_t shift; /**< The shift value for the q31_t v[3] reading. */
struct {
/** Timestamp delta of the reading. Unit is micro seconds. */
uint32_t timestamp_delta;
union {
/**
* 3D vector of the reading represented as an array.
* For SENSING_SENSOR_TYPE_MOTION_ACCELEROMETER_3D and
* SENSING_SENSOR_TYPE_MOTION_UNCALIB_ACCELEROMETER_3D,
* the unit is Gs (gravitational force).
* For SENSING_SENSOR_TYPE_MOTION_GYROMETER_3D, the unit is degrees.
*/
q31_t v[3];
struct {
q31_t x;
q31_t y;
q31_t z;
q31_t x; /**< X value of the 3D vector. */
q31_t y; /**< Y value of the 3D vector. */
q31_t z; /**< Z value of the 3D vector. */
};
};
} readings[1];
} readings[1]; /**< Array of readings. */
};

/**
Expand All @@ -86,11 +95,17 @@ struct sensing_sensor_value_3d_q31 {
* uint32_t version
*/
struct sensing_sensor_value_uint32 {
/** Header of the sensor value data structure. */
struct sensing_sensor_value_header header;
struct {
/** Timestamp delta of the reading. Unit is micro seconds. */
uint32_t timestamp_delta;
/**
* Value of the reading.
* For SENSING_SENSOR_TYPE_LIGHT_AMBIENTLIGHT, the unit is luxs.
*/
uint32_t v;
} readings[1];
} readings[1]; /**< Array of readings. */
};

/**
Expand All @@ -99,15 +114,20 @@ struct sensing_sensor_value_uint32 {
* q31 version
*/
struct sensing_sensor_value_q31 {
/** Header of the sensor value data structure. */
struct sensing_sensor_value_header header;
int8_t shift;
int8_t shift; /**< The shift value for the q31_t v reading. */
struct {
/** Timestamp delta of the reading. Unit is micro seconds. */
uint32_t timestamp_delta;
/**
* Value of the reading.
* For SENSING_SENSOR_TYPE_MOTION_HINGE_ANGLE, the unit is degrees.
*/
q31_t v;
} readings[1];
} readings[1]; /**< Array of readings. */
};


/**
* @}
*/
Expand Down
Loading

0 comments on commit 8f5146b

Please sign in to comment.