Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

sensing: sensing.h: fix doxygen warnings #68317

Merged
merged 1 commit into from
Apr 30, 2024
+266 −106
Merged

sensing: sensing.h: fix doxygen warnings #68317

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
88 changes: 44 additions & 44 deletions include/zephyr/sensing/sensing.h
View file
Open in desktop
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
Open in desktop
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
Loading