From 71daf49e397c6a1e72131523bda66aea30aeee73 Mon Sep 17 00:00:00 2001 From: Ivan Grokhotkov Date: Thu, 8 Dec 2016 18:37:22 +0800 Subject: [PATCH] driver/rtc_io: improve header comments Fix descriptions of return values, fix typos, use upper case for abbreviations. --- components/driver/include/driver/rtc_io.h | 108 ++++++++++++---------- 1 file changed, 57 insertions(+), 51 deletions(-) diff --git a/components/driver/include/driver/rtc_io.h b/components/driver/include/driver/rtc_io.h index 5196b058a5..2e351cf13a 100644 --- a/components/driver/include/driver/rtc_io.h +++ b/components/driver/include/driver/rtc_io.h @@ -27,136 +27,142 @@ extern "C" { * @brief Pullup/pulldown information for a single GPIO pad */ typedef struct { - uint32_t reg; /*!< Register of Rtc Pad */ - uint32_t mux; /*!< Mux seletct the Rtc pad is Digital Pad or Rtc pad */ - uint32_t func; /*!< Select Rtc Pad Func */ - uint32_t ie; /*!< Input Enable */ - uint32_t pullup; /*!< Pullup Enable */ - uint32_t pulldown; /*!< PullDown Enable */ - int rtc_num; /*!< The Rtc number */ + uint32_t reg; /*!< Register of RTC pad, or 0 if not an RTC GPIO */ + uint32_t mux; /*!< Bit mask for selecting digital pad or RTC pad */ + uint32_t func; /*!< Mask of RTC pad function */ + uint32_t ie; /*!< Mask of input enable */ + uint32_t pullup; /*!< Mask of pullup enable */ + uint32_t pulldown; /*!< Mask of pulldown enable */ + int rtc_num; /*!< RTC IO number, or -1 if not an RTC GPIO */ } rtc_gpio_desc_t; typedef enum { - RTC_GPIO_MODE_INPUT_ONLY , /*!< Pad output */ - RTC_GPIO_MODE_OUTPUT_ONLY, /*!< Pad input */ - RTC_GPIO_MODE_INPUT_OUTUT, /*!< Pad pull output + input */ - RTC_GPIO_MODE_DISABLED, /*!< Pad (output + input) disable */ + RTC_GPIO_MODE_INPUT_ONLY , /*!< Pad output */ + RTC_GPIO_MODE_OUTPUT_ONLY, /*!< Pad input */ + RTC_GPIO_MODE_INPUT_OUTUT, /*!< Pad pull output + input */ + RTC_GPIO_MODE_DISABLED, /*!< Pad (output + input) disable */ } rtc_gpio_mode_t; #define RTC_GPIO_IS_VALID_GPIO(gpio_num) ((gpio_num < GPIO_PIN_COUNT && rtc_gpio_desc[gpio_num].reg != 0)) //to decide whether it is a valid GPIO number -extern const rtc_gpio_desc_t rtc_gpio_desc[GPIO_PIN_COUNT] ; +extern const rtc_gpio_desc_t rtc_gpio_desc[GPIO_PIN_COUNT]; -/* - * @brief Init a gpio as rtc gpio +/** + * @brief Init a GPIO as RTC GPIO * - * when init a pad as analog function,need to call this funciton + * This function must be called when initializing a pad for an analog function. * - * @param gpio_num gpio_num GPIO number. If you want to set the trigger type of e.g. of GPIO16, gpio_num should be GPIO_NUM_12 (12); + * @param gpio_num GPIO number (e.g. GPIO_NUM_12) * * @return * - ESP_OK success - * - ESP_ERR_INVALID_ARG Parameter error + * - ESP_ERR_INVALID_ARG GPIO is not an RTC IO */ esp_err_t rtc_gpio_init(gpio_num_t gpio_num); /** - * @brief Init a gpio as digital gpio + * @brief Init a GPIO as digital GPIO * - * @param gpio_num gpio_num GPIO number. If you want to set the trigger type of e.g. of GPIO16, gpio_num should be GPIO_NUM_12 (12); + * @param gpio_num GPIO number (e.g. GPIO_NUM_12) * * @return * - ESP_OK success - * - ESP_ERR_INVALID_ARG Parameter error + * - ESP_ERR_INVALID_ARG GPIO is not an RTC IO */ esp_err_t rtc_gpio_deinit(gpio_num_t gpio_num); /** - * @brief Get the rtc io input level + * @brief Get the RTC IO input level * - * @param gpio_num gpio_num GPIO number. If you want to set the trigger type of e.g. of GPIO16, gpio_num should be GPIO_NUM_12 (12); + * @param gpio_num GPIO number (e.g. GPIO_NUM_12) * * @return * - 1 High level * - 0 Low level + * - ESP_ERR_INVALID_ARG GPIO is not an RTC IO */ uint32_t rtc_gpio_get_level(gpio_num_t gpio_num); /** - * @brief Set the rtc io output level + * @brief Set the RTC IO output level * - * @param gpio_num GPIO number. If you want to set the trigger type of e.g. of GPIO16, gpio_num should be GPIO_NUM_12 (12); - * @param level output level; + * @param gpio_num GPIO number (e.g. GPIO_NUM_12) + * @param level output level * * @return - * - 1 High level - * - 0 Low level + * - ESP_OK Success + * - ESP_ERR_INVALID_ARG GPIO is not an RTC IO */ esp_err_t rtc_gpio_set_level(gpio_num_t gpio_num, uint32_t level); /** - * @brief Rtc gpio set direction + * @brief RTC GPIO set direction * - * Configure Rtc gpio direction,such as output_only,input_only,output_and_input + * Configure RTC GPIO direction, such as output only, input only, + * output and input. * - * @param gpio_num Configure GPIO pins number, it should be GPIO number. If you want to set direction of e.g. GPIO12, gpio_num should be GPIO_NUM_12 (12); + * @param gpio_num GPIO number (e.g. GPIO_NUM_12) * @param mode GPIO direction * * @return * - ESP_OK Success - * - ESP_ERR_INVALID_ARG GPIO error + * - ESP_ERR_INVALID_ARG GPIO is not an RTC IO */ esp_err_t rtc_gpio_set_direction(gpio_num_t gpio_num, rtc_gpio_mode_t mode); /** - * @brief Rtc gpio pullup enable + * @brief RTC GPIO pullup enable * - * If the user needs to configure the GPIO pull ,Please call gpio_set_pull_mode.This function will be called in gpio_set_pull + * This function only works for RTC IOs. In general, call gpio_pullup_en, + * which will work both for normal GPIOs and RTC IOs. * - * @param gpio_num GPIO number. If you want to set pull up or down mode for e.g. GPIO12, gpio_num should be GPIO_NUM_12 (12); + * @param gpio_num GPIO number (e.g. GPIO_NUM_12) * * @return - * - True the gpio number is Rts pad - * - False the gpio number is Digital pad + * - ESP_OK Success + * - ESP_ERR_INVALID_ARG GPIO is not an RTC IO */ esp_err_t rtc_gpio_pullup_en(gpio_num_t gpio_num); /** - * @brief Rtc gpio pulldown enable + * @brief RTC GPIO pulldown enable * - * If the user needs to configure the GPIO pull ,Please call gpio_set_pull_mode.This function will be called in gpio_set_pull + * This function only works for RTC IOs. In general, call gpio_pulldown_en, + * which will work both for normal GPIOs and RTC IOs. * - * @param gpio_num GPIO number. If you want to set pull up or down mode for e.g. GPIO12, gpio_num should be GPIO_NUM_12 (12); + * @param gpio_num GPIO number (e.g. GPIO_NUM_12) * * @return - * - True the gpio number is Rts pad - * - False the gpio number is Digital pad + * - ESP_OK Success + * - ESP_ERR_INVALID_ARG GPIO is not an RTC IO */ esp_err_t rtc_gpio_pulldown_en(gpio_num_t gpio_num); /** - * @brief Rtc gpio pullup clear + * @brief RTC GPIO pullup disable * - * If the user needs to configure the GPIO pull ,Please call gpio_set_pull_mode.This function will be called in gpio_set_pull + * This function only works for RTC IOs. In general, call gpio_pullup_dis, + * which will work both for normal GPIOs and RTC IOs. * - * @param gpio_num GPIO number. If you want to set pull up or down mode for e.g. GPIO12, gpio_num should be GPIO_NUM_12 (12); + * @param gpio_num GPIO number (e.g. GPIO_NUM_12) * * @return - * - True the gpio number is Rts pad - * - False the gpio number is Digital pad + * - ESP_OK Success + * - ESP_ERR_INVALID_ARG GPIO is not an RTC IO */ esp_err_t rtc_gpio_pullup_dis(gpio_num_t gpio_num); /** - * @brief Rtc gpio pulldown clear + * @brief RTC GPIO pulldown disable * - * If the user needs to configure the GPIO pull ,Please call gpio_set_pull_mode.This function will be called in gpio_set_pull + * This function only works for RTC IOs. In general, call gpio_pulldown_dis, + * which will work both for normal GPIOs and RTC IOs. * - * @param gpio_num GPIO number. If you want to set pull up or down mode for e.g. GPIO12, gpio_num should be GPIO_NUM_12 (12); + * @param gpio_num GPIO number (e.g. GPIO_NUM_12) * * @return - * - True the gpio number is Rts pad - * - False the gpio number is Digital pad + * - ESP_OK Success + * - ESP_ERR_INVALID_ARG GPIO is not an RTC IO */ esp_err_t rtc_gpio_pulldown_dis(gpio_num_t gpio_num); -- 2.40.0