1 /** 2 * Copyright (c) 2020 HiSilicon (Shanghai) Technologies CO., LIMITED. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 * 15 * Description: Provides PWM driver api \n 16 * 17 * History: \n 18 * 2022-09-16， Create file. \n 19 */ 20 21 #ifndef PWM_H 22 #define PWM_H 23 24 #include <stdint.h> 25 #include <stdbool.h> 26 #include "errcode.h" 27 28 #ifdef __cplusplus 29 #if __cplusplus 30 extern "C" { 31 #endif /* __cplusplus */ 32 #endif /* __cplusplus */ 33 34 /** 35 * @defgroup drivers_driver_pwm PWM 36 * @ingroup drivers_driver 37 * @{ 38 */ 39 40 /** 41 * @if Eng 42 * @brief Definition of PWM configuration. 43 * @else 44 * @brief PWM配置类型定义。 45 * @endif 46 */ 47 typedef struct pwm_config { 48 uint32_t low_time; /*!< @if Eng PWM working clock cycle count low level part, 49 PWM work frequency @ref uapi_pwm_get_frequency(). 50 If the PWM operating cycle is Tus, 51 the actual low-level time = low_time * Tus. 52 @else PWM工作时钟周期计数个数低电平部分， 53 频率参考 @ref uapi_pwm_get_frequency()。 54 如果PWM工作周期为Tus, 实际低电平时间 = low_time * Tus @endif */ 55 uint32_t high_time; /*!< @if Eng PWM working clock cycle count high level part, 56 PWM work frequency @ref uapi_pwm_get_frequency(). 57 If the PWM operating cycle is Tus, 58 the actual high-level time = high_time * Tus. 59 @else PWM工作时钟周期计数个数高电平部分， 60 频率参考 @ref uapi_pwm_get_frequency()。 61 如果PWM工作周期为Tus, 实际高电平时间 = high_time * Tus @endif */ 62 uint32_t offset_time; /*!< @if Eng PWM offset time. 63 @else PWM相位。 @endif */ 64 uint16_t cycles; /*!< @if Eng PWM cycles, range:0~32767 (15bit). 65 @else PWM重复周期，范围：0~32767 (15bit)。 @endif */ 66 bool repeat; /*!< @if Eng Flag to indicate PWM should output continuously. 67 @else 指示PWM应连续输出的标志。 @endif */ 68 } pwm_config_t; 69 70 /** 71 * @if Eng 72 * @brief Definition of PWM callback type. 73 * @param [in] channel PWM device. 74 * @retval ERRCODE_SUCC Success. 75 * @retval Other Failure. For details, see @ref errcode_t. 76 * @else 77 * @brief PWM 回调类型定义。 78 * @param [in] channel PWM设备。 79 * @retval ERRCODE_SUCC 成功。 80 * @retval Other 失败，参考 @ref errcode_t 。 81 * @endif 82 */ 83 typedef errcode_t (*pwm_callback_t)(uint8_t channel); 84 85 /** 86 * @if Eng 87 * @brief Initialize the PWM. 88 * @retval ERRCODE_SUCC Success. 89 * @retval Other Failure. For details, see @ref errcode_t. 90 * @else 91 * @brief 初始化PWM。 92 * @retval ERRCODE_SUCC 成功。 93 * @retval Other 失败，参考 @ref errcode_t 。 94 * @endif 95 */ 96 errcode_t uapi_pwm_init(void); 97 98 /** 99 * @if Eng 100 * @brief Deinitialize the PWM. 101 * @else 102 * @brief 去初始化PWM。 103 * @endif 104 */ 105 void uapi_pwm_deinit(void); 106 107 /** 108 * @if Eng 109 * @brief Open a PWM device with the specified configuration. 110 * @param [in] channel PWM channel to use. For details, see @ref pwm_channel_t. 111 * @param [in] cfg Config set to the PWM device. For details, see @ref pwm_config_t. 112 * @retval ERRCODE_SUCC Success. 113 * @retval Other Failure. For details, see @ref errcode_t. 114 * @else 115 * @brief 打开具有指定配置的PWM通道。 116 * @param [in] channel PWM通道，参考 @ref pwm_channel_t 。 117 * @param [in] cfg PWM设备的配置信息，参考 @ref pwm_config_t 。 118 * @retval ERRCODE_SUCC 成功。 119 * @retval Other 失败，参考 @ref errcode_t 。 120 * @endif 121 */ 122 errcode_t uapi_pwm_open(uint8_t channel, const pwm_config_t *cfg); 123 124 /** 125 * @if Eng 126 * @brief Close the specified PWM. 127 * @param [in] channel PWM channel to use. For details, see @ref pwm_channel_t. 128 * @retval ERRCODE_SUCC Success. 129 * @retval Other Failure. For details, see @ref errcode_t. 130 * @else 131 * @brief 关闭指定的PWM。 132 * @param [in] channel PWM通道，参考 @ref pwm_channel_t 。 133 * @retval ERRCODE_SUCC 成功。 134 * @retval Other 失败，参考 @ref errcode_t 。 135 * @endif 136 */ 137 errcode_t uapi_pwm_close(uint8_t channel); 138 139 /** 140 * @if Eng 141 * @brief Start up PWM. 142 * @param [in] channel PWM channel to use. For details, see @ref pwm_channel_t. 143 * @retval ERRCODE_SUCC Success. 144 * @retval Other Failure. For details, see @ref errcode_t. 145 * @else 146 * @brief 开始PWM。 147 * @param [in] channel PWM通道，参考 @ref pwm_channel_t 。 148 * @retval ERRCODE_SUCC 成功。 149 * @retval Other 失败，参考 @ref errcode_t 。 150 * @endif 151 */ 152 errcode_t uapi_pwm_start(uint8_t channel); 153 154 /** 155 * @if Eng 156 * @brief Get PWM work frequency. 157 * @param [in] channel PWM channel to use. For details, see @ref pwm_channel_t. 158 * @retval PWM work frequency, the unit is HZ. 159 * @else 160 * @brief 获取PWM工作频率。 161 * @param [in] channel PWM通道，参考 @ref pwm_channel_t 。 162 * @retval PWM工作频率，单位为HZ。 163 * @endif 164 */ 165 uint32_t uapi_pwm_get_frequency(uint8_t channel); 166 167 #if defined(CONFIG_PWM_USING_V150) 168 /** 169 * @if Eng 170 * @brief Stop a running PWM. 171 * @param [in] channel PWM channel to use. For details, see @ref pwm_channel_t. 172 * @retval ERRCODE_SUCC Success. 173 * @retval Other Failure. For details, see @ref errcode_t. 174 * @else 175 * @brief 停止正在运行的PWM。 176 * @param [in] channel PWM通道，参考 @ref pwm_channel_t 。 177 * @retval ERRCODE_SUCC 成功。 178 * @retval Other 失败，参考 @ref errcode_t 。 179 * @endif 180 */ 181 errcode_t uapi_pwm_stop(uint8_t channel); 182 183 /** 184 * @if Eng 185 * @brief Update the duty ratio on a opened PWM. 186 * @param [in] channel PWM channel to use. For details, see @ref pwm_channel_t. 187 * @param [in] low_time PWM working clock cycle count low level part, PWM work freq @ref uapi_pwm_get_frequency(). 188 If the PWM operating cycle is Tus, the actual low-level time = low_time * Tus. 189 * @param [in] high_time PWM working clock cycle count high level part, PWM work freq @ref uapi_pwm_get_frequency(). 190 If the PWM operating cycle is Tus, the actual high-level time = high_time * Tus. 191 * @retval ERRCODE_SUCC Success. 192 * @retval Other Failure. For details, see @ref errcode_t. 193 * @else 194 * @brief 更新打开的PWM上的占空比。 195 * @param [in] channel PWM通道，参考 @ref pwm_channel_t 。 196 * @param [in] low_time PWM工作时钟周期计数个数低电平部分，频率参考 @ref uapi_pwm_get_frequency()。 197 如果PWM工作周期为Tus, 实际低电平时间 = low_time * Tus。 198 * @param [in] high_time PWM工作时钟周期计数个数高电平部分，频率参考 @ref uapi_pwm_get_frequency()。 199 如果PWM工作周期为Tus, 实际高电平时间 = high_time * Tus。 200 * @retval ERRCODE_SUCC 成功。 201 * @retval Other 失败，参考 @ref errcode_t 。 202 * @endif 203 */ 204 errcode_t uapi_pwm_update_duty_ratio(uint8_t channel, uint32_t low_time, uint32_t high_time); 205 #endif /* CONFIG_PWM_USING_V150 */ 206 207 /** 208 * @if Eng 209 * @brief PWM Interrupt Service Routine. 210 * @param [in] channel PWM channel to use. For details, see @ref pwm_channel_t. 211 * @retval ERRCODE_SUCC Success. 212 * @retval Other Failure. For details, see @ref errcode_t. 213 * @else 214 * @brief PWM中断服务例程。 215 * @param [in] channel PWM通道，参考 @ref pwm_channel_t 。 216 * @retval ERRCODE_SUCC 成功。 217 * @retval Other 失败，参考 @ref errcode_t 。 218 * @endif 219 */ 220 errcode_t uapi_pwm_isr(uint8_t channel); 221 222 /** 223 * @if Eng 224 * @brief Register an interrupt callback for PWM. 225 * @param [in] channel PWM channel to use. For details, see @ref pwm_channel_t. 226 * @param [in] callback Callback to register. 227 * @retval ERRCODE_SUCC Success. 228 * @retval Other Failure. For details, see @ref errcode_t. 229 * @else 230 * @brief 为PWM注册中断回调。 231 * @param [in] channel PWM通道，参考 @ref pwm_channel_t 。 232 * @param [in] callback 回调函数。 233 * @retval ERRCODE_SUCC 成功。 234 * @retval Other 失败，参考 @ref errcode_t 。 235 * @endif 236 */ 237 errcode_t uapi_pwm_register_interrupt(uint8_t channel, pwm_callback_t callback); 238 239 /** 240 * @if Eng 241 * @brief Unregister an interrupt callback. 242 * @param [in] channel PWM channel to use. For details, see @ref pwm_channel_t. 243 * @retval ERRCODE_SUCC Success. 244 * @retval Other Failure. For details, see @ref errcode_t. 245 * @else 246 * @brief 去注册中断回调。 247 * @param [in] channel PWM通道，参考 @ref pwm_channel_t 。 248 * @retval ERRCODE_SUCC 成功。 249 * @retval Other 失败，参考 @ref errcode_t 。 250 * @endif 251 */ 252 errcode_t uapi_pwm_unregister_interrupt(uint8_t channel); 253 254 #if defined(CONFIG_PWM_USING_V151) 255 /** 256 * @if Eng 257 * @brief Grouping the channels for PWM channels into one group. 258 * @param [in] group The group ID which can be from 0 to CONFIG_PWM_GROUP_NUM. 259 * @param [in] channel_set Set of channels to be grouped. 260 * @param [in] channel_set_len Length of the channel set. 261 * @retval ERRCODE_SUCC Success. 262 * @retval Other Failure. For details, see @ref errcode_t. 263 * @else 264 * @brief 为PWM通道分组。 265 * @param [in] group PWM组。 266 * @param [in] channel_set 进行分组设置的通道集合。 267 * @param [in] channel_set_len 进行分组设置的通道集合长度。 268 * @retval ERRCODE_SUCC 成功。 269 * @retval Other 失败，参考 @ref errcode_t 。 270 * @endif 271 */ 272 errcode_t uapi_pwm_set_group(uint8_t group, const uint8_t *channel_set, uint32_t channel_set_len); 273 274 /** 275 * @if Eng 276 * @brief Clear PWM channel of the group. 277 * @param [in] group The group ID which can be from 0 to CONFIG_PWM_GROUP_NUM. 278 * @retval ERRCODE_SUCC Success. 279 * @retval Other Failure. For details, see @ref errcode_t. 280 * @else 281 * @brief 清理PWM通道分组。 282 * @param [in] group PWM组。 283 * @retval ERRCODE_SUCC 成功。 284 * @retval Other 失败，参考 @ref errcode_t 。 285 * @endif 286 */ 287 errcode_t uapi_pwm_clear_group(uint8_t group); 288 289 /** 290 * @if Eng 291 * @brief Start up PWM of a group. 292 * @param [in] group The group ID which can be from 0 to CONFIG_PWM_GROUP_NUM. 293 * corresponds to a corresponding channel. 294 * @retval ERRCODE_SUCC Success. 295 * @retval Other Failure. For details, see @ref errcode_t. 296 * @else 297 * @brief 启动指定分组的PWM。 298 * @param [in] group PWM组。 299 * @retval ERRCODE_SUCC 成功。 300 * @retval Other 失败，参考 @ref errcode_t 。 301 * @endif 302 */ 303 errcode_t uapi_pwm_start_group(uint8_t group); 304 305 /** 306 * @if Eng 307 * @brief Stop PWM of a group 308 * @param [in] group The group ID which can be from 0 to CONFIG_PWM_GROUP_NUM. 309 * @retval ERRCODE_SUCC Success. 310 * @retval Other Failure. For details, see @ref errcode_t. 311 * @else 312 * @brief 停止指定分组的PWM。 313 * @param [in] group PWM组。 314 * @retval ERRCODE_SUCC 成功。 315 * @retval Other 失败，参考 @ref errcode_t 。 316 * @endif 317 */ 318 errcode_t uapi_pwm_stop_group(uint8_t group); 319 320 #if defined(CONFIG_PWM_PRELOAD) 321 /** 322 * @if Eng 323 * @brief PWM preload. When the previous PWM configuration is completed and configuration are auto loaded. 324 * @param [in] group The group ID which can be from 0 to CONFIG_PWM_GROUP_NUM. 325 * @param [in] channel PWM channel. For details, see @ref pwm_channel_t. 326 * @param [in] cfg Config set to the PWM device. 327 * @retval ERRCODE_SUCC Success. 328 * @retval Other Failure. For details, see @ref errcode_t. 329 * @else 330 * @brief PWM预配置，当上一个PWM配置完成时，此配置会自动加载。 331 * @param [in] group PWM组。 332 * @param [in] channel PWM通道，参考 @ref pwm_channel_t 。 333 * @param [in] cfg PWM设备的配置信息。 334 * @retval ERRCODE_SUCC 成功。 335 * @retval Other 失败，参考 @ref errcode_t 。 336 * @endif 337 */ 338 errcode_t uapi_pwm_config_preload(uint8_t group, uint8_t channel, const pwm_config_t *cfg); 339 #endif /* CONFIG_PWM_PRELOAD */ 340 #endif /* CONFIG_PWM_USING_V151 */ 341 342 /** 343 * @} 344 */ 345 346 #ifdef __cplusplus 347 #if __cplusplus 348 } 349 #endif /* __cplusplus */ 350 #endif /* __cplusplus */ 351 352 #endif 353