From 610f4f5d73f2ab5898f49d5834b96a2dbbc29e53 Mon Sep 17 00:00:00 2001 From: gornekich <44112859+gornekich@users.noreply.github.com> Date: Wed, 24 Mar 2021 12:35:33 +0300 Subject: [PATCH] [FL-41] api-hal doxygen documentation (#387) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * targets/api-hal: rework documentation in doxygen style * core/api-hal: rework documentation in doxygen style * core/furi: rework documentation in doxygen style * drivers: rework documentation in doxygen style Co-authored-by: あく --- core/api-hal/api-gpio.h | 53 +++++++++++++--- core/api-hal/api-interrupt-mgr.h | 38 ++++++++++++ core/furi/pubsub.h | 42 ++++++------- core/furi/record.h | 15 +++-- core/furi/stdglue.h | 11 ++-- core/furi/thread.h | 46 +++++++++----- core/furi/valuemutex.h | 60 +++++++++---------- .../targets/api-hal-include/api-hal-boot.h | 2 + firmware/targets/api-hal-include/api-hal-bt.h | 25 ++++---- .../targets/api-hal-include/api-hal-delay.h | 8 +++ .../targets/api-hal-include/api-hal-i2c.h | 38 ++++++++++++ .../targets/api-hal-include/api-hal-light.h | 6 ++ .../targets/api-hal-include/api-hal-power.h | 52 ++++++++-------- firmware/targets/api-hal-include/api-hal-sd.h | 13 +--- .../targets/api-hal-include/api-hal-subghz.h | 5 ++ .../targets/api-hal-include/api-hal-uid.h | 4 +- .../targets/api-hal-include/api-hal-vcp.h | 9 ++- .../targets/api-hal-include/api-hal-version.h | 7 +++ .../targets/api-hal-include/api-hal-vibro.h | 4 +- firmware/targets/api-hal-include/api-hal.h | 1 + lib/drivers/bq25896.h | 20 +++---- lib/drivers/bq27220.h | 20 +++---- lib/drivers/lp5562.h | 7 ++- 23 files changed, 325 insertions(+), 161 deletions(-) diff --git a/core/api-hal/api-gpio.h b/core/api-hal/api-gpio.h index d4fcd3a9..0a111aca 100644 --- a/core/api-hal/api-gpio.h +++ b/core/api-hal/api-gpio.h @@ -12,39 +12,74 @@ typedef struct { GpioPin* gpio; } GpioDisableRecord; -// init GPIO API +/** + * Init GPIO API + * @return true on successful gpio initialization, false otherwize + */ bool gpio_api_init(); -// init GPIO +/** + * Init GPIO + * @param gpio GpioPin instance + * @param mode GpioMode gpio mode + */ void gpio_init(const GpioPin* gpio, const GpioMode mode); -// init GPIO, extended version +/** + * Init GPIO, extended version + * @param gpio GpioPin instance + * @param mode GpioMode gpio mode + * @param pull GpioPull gpio pull mode + * @param speed GpioSpeed gpio speed + */ void gpio_init_ex( const GpioPin* gpio, const GpioMode mode, const GpioPull pull, const GpioSpeed speed); -// write value to GPIO, false = LOW, true = HIGH +/** + * Write value to GPIO + * @param gpio GpioPin instance + * @param state false = LOW, true = HIGH + */ static inline void gpio_write(const GpioPin* gpio, const bool state) { hal_gpio_write(gpio, state); } -// read value from GPIO, false = LOW, true = HIGH +/** + * Read value from GPIO + * @param gpio GpioPin instance + * @return false = LOW, true = HIGH + */ static inline bool gpio_read(const GpioPin* gpio) { return hal_gpio_read(gpio); } -// put GPIO to Z-state +/** + * Put GPIO to Z-state + * @param gpio_record GpioDisableRecord instance + */ void gpio_disable(GpioDisableRecord* gpio_record); -// get GPIO record +/** + * Get GPIO record + * @param name name of record + * @return ValueMutex instance + */ ValueMutex* gpio_open_mutex(const char* name); -// get GPIO record and acquire mutex +/** + * Get GPIO record and acquire mutex + * @param name name of record + * @return GpioPin instance + */ GpioPin* gpio_open(const char* name); -// get RFID IN level +/** + * Get RFID IN level + * @return false = LOW, true = HIGH + */ bool get_rfid_in_level(); #ifdef __cplusplus diff --git a/core/api-hal/api-interrupt-mgr.h b/core/api-hal/api-interrupt-mgr.h index a38983d6..9716f463 100644 --- a/core/api-hal/api-interrupt-mgr.h +++ b/core/api-hal/api-interrupt-mgr.h @@ -6,8 +6,10 @@ extern "C" { #endif +/** Interrupt callback prototype */ typedef void (*InterruptCallback)(void*, void*); +/** Interupt type */ typedef enum { InterruptTypeComparatorTrigger, InterruptTypeTimerCapture, @@ -16,6 +18,7 @@ typedef enum { InterruptTypeExternalInterrupt, } InterruptType; +/** Interrupt callback type */ typedef struct { InterruptCallback callback; InterruptType type; @@ -23,11 +26,46 @@ typedef struct { bool ready; } InterruptCallbackItem; +/** + * Init interrupt + * @return true on succsessful initialization, false otherwise + */ bool api_interrupt_init(); + +/** + * Add interrupt + * @param callback InterruptCallback + * @param type InterruptType + * @param context context for callback + */ void api_interrupt_add(InterruptCallback callback, InterruptType type, void* context); + +/** + * Remove interrupt + * @param callback InterruptCallback + * @param type InterruptType + */ void api_interrupt_remove(InterruptCallback callback, InterruptType type); + +/** + * Enable interrupt + * @param callback InterruptCallback + * @param type InterruptType + */ void api_interrupt_enable(InterruptCallback callback, InterruptType type); + +/** + * Disable interrupt + * @param callback InterruptCallback + * @param type InterruptType + */ void api_interrupt_disable(InterruptCallback callback, InterruptType type); + +/** + * Call interrupt + * @param type InterruptType + * @param hw pointer to hardware peripheral + */ void api_interrupt_call(InterruptType type, void* hw); #ifdef __cplusplus diff --git a/core/furi/pubsub.h b/core/furi/pubsub.h index 62a7f2b3..2f440e1c 100644 --- a/core/furi/pubsub.h +++ b/core/furi/pubsub.h @@ -7,14 +7,14 @@ extern "C" { #endif -/* +/** == PubSub == -PubSub allows users to subscribe on notifies and notify subscribers. -Notifier side can pass `void*` arg to subscriber callback, -and also subscriber can set `void*` context pointer that pass into -callback (you can see callback signature below). -*/ + * PubSub allows users to subscribe on notifies and notify subscribers. + * Notifier side can pass `void*` arg to subscriber callback, + * and also subscriber can set `void*` context pointer that pass into + * callback (you can see callback signature below). + */ typedef void (*PubSubCallback)(const void*, void*); typedef struct PubSubType PubSub; @@ -32,29 +32,29 @@ struct PubSubType { osMutexId_t mutex; }; -/* -To create PubSub you should create PubSub instance and call `init_pubsub`. -*/ +/** + * To create PubSub you should create PubSub instance and call `init_pubsub`. + */ bool init_pubsub(PubSub* pubsub); -/* -Since we use dynamic memory - we must explicity delete pubsub -*/ +/** + * Since we use dynamic memory - we must explicity delete pubsub + */ bool delete_pubsub(PubSub* pubsub); -/* -Use `subscribe_pubsub` to register your callback. -*/ +/** + * Use `subscribe_pubsub` to register your callback. + */ PubSubItem* subscribe_pubsub(PubSub* pubsub, PubSubCallback cb, void* ctx); -/* -Use `unsubscribe_pubsub` to unregister callback. -*/ +/** + * Use `unsubscribe_pubsub` to unregister callback. + */ bool unsubscribe_pubsub(PubSubItem* pubsub_id); -/* -Use `notify_pubsub` to notify subscribers. -*/ +/** + * Use `notify_pubsub` to notify subscribers. + */ bool notify_pubsub(PubSub* pubsub, void* arg); #ifdef __cplusplus diff --git a/core/furi/record.h b/core/furi/record.h index 965d1908..b90b0879 100644 --- a/core/furi/record.h +++ b/core/furi/record.h @@ -6,26 +6,30 @@ extern "C" { #endif -/* Initialize record storage +/** + * Initialize record storage * For internal use only. */ void furi_record_init(); -/* Create record +/** + * Create record * @param name - record name * @param data - data pointer * @note Thread safe. Create and destroy must be executed from the same thread. */ void furi_record_create(const char* name, void* data); -/* Destroy record +/** + * Destroy record * @param name - record name * @return true if successful, false if still have holders or thread is not owner. * @note Thread safe. Create and destroy must be executed from the same thread. */ bool furi_record_destroy(const char* name); -/* Open record +/** + * Open record * @param name - record name * @return pointer to the record * @note Thread safe. Open and close must be executed from the same thread. @@ -33,7 +37,8 @@ bool furi_record_destroy(const char* name); */ void* furi_record_open(const char* name); -/* Close record +/** + * Close record * @param name - record name * @note Thread safe. Open and close must be executed from the same thread. */ diff --git a/core/furi/stdglue.h b/core/furi/stdglue.h index 16d9b917..a13c994d 100644 --- a/core/furi/stdglue.h +++ b/core/furi/stdglue.h @@ -7,7 +7,8 @@ extern "C" { #endif -/* Write callback +/** + * Write callback * @param _cookie - pointer to cookie (see stdio gnu extension) * @param data - pointer to data * @param size - data size @@ -15,17 +16,19 @@ extern "C" { */ typedef void (*FuriStdglueWriteCallback)(void* _cookie, const char* data, size_t size); -/* Initialized std library glue code */ +/** Initialized std library glue code */ void furi_stdglue_init(); -/* Set global STDOUT callback +/** + * Set global STDOUT callback * @param callback - callback or NULL to clear * @return true on success, otherwise fail * @warning function is thread aware, use this API from the same thread */ bool furi_stdglue_set_global_stdout_callback(FuriStdglueWriteCallback callback); -/* Set STDOUT callback for your thread +/** + * Set STDOUT callback for your thread * @param callback - callback or NULL to clear * @return true on success, otherwise fail * @warning function is thread aware, use this API from the same thread diff --git a/core/furi/thread.h b/core/furi/thread.h index d73141c2..780f06ac 100644 --- a/core/furi/thread.h +++ b/core/furi/thread.h @@ -8,88 +8,101 @@ extern "C" { #endif -/* FuriThreadState */ +/** FuriThreadState */ typedef enum { FuriThreadStateStopped, FuriThreadStateStarting, FuriThreadStateRunning, } FuriThreadState; -/* FuriThread anonymous structure */ +/** FuriThread anonymous structure */ typedef struct FuriThread FuriThread; -/* FuriThreadCallback +/** + * FuriThreadCallback * Your callback to run in new thread * @warning don't use osThreadExit */ typedef int32_t (*FuriThreadCallback)(void* context); -/* FuriThread state change calback +/** + * FuriThread state change calback * called upon thread state change * @param state - new thread state * @param context - callback context */ typedef void (*FuriThreadStateCallback)(FuriThreadState state, void* context); -/* Allocate FuriThread +/** + * Allocate FuriThread * @return FuriThread instance */ FuriThread* furi_thread_alloc(); -/* Release FuriThread +/** + * Release FuriThread * @param thread - FuriThread instance */ void furi_thread_free(FuriThread* thread); -/* Set FuriThread name +/** + * Set FuriThread name * @param thread - FuriThread instance * @param name - string */ void furi_thread_set_name(FuriThread* thread, const char* name); -/* Set FuriThread stack size +/** + * Set FuriThread stack size * @param thread - FuriThread instance * @param stack_size - stack size in bytes */ void furi_thread_set_stack_size(FuriThread* thread, size_t stack_size); -/* Set FuriThread callback +/** + * Set FuriThread callback * @param thread - FuriThread instance * @param callback - FuriThreadCallback, called upon thread run */ void furi_thread_set_callback(FuriThread* thread, FuriThreadCallback callback); -/* Set FuriThread context +/** + * Set FuriThread context * @param thread - FuriThread instance * @param context - pointer to context for thread callback */ void furi_thread_set_context(FuriThread* thread, void* context); -/* Set FuriThread state change callback +/** + * Set FuriThread state change callback * @param thread - FuriThread instance * @param callack - state change callback */ void furi_thread_set_state_callback(FuriThread* thread, FuriThreadStateCallback callback); -/* Set FuriThread state change context +/** + * Set FuriThread state change context * @param thread - FuriThread instance * @param context - pointer to context */ void furi_thread_set_state_context(FuriThread* thread, void* context); -/* Get FuriThread state +/** + * Get FuriThread state * @param thread - FuriThread instance * @return thread state from FuriThreadState */ FuriThreadState furi_thread_get_state(FuriThread* thread); -/* Start FuriThread +/** + * Start FuriThread * @param thread - FuriThread instance * @return true on success */ bool furi_thread_start(FuriThread* thread); -/* Treminate FuriThread +/** + * Treminate FuriThread * @param thread - FuriThread instance * @return osStatus_t * @warning terminating statefull thread is dangerous @@ -97,7 +110,8 @@ bool furi_thread_start(FuriThread* thread); */ osStatus_t furi_thread_terminate(FuriThread* thread); -/* Join FuriThread +/** + * Join FuriThread * @param thread - FuriThread instance * @return osStatus_t */ diff --git a/core/furi/valuemutex.h b/core/furi/valuemutex.h index df224e1a..84a08093 100644 --- a/core/furi/valuemutex.h +++ b/core/furi/valuemutex.h @@ -7,13 +7,13 @@ extern "C" { #endif -/* -== ValueMutex == +/** + * == ValueMutex == -The most simple concept is ValueMutex. -It is wrapper around mutex and value pointer. -You can take and give mutex to work with value and read and write value. -*/ + * The most simple concept is ValueMutex. + * It is wrapper around mutex and value pointer. + * You can take and give mutex to work with value and read and write value. + */ typedef struct { void* value; @@ -21,36 +21,36 @@ typedef struct { osMutexId_t mutex; } ValueMutex; -/* -Creates ValueMutex. -*/ +/** + * Creates ValueMutex. + */ bool init_mutex(ValueMutex* valuemutex, void* value, size_t size); -/* -Free resources allocated by `init_mutex`. -This function doesn't free the memory occupied by `ValueMutex` itself. -*/ +/** + * Free resources allocated by `init_mutex`. + * This function doesn't free the memory occupied by `ValueMutex` itself. + */ bool delete_mutex(ValueMutex* valuemutex); -/* -Call for work with data stored in mutex. -Returns pointer to data if success, NULL otherwise. -*/ +/** + * Call for work with data stored in mutex. + * @return pointer to data if success, NULL otherwise. + */ void* acquire_mutex(ValueMutex* valuemutex, uint32_t timeout); -/* -Helper: infinitly wait for mutex -*/ +/** + * Helper: infinitly wait for mutex + */ static inline void* acquire_mutex_block(ValueMutex* valuemutex) { return acquire_mutex(valuemutex, osWaitForever); } -/* +/** * With statement for value mutex, acts as lambda * @param name a resource name, const char* * @param function_body a (){} lambda declaration, * executed within you parent function context. -*/ + */ #define with_value_mutex(value_mutex, function_body) \ { \ void* p = acquire_mutex_block(value_mutex); \ @@ -59,16 +59,16 @@ static inline void* acquire_mutex_block(ValueMutex* valuemutex) { release_mutex(value_mutex, p); \ } -/* -Release mutex after end of work with data. -Call `release_mutex` and pass ValueData instance and pointer to data. -*/ +/** + * Release mutex after end of work with data. + * Call `release_mutex` and pass ValueData instance and pointer to data. + */ bool release_mutex(ValueMutex* valuemutex, const void* value); -/* -Instead of take-access-give sequence you can use `read_mutex` and `write_mutex` functions. -Both functions return true in case of success, false otherwise. -*/ +/** + * Instead of take-access-give sequence you can use `read_mutex` and `write_mutex` functions. + * Both functions return true in case of success, false otherwise. + */ bool read_mutex(ValueMutex* valuemutex, void* data, size_t len, uint32_t timeout); bool write_mutex(ValueMutex* valuemutex, void* data, size_t len, uint32_t timeout); diff --git a/firmware/targets/api-hal-include/api-hal-boot.h b/firmware/targets/api-hal-include/api-hal-boot.h index 19785191..797b3ac7 100644 --- a/firmware/targets/api-hal-include/api-hal-boot.h +++ b/firmware/targets/api-hal-include/api-hal-boot.h @@ -4,11 +4,13 @@ extern "C" { #endif +/** Boot modes */ typedef enum { ApiHalBootModeNormal, ApiHalBootModeDFU } ApiHalBootMode; +/** Set boot mode */ void api_hal_boot_set_mode(ApiHalBootMode mode); #ifdef __cplusplus diff --git a/firmware/targets/api-hal-include/api-hal-bt.h b/firmware/targets/api-hal-include/api-hal-bt.h index 320d98aa..e6b0fcda 100644 --- a/firmware/targets/api-hal-include/api-hal-bt.h +++ b/firmware/targets/api-hal-include/api-hal-bt.h @@ -7,42 +7,43 @@ extern "C" { #endif -/* Initialize */ +/** Initialize */ void api_hal_bt_init(); -/* Start BLE app */ +/** Start BLE app */ bool api_hal_bt_start_app(); -/* Get BT/BLE system component state */ +/** Get BT/BLE system component state */ void api_hal_bt_dump_state(string_t buffer); -/* Get BT/BLE system component state */ +/** Get BT/BLE system component state */ bool api_hal_bt_is_alive(); -/* Lock shared access to flash controller +/** + * Lock shared access to flash controller * @return true if lock was successful, false if not */ bool api_hal_bt_lock_flash(); -/* Unlock shared access to flash controller */ +/** Unlock shared access to flash controller */ void api_hal_bt_unlock_flash(); -/* Start ble tone tx at given channel and power */ +/** Start ble tone tx at given channel and power */ void api_hal_bt_start_tone_tx(uint8_t tx_channel, uint8_t power); -/* Stop ble tone tx */ +/** Stop ble tone tx */ void api_hal_bt_stop_tone_tx(); -/* Start sending ble packets at a given frequency and datarate */ +/** Start sending ble packets at a given frequency and datarate */ void api_hal_bt_start_packet_tx(uint8_t frequency, uint8_t datarate); -/* Stop sending ble packets */ +/** Stop sending ble packets */ void api_hal_bt_stop_packet_tx(); -/* Set up the RF to listen to a given RF channel */ +/** Set up the RF to listen to a given RF channel */ void api_hal_bt_start_rx(uint8_t frequency); -/* Stop RF listenning */ +/** Stop RF listenning */ void api_hal_bt_stop_rx(); #ifdef __cplusplus diff --git a/firmware/targets/api-hal-include/api-hal-delay.h b/firmware/targets/api-hal-include/api-hal-delay.h index 9ca4a5a7..3a927bed 100644 --- a/firmware/targets/api-hal-include/api-hal-delay.h +++ b/firmware/targets/api-hal-include/api-hal-delay.h @@ -5,8 +5,16 @@ extern "C" { #endif +/** + * Delay in milliseconds + * @warning Cannot be used from ISR + */ void delay(float milliseconds); + +/** Delay in microseconds */ void delay_us(float microseconds); + +/** Init DWT */ void delay_us_init_DWT(void); #ifdef __cplusplus diff --git a/firmware/targets/api-hal-include/api-hal-i2c.h b/firmware/targets/api-hal-include/api-hal-i2c.h index 596fffd7..e34b5245 100644 --- a/firmware/targets/api-hal-include/api-hal-i2c.h +++ b/firmware/targets/api-hal-include/api-hal-i2c.h @@ -8,8 +8,18 @@ extern "C" { #endif +/** Init I2C */ void api_hal_i2c_init(); +/** + * Perform I2C tx transfer + * @param instance I2C_TypeDef instance + * @param address I2C slave address + * @param data pointer to data buffer + * @param size size of data buffer + * @param timeout timeout in CPU ticks + * @return true on successful transfer, false otherwise + */ bool api_hal_i2c_tx( I2C_TypeDef* instance, const uint8_t address, @@ -17,6 +27,15 @@ bool api_hal_i2c_tx( const uint8_t size, uint32_t timeout); +/** + * Perform I2C rx transfer + * @param instance I2C_TypeDef instance + * @param address I2C slave address + * @param data pointer to data buffer + * @param size size of data buffer + * @param timeout timeout in CPU ticks + * @return true on successful transfer, false otherwise + */ bool api_hal_i2c_rx( I2C_TypeDef* instance, const uint8_t address, @@ -24,6 +43,17 @@ bool api_hal_i2c_rx( const uint8_t size, uint32_t timeout); +/** + * Perform I2C tx and rx transfers + * @param instance I2C_TypeDef instance + * @param address I2C slave address + * @param tx_data pointer to tx data buffer + * @param tx_size size of tx data buffer + * @param rx_data pointer to rx data buffer + * @param rx_size size of rx data buffer + * @param timeout timeout in CPU ticks + * @return true on successful transfer, false otherwise + */ bool api_hal_i2c_trx( I2C_TypeDef* instance, const uint8_t address, @@ -33,10 +63,18 @@ bool api_hal_i2c_trx( const uint8_t rx_size, uint32_t timeout); +/** Acquire I2C mutex */ void api_hal_i2c_lock(); +/** Release I2C mutex */ void api_hal_i2c_unlock(); +/** + * With clause for I2C peripheral + * @param type type of function_body + * @param pointer pointer to return of function_body + * @param function_body a (){} lambda declaration, executed with I2C mutex acquired + */ #define with_api_hal_i2c(type, pointer, function_body) \ { \ api_hal_i2c_lock(); \ diff --git a/firmware/targets/api-hal-include/api-hal-light.h b/firmware/targets/api-hal-include/api-hal-light.h index 1d571f06..fd5fa458 100644 --- a/firmware/targets/api-hal-include/api-hal-light.h +++ b/firmware/targets/api-hal-include/api-hal-light.h @@ -8,8 +8,14 @@ extern "C" { #endif +/** Init light driver */ void api_hal_light_init(); +/** + * Set light value + * @param light - Light + * @param value - light brightness [0-255] + */ void api_hal_light_set(Light light, uint8_t value); #ifdef __cplusplus diff --git a/firmware/targets/api-hal-include/api-hal-power.h b/firmware/targets/api-hal-include/api-hal-power.h index 1c7a3b63..505c2d2e 100644 --- a/firmware/targets/api-hal-include/api-hal-power.h +++ b/firmware/targets/api-hal-include/api-hal-power.h @@ -8,89 +8,89 @@ extern "C" { #endif +/** Power IC type */ typedef enum { ApiHalPowerICCharger, ApiHalPowerICFuelGauge, } ApiHalPowerIC; -/* Initialize drivers */ +/** Initialize drivers */ void api_hal_power_init(); -/* Get current insomnia level +/** + * Get current insomnia level * @return insomnia level: 0 - no insomnia, >0 - insomnia, bearer count. */ uint16_t api_hal_power_insomnia_level(); -/* Enter insomnia mode +/** + * Enter insomnia mode * Prevents device from going to sleep * @warning Internally increases insomnia level * Must be paired with api_hal_power_insomnia_exit */ void api_hal_power_insomnia_enter(); -/* Exit insomnia mode +/** + * Exit insomnia mode * Allow device to go to sleep * @warning Internally decreases insomnia level. * Must be paired with api_hal_power_insomnia_enter */ void api_hal_power_insomnia_exit(); -/* Check if deep sleep availble */ +/** Check if deep sleep availble */ bool api_hal_power_deep_available(); -/* Go to sleep */ +/** Go to sleep */ void api_hal_power_sleep(); -/* Get predicted remaining battery capacity in percents */ +/** Get predicted remaining battery capacity in percents */ uint8_t api_hal_power_get_pct(); -/* Get battery health state in percents */ +/** Get battery health state in percents */ uint8_t api_hal_power_get_bat_health_pct(); -/* Get charging status */ +/** Get charging status */ bool api_hal_power_is_charging(); -/* Poweroff system */ +/** Poweroff system */ void api_hal_power_off(); -/* OTG enable */ +/** OTG enable */ void api_hal_power_enable_otg(); -/* OTG disable */ +/** OTG disable */ void api_hal_power_disable_otg(); -/* Get remaining battery battery capacity in mAh */ +/** Get remaining battery battery capacity in mAh */ uint32_t api_hal_power_get_battery_remaining_capacity(); -/* Get full charge battery capacity in mAh */ +/** Get full charge battery capacity in mAh */ uint32_t api_hal_power_get_battery_full_capacity(); -/* Get battery voltage in V */ +/** Get battery voltage in V */ float api_hal_power_get_battery_voltage(ApiHalPowerIC ic); -/* Get battery current in A */ +/** Get battery current in A */ float api_hal_power_get_battery_current(ApiHalPowerIC ic); -/* Get temperature in C */ +/** Get temperature in C */ float api_hal_power_get_battery_temperature(ApiHalPowerIC ic); -/* Get System voltage in V */ +/** Get System voltage in V */ float api_hal_power_get_system_voltage(); -/* Get USB voltage in V */ +/** Get USB voltage in V */ float api_hal_power_get_usb_voltage(); -/* Get power system component state */ +/** Get power system component state */ void api_hal_power_dump_state(string_t buffer); -/** - * @brief Enable 3.3v on external gpio and sd card - */ +/** Enable 3.3v on external gpio and sd card */ void api_hal_power_enable_external_3_3v(); -/** - * @brief Disable 3.3v on external gpio and sd card - */ +/** Disable 3.3v on external gpio and sd card */ void api_hal_power_disable_external_3_3v(); #ifdef __cplusplus diff --git a/firmware/targets/api-hal-include/api-hal-sd.h b/firmware/targets/api-hal-include/api-hal-sd.h index 8d9f1374..ab67022b 100644 --- a/firmware/targets/api-hal-include/api-hal-sd.h +++ b/firmware/targets/api-hal-include/api-hal-sd.h @@ -5,21 +5,14 @@ extern "C" { #endif -/** - * @brief Init SD card detect - * - */ +/** Init SD card detect */ void hal_sd_detect_init(void); -/** - * @brief Set SD card detect pin to low - * - */ +/** Set SD card detect pin to low */ void hal_sd_detect_set_low(void); /** - * @brief Get SD card status - * + * Get SD card status * @return true if SD card present * @return false if SD card not present */ diff --git a/firmware/targets/api-hal-include/api-hal-subghz.h b/firmware/targets/api-hal-include/api-hal-subghz.h index 1321bcb3..650374ad 100644 --- a/firmware/targets/api-hal-include/api-hal-subghz.h +++ b/firmware/targets/api-hal-include/api-hal-subghz.h @@ -4,6 +4,7 @@ extern "C" { #endif +/** Sub-GHz band type */ typedef enum { RfBandIsolation = 0, RfBand1 = 1, @@ -11,6 +12,10 @@ typedef enum { RfBand3 = 3 } RfBand; +/** + * Set Sub-GHz band + * @param band RfBand + */ void api_hal_rf_band_set(RfBand band); #ifdef __cplusplus diff --git a/firmware/targets/api-hal-include/api-hal-uid.h b/firmware/targets/api-hal-include/api-hal-uid.h index fe822924..bf15e663 100644 --- a/firmware/targets/api-hal-include/api-hal-uid.h +++ b/firmware/targets/api-hal-include/api-hal-uid.h @@ -7,10 +7,10 @@ extern "C" { #endif -/* Get platform UID size in bytes */ +/** Get platform UID size in bytes */ size_t api_hal_uid_size(); -/* Get const pointer to UID */ +/** Get const pointer to UID */ const uint8_t* api_hal_uid(); #ifdef __cplusplus diff --git a/firmware/targets/api-hal-include/api-hal-vcp.h b/firmware/targets/api-hal-include/api-hal-vcp.h index 3d6d53ab..129e6d34 100644 --- a/firmware/targets/api-hal-include/api-hal-vcp.h +++ b/firmware/targets/api-hal-include/api-hal-vcp.h @@ -8,12 +8,14 @@ extern "C" { #endif -/* Init VCP HAL +/** + * Init VCP HAL * Allocates ring buffer and initializes state */ void api_hal_vcp_init(); -/* Recieve data from VCP +/** + * Recieve data from VCP * Waits till some data arrives, never returns 0 * @param buffer - pointer to buffer * @param size - buffer size @@ -21,7 +23,8 @@ void api_hal_vcp_init(); */ size_t api_hal_vcp_rx(uint8_t* buffer, size_t size); -/* Transmit data to VCP +/** + * Transmit data to VCP * @param buffer - pointer to buffer * @param size - buffer size */ diff --git a/firmware/targets/api-hal-include/api-hal-version.h b/firmware/targets/api-hal-include/api-hal-version.h index 44a4e96a..88e5bcb2 100644 --- a/firmware/targets/api-hal-include/api-hal-version.h +++ b/firmware/targets/api-hal-include/api-hal-version.h @@ -8,18 +8,25 @@ extern "C" { #endif +/** Check target firmware version */ bool api_hal_version_do_i_belong_here(); +/** Get hardware version */ const uint8_t api_hal_version_get_hw_version(); +/** Get hardware target */ const uint8_t api_hal_version_get_hw_target(); +/** Get hardware body */ const uint8_t api_hal_version_get_hw_body(); +/** Get hardware connect */ const uint8_t api_hal_version_get_hw_connect(); +/** Get hardware timestamp */ const uint32_t api_hal_version_get_hw_timestamp(); +/** Get pointer to target name */ const char * api_hal_version_get_name_ptr(); #ifdef __cplusplus diff --git a/firmware/targets/api-hal-include/api-hal-vibro.h b/firmware/targets/api-hal-include/api-hal-vibro.h index 586b31f1..088dbb40 100644 --- a/firmware/targets/api-hal-include/api-hal-vibro.h +++ b/firmware/targets/api-hal-include/api-hal-vibro.h @@ -8,10 +8,10 @@ extern "C" { #endif -/* Initialize vibro */ +/** Initialize vibro */ void api_hal_vibro_init(); -/* Turn on/off vibro */ +/** Turn on/off vibro */ void api_hal_vibro_on(bool value); #ifdef __cplusplus diff --git a/firmware/targets/api-hal-include/api-hal.h b/firmware/targets/api-hal-include/api-hal.h index 5a6fdd93..f78bd7ec 100644 --- a/firmware/targets/api-hal-include/api-hal.h +++ b/firmware/targets/api-hal-include/api-hal.h @@ -24,4 +24,5 @@ template struct STOP_EXTERNING_ME {}; #include "api-hal-subghz.h" #include "api-hal-vibro.h" +/** Init api-hal */ void api_hal_init(); diff --git a/lib/drivers/bq25896.h b/lib/drivers/bq25896.h index 06e33c18..ee5ad09b 100644 --- a/lib/drivers/bq25896.h +++ b/lib/drivers/bq25896.h @@ -3,32 +3,32 @@ #include #include -/* Initialize Driver */ +/** Initialize Driver */ void bq25896_init(); -/* Send device into shipping mode */ +/** Send device into shipping mode */ void bq25896_poweroff(); -/* Is currently charging */ +/** Is currently charging */ bool bq25896_is_charging(); -/* Enable otg */ +/** Enable otg */ void bq25896_enable_otg(); -/* Disable otg */ +/** Disable otg */ void bq25896_disable_otg(); -/* Get VBUS Voltage in mV */ +/** Get VBUS Voltage in mV */ uint16_t bq25896_get_vbus_voltage(); -/* Get VSYS Voltage in mV */ +/** Get VSYS Voltage in mV */ uint16_t bq25896_get_vsys_voltage(); -/* Get VBAT Voltage in mV */ +/** Get VBAT Voltage in mV */ uint16_t bq25896_get_vbat_voltage(); -/* Get VBAT current in mA */ +/** Get VBAT current in mA */ uint16_t bq25896_get_vbat_current(); -/* Get NTC voltage in mpct of REGN */ +/** Get NTC voltage in mpct of REGN */ uint32_t bq25896_get_ntc_mpct(); diff --git a/lib/drivers/bq27220.h b/lib/drivers/bq27220.h index d55c2bb7..4512db46 100644 --- a/lib/drivers/bq27220.h +++ b/lib/drivers/bq27220.h @@ -43,32 +43,32 @@ typedef struct { uint8_t RSVD0 : 5; } OperationStatus; -/* Initialize Driver */ +/** Initialize Driver */ void bq27220_init(); -/* Get battery voltage in mV or error */ +/** Get battery voltage in mV or error */ uint16_t bq27220_get_voltage(); -/* Get current in mA or error*/ +/** Get current in mA or error*/ int16_t bq27220_get_current(); -/* Get battery status */ +/** Get battery status */ uint8_t bq27220_get_battery_status(BatteryStatus* battery_status); -/* Get operation status */ +/** Get operation status */ uint8_t bq27220_get_operation_status(OperationStatus* operation_status); -/* Get temperature in units of 0.1°K */ +/** Get temperature in units of 0.1°K */ uint16_t bq27220_get_temperature(); -/* Get compensated full charge capacity in in mAh */ +/** Get compensated full charge capacity in in mAh */ uint16_t bq27220_get_full_charge_capacity(); -/* Get remaining capacity in in mAh */ +/** Get remaining capacity in in mAh */ uint16_t bq27220_get_remaining_capacity(); -/* Get predicted remaining battery capacity in percents */ +/** Get predicted remaining battery capacity in percents */ uint16_t bq27220_get_state_of_charge(); -/* Get ratio of full charge capacity over design capacity in percents */ +/** Get ratio of full charge capacity over design capacity in percents */ uint16_t bq27220_get_state_of_health(); diff --git a/lib/drivers/lp5562.h b/lib/drivers/lp5562.h index 7096f738..b58e2ee0 100644 --- a/lib/drivers/lp5562.h +++ b/lib/drivers/lp5562.h @@ -3,6 +3,7 @@ #include #include +/** Channel types */ typedef enum { LP5562ChannelRed, LP5562ChannelGreen, @@ -10,13 +11,17 @@ typedef enum { LP5562ChannelWhite, } LP5562Channel; -/* Initialize Driver */ +/** Initialize Driver */ void lp5562_reset(); +/** Configure Driver */ void lp5562_configure(); +/** Enable Driver */ void lp5562_enable(); +/** Set channel current */ void lp5562_set_channel_current(LP5562Channel channel, uint8_t value); +/** Set channel current */ void lp5562_set_channel_value(LP5562Channel channel, uint8_t value);