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 #pragma pack(push, 4) 91 struct PwmConfig { 92 uint32_t duty; /**< Duty cycle, in nanoseconds */ 93 uint32_t period; /**< PWM period, in nanoseconds */ 94 uint32_t number; /**< Number of square waves to generate. A positive value indicates that 95 * the specified number of square waves will be generated, and <b>0</b> indicates 96 * that square waves will be continuously generated. 97 */ 98 uint8_t polarity; /**< Polarity 99 * --------------------- | --------------------- 100 * PWM_NORMAL_POLARITY | Normal polarity 101 * PWM_INVERTED_POLARITY | Inverted polarity 102 */ 103 uint8_t status; /**< Running status 104 * ------------------ | ------------------ 105 * PWM_DISABLE_STATUS | Disabled 106 * PWM_ENABLE_STATUS | Enabled 107 */ 108 }; 109 #pragma pack(pop) 110 111 /** 112 * @brief Obtains the PWM device handle. 113 * 114 * @param num Indicates the PWM device number. 115 * 116 * @return Returns the PWM device handle if the operation is successful; returns <b>NULL</b> otherwise. 117 * 118 * @since 1.0 119 */ 120 DevHandle PwmOpen(uint32_t num); 121 122 /** 123 * @brief Releases the PWM device handle. 124 * 125 * @param handle Indicates the PWM device handle obtained via {@link PwmOpen}. 126 * 127 * @since 1.0 128 */ 129 void PwmClose(DevHandle handle); 130 131 /** 132 * @brief Sets the PWM period. 133 * 134 * @param handle Indicates the PWM device handle obtained via {@link PwmOpen}. 135 * @param period Indicates the PWM device period to set, in nanoseconds. 136 * 137 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 138 * 139 * @since 1.0 140 */ 141 int32_t PwmSetPeriod(DevHandle handle, uint32_t period); 142 143 /** 144 * @brief Sets the PWM duty cycle. 145 * 146 * @param handle Indicates the PWM device handle obtained via {@link PwmOpen}. 147 * @param duty Indicates the duty cycle to set, in nanoseconds. 148 * 149 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 150 * 151 * @since 1.0 152 */ 153 int32_t PwmSetDuty(DevHandle handle, uint32_t duty); 154 155 /** 156 * @brief Sets the PWM polarity. 157 * 158 * @param handle Indicates the PWM device handle obtained via {@link PwmOpen}. 159 * @param polarity Indicates the polarity to set, which can be {@link PWM_NORMAL_POLARITY} 160 * or {@link PWM_INVERTED_POLARITY}. 161 * 162 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 163 * 164 * @since 1.0 165 */ 166 int32_t PwmSetPolarity(DevHandle handle, uint8_t polarity); 167 168 /** 169 * @brief Enables the PWM device. 170 * 171 * @param handle Indicates the PWM device handle obtained via {@link PwmOpen}. 172 * 173 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 174 * 175 * @since 1.0 176 */ 177 int32_t PwmEnable(DevHandle handle); 178 179 /** 180 * @brief Disables the PWM device. 181 * 182 * @param handle Indicates the PWM device handle obtained via {@link PwmOpen}. 183 * 184 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 185 * 186 * @since 1.0 187 */ 188 int32_t PwmDisable(DevHandle handle); 189 190 /** 191 * @brief Sets the PWM device configuration parameters. 192 * 193 * @param handle Indicates the PWM device handle obtained via {@link PwmOpen}. 194 * @param config Indicates the pointer to the {@link PwmConfig} structure that 195 * contains PWM device configuration parameters. 196 * 197 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 198 * 199 * @since 1.0 200 */ 201 int32_t PwmSetConfig(DevHandle handle, struct PwmConfig *config); 202 203 /** 204 * @brief Obtains the PWM device configuration parameters. 205 * 206 * @param handle Indicates the PWM device handle obtained via {@link PwmOpen}. 207 * @param config Indicates the pointer to the {@link PwmConfig} structure that contains 208 * PWM device configuration parameters. 209 * 210 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 211 * 212 * @since 1.0 213 */ 214 int32_t PwmGetConfig(DevHandle handle, struct PwmConfig *config); 215 216 #ifdef __cplusplus 217 #if __cplusplus 218 } 219 #endif 220 #endif /* __cplusplus */ 221 222 #endif /* PWM_IF_H */ 223 /** @} */ 224