1 /* 2 * Copyright (c) 2020-2021 Huawei Device Co., Ltd. 3 * 4 * HDF is dual licensed: you can use it either under the terms of 5 * the GPL, or the BSD license, at your option. 6 * See the LICENSE file in the root of this repository for complete details. 7 */ 8 9 /** 10 * @addtogroup PWM 11 * @{ 12 * 13 * @brief Provides standard pulse width modulation (PWM) interfaces for driver development. 14 * 15 * The PWM module abstracts the PWM capabilities of different system platforms to provide stable APIs for driver 16 * development. You can use this module to create/release PWM device handles, set the PWM period, polarity, and duty 17 * cycle, enable/disable PWM devices, and set/obtain the PWM configuration. 18 * 19 * @since 1.0 20 */ 21 22 /** 23 * @file pwm_if.h 24 * 25 * @brief Declares standard PWM interfaces for driver development. 26 * 27 * A driver needs to use the PWM interfaces to perform operations on a PWM device. 28 * 29 * @since 1.0 30 */ 31 32 #ifndef PWM_IF_H 33 #define PWM_IF_H 34 35 #include "platform_if.h" 36 37 #ifdef __cplusplus 38 #if __cplusplus 39 extern "C" { 40 #endif 41 #endif /* __cplusplus */ 42 43 /** 44 * @brief Indicates the normal polarity of a PWM device. 45 * 46 * @since 1.0 47 */ 48 #define PWM_NORMAL_POLARITY 0 49 50 /** 51 * @brief Indicates the inverted polarity of a PWM device. 52 * 53 * @since 1.0 54 */ 55 #define PWM_INVERTED_POLARITY 1 56 57 /** 58 * @brief Indicates that a PWM device is in the disabled state. 59 * 60 * @since 1.0 61 */ 62 #define PWM_DISABLE_STATUS 0 63 64 /** 65 * @brief Indicates that a PWM device is in the enabled state. 66 * 67 * @since 1.0 68 */ 69 #define PWM_ENABLE_STATUS 1 70 71 /** 72 * @brief Enumerates PWM I/O commands. 73 * 74 * @since 1.0 75 */ 76 enum PwmIoCmd { 77 PWM_IO_GET = 0, /**< Get the PWM device. */ 78 PWM_IO_PUT, /**< Put the PWM device. */ 79 PWM_IO_SET_CONFIG, /**< Set config. */ 80 PWM_IO_GET_CONFIG, /**< Get config. */ 81 }; 82 83 /** 84 * @brief Defines the PWM device configuration parameters. 85 * 86 * @attention The specific PWM device determines which variables in this structure are supported. 87 * 88 * @since 1.0 89 */ 90 struct PwmConfig { 91 uint32_t duty; /**< Duty cycle, in nanoseconds */ 92 uint32_t period; /**< PWM period, in nanoseconds */ 93 uint32_t number; /**< Number of square waves to generate. A positive value indicates that 94 * the specified number of square waves will be generated, and <b>0</b> indicates 95 * that square waves will be continuously generated. 96 */ 97 uint8_t polarity; /**< Polarity 98 * --------------------- | --------------------- 99 * PWM_NORMAL_POLARITY | Normal polarity 100 * PWM_INVERTED_POLARITY | Inverted polarity 101 */ 102 uint8_t status; /**< Running status 103 * ------------------ | ------------------ 104 * PWM_DISABLE_STATUS | Disabled 105 * PWM_ENABLE_STATUS | Enabled 106 */ 107 }; 108 109 /** 110 * @brief Obtains the PWM device handle. 111 * 112 * @param num Indicates the PWM device number. 113 * 114 * @return Returns the PWM device handle if the operation is successful; returns <b>NULL</b> otherwise. 115 * 116 * @since 1.0 117 */ 118 DevHandle PwmOpen(uint32_t num); 119 120 /** 121 * @brief Releases the PWM device handle. 122 * 123 * @param handle Indicates the PWM device handle obtained via {@link PwmOpen}. 124 * 125 * @since 1.0 126 */ 127 void PwmClose(DevHandle handle); 128 129 /** 130 * @brief Sets the PWM period. 131 * 132 * @param handle Indicates the PWM device handle obtained via {@link PwmOpen}. 133 * @param period Indicates the PWM device period to set, in nanoseconds. 134 * 135 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 136 * 137 * @since 1.0 138 */ 139 int32_t PwmSetPeriod(DevHandle handle, uint32_t period); 140 141 /** 142 * @brief Sets the PWM duty cycle. 143 * 144 * @param handle Indicates the PWM device handle obtained via {@link PwmOpen}. 145 * @param duty Indicates the duty cycle to set, in nanoseconds. 146 * 147 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 148 * 149 * @since 1.0 150 */ 151 int32_t PwmSetDuty(DevHandle handle, uint32_t duty); 152 153 /** 154 * @brief Sets the PWM polarity. 155 * 156 * @param handle Indicates the PWM device handle obtained via {@link PwmOpen}. 157 * @param polarity Indicates the polarity to set, which can be {@link PWM_NORMAL_POLARITY} 158 * or {@link PWM_INVERTED_POLARITY}. 159 * 160 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 161 * 162 * @since 1.0 163 */ 164 int32_t PwmSetPolarity(DevHandle handle, uint8_t polarity); 165 166 /** 167 * @brief Enables the PWM device. 168 * 169 * @param handle Indicates the PWM device handle obtained via {@link PwmOpen}. 170 * 171 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 172 * 173 * @since 1.0 174 */ 175 int32_t PwmEnable(DevHandle handle); 176 177 /** 178 * @brief Disables the PWM device. 179 * 180 * @param handle Indicates the PWM device handle obtained via {@link PwmOpen}. 181 * 182 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 183 * 184 * @since 1.0 185 */ 186 int32_t PwmDisable(DevHandle handle); 187 188 /** 189 * @brief Sets the PWM device configuration parameters. 190 * 191 * @param handle Indicates the PWM device handle obtained via {@link PwmOpen}. 192 * @param config Indicates the pointer to the {@link PwmConfig} structure that 193 * contains PWM device configuration parameters. 194 * 195 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 196 * 197 * @since 1.0 198 */ 199 int32_t PwmSetConfig(DevHandle handle, struct PwmConfig *config); 200 201 /** 202 * @brief Obtains the PWM device configuration parameters. 203 * 204 * @param handle Indicates the PWM device handle obtained via {@link PwmOpen}. 205 * @param config Indicates the pointer to the {@link PwmConfig} structure that contains 206 * PWM device configuration parameters. 207 * 208 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 209 * 210 * @since 1.0 211 */ 212 int32_t PwmGetConfig(DevHandle handle, struct PwmConfig *config); 213 214 #ifdef __cplusplus 215 #if __cplusplus 216 } 217 #endif 218 #endif /* __cplusplus */ 219 220 #endif /* PWM_IF_H */ 221 /** @} */ 222