1 /* 2 * Copyright (c) 2015 - 2018, Nordic Semiconductor ASA 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions are met: 7 * 8 * 1. Redistributions of source code must retain the above copyright notice, this 9 * list of conditions and the following disclaimer. 10 * 11 * 2. Redistributions in binary form must reproduce the above copyright 12 * notice, this list of conditions and the following disclaimer in the 13 * documentation and/or other materials provided with the distribution. 14 * 15 * 3. Neither the name of the copyright holder nor the names of its 16 * contributors may be used to endorse or promote products derived from this 17 * software without specific prior written permission. 18 * 19 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 20 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 23 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 24 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 25 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 26 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 27 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 28 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 29 * POSSIBILITY OF SUCH DAMAGE. 30 */ 31 32 #ifndef NRFX_PWM_H__ 33 #define NRFX_PWM_H__ 34 35 #include <nrfx.h> 36 #include <hal/nrf_pwm.h> 37 38 #ifdef __cplusplus 39 extern "C" { 40 #endif 41 42 /** 43 * @defgroup nrfx_pwm PWM driver 44 * @{ 45 * @ingroup nrf_pwm 46 * @brief Pulse Width Modulation (PWM) peripheral driver. 47 */ 48 49 /** 50 * @brief PWM driver instance data structure. 51 */ 52 typedef struct 53 { 54 NRF_PWM_Type * p_registers; ///< Pointer to the structure with PWM peripheral instance registers. 55 uint8_t drv_inst_idx; ///< Driver instance index. 56 } nrfx_pwm_t; 57 58 /** 59 * @brief Macro for creating a PWM driver instance. 60 */ 61 #define NRFX_PWM_INSTANCE(id) \ 62 { \ 63 .p_registers = NRFX_CONCAT_2(NRF_PWM, id), \ 64 .drv_inst_idx = NRFX_CONCAT_3(NRFX_PWM, id, _INST_IDX), \ 65 } 66 67 enum { 68 #if NRFX_CHECK(NRFX_PWM0_ENABLED) 69 NRFX_PWM0_INST_IDX, 70 #endif 71 #if NRFX_CHECK(NRFX_PWM1_ENABLED) 72 NRFX_PWM1_INST_IDX, 73 #endif 74 #if NRFX_CHECK(NRFX_PWM2_ENABLED) 75 NRFX_PWM2_INST_IDX, 76 #endif 77 #if NRFX_CHECK(NRFX_PWM3_ENABLED) 78 NRFX_PWM3_INST_IDX, 79 #endif 80 NRFX_PWM_ENABLED_COUNT 81 }; 82 83 /** 84 * @brief This value can be provided instead of a pin number for any channel 85 * to specify that its output is not used and therefore does not need 86 * to be connected to a pin. 87 */ 88 #define NRFX_PWM_PIN_NOT_USED 0xFF 89 90 /** 91 * @brief This value can be added to a pin number to inverse its polarity 92 * (set idle state = 1). 93 */ 94 #define NRFX_PWM_PIN_INVERTED 0x80 95 96 /** 97 * @brief PWM driver configuration structure. 98 */ 99 typedef struct 100 { 101 uint8_t output_pins[NRF_PWM_CHANNEL_COUNT]; ///< Pin numbers for individual output channels (optional). 102 /**< Use @ref NRFX_PWM_PIN_NOT_USED 103 * if a given output channel is not needed. */ 104 uint8_t irq_priority; ///< Interrupt priority. 105 nrf_pwm_clk_t base_clock; ///< Base clock frequency. 106 nrf_pwm_mode_t count_mode; ///< Operating mode of the pulse generator counter. 107 uint16_t top_value; ///< Value up to which the pulse generator counter counts. 108 nrf_pwm_dec_load_t load_mode; ///< Mode of loading sequence data from RAM. 109 nrf_pwm_dec_step_t step_mode; ///< Mode of advancing the active sequence. 110 } nrfx_pwm_config_t; 111 112 /** 113 * @brief PWM driver default configuration. 114 */ 115 #define NRFX_PWM_DEFAULT_CONFIG \ 116 { \ 117 .output_pins = { NRFX_PWM_DEFAULT_CONFIG_OUT0_PIN, \ 118 NRFX_PWM_DEFAULT_CONFIG_OUT1_PIN, \ 119 NRFX_PWM_DEFAULT_CONFIG_OUT2_PIN, \ 120 NRFX_PWM_DEFAULT_CONFIG_OUT3_PIN }, \ 121 .irq_priority = NRFX_PWM_DEFAULT_CONFIG_IRQ_PRIORITY, \ 122 .base_clock = (nrf_pwm_clk_t)NRFX_PWM_DEFAULT_CONFIG_BASE_CLOCK, \ 123 .count_mode = (nrf_pwm_mode_t)NRFX_PWM_DEFAULT_CONFIG_COUNT_MODE, \ 124 .top_value = NRFX_PWM_DEFAULT_CONFIG_TOP_VALUE, \ 125 .load_mode = (nrf_pwm_dec_load_t)NRFX_PWM_DEFAULT_CONFIG_LOAD_MODE, \ 126 .step_mode = (nrf_pwm_dec_step_t)NRFX_PWM_DEFAULT_CONFIG_STEP_MODE, \ 127 } 128 129 130 /** 131 * @brief PWM flags providing additional playback options. 132 */ 133 typedef enum 134 { 135 NRFX_PWM_FLAG_STOP = 0x01, /**< When the requested playback is finished, 136 the peripheral should be stopped. 137 @note The STOP task is triggered when 138 the last value of the final sequence is 139 loaded from RAM, and the peripheral stops 140 at the end of the current PWM period. 141 For sequences with configured repeating 142 of duty cycle values, this might result in 143 less than the requested number of repeats 144 of the last value. */ 145 NRFX_PWM_FLAG_LOOP = 0x02, /**< When the requested playback is finished, 146 it should be started from the beginning. 147 This flag is ignored if used together 148 with @ref NRFX_PWM_FLAG_STOP. 149 @note The playback restart is done via a 150 shortcut configured in the PWM peripheral. 151 This shortcut triggers the proper starting 152 task when the final value of previous 153 playback is read from RAM and applied to 154 the pulse generator counter. 155 When this mechanism is used together with 156 the @ref NRF_PWM_STEP_TRIGGERED mode, 157 the playback restart will occur right 158 after switching to the final value (this 159 final value will be played only once). */ 160 NRFX_PWM_FLAG_SIGNAL_END_SEQ0 = 0x04, /**< The event handler should be 161 called when the last value 162 from sequence 0 is loaded. */ 163 NRFX_PWM_FLAG_SIGNAL_END_SEQ1 = 0x08, /**< The event handler should be 164 called when the last value 165 from sequence 1 is loaded. */ 166 NRFX_PWM_FLAG_NO_EVT_FINISHED = 0x10, /**< The playback finished event 167 (enabled by default) should be 168 suppressed. */ 169 NRFX_PWM_FLAG_START_VIA_TASK = 0x80, /**< The playback should not be 170 started directly by the called 171 function. Instead, the function 172 should only prepare it and 173 return the address of the task 174 to be triggered to start the 175 playback. */ 176 } nrfx_pwm_flag_t; 177 178 179 /** 180 * @brief PWM driver event type. 181 */ 182 typedef enum 183 { 184 NRFX_PWM_EVT_FINISHED, ///< Sequence playback finished. 185 NRFX_PWM_EVT_END_SEQ0, /**< End of sequence 0 reached. Its data can be 186 safely modified now. */ 187 NRFX_PWM_EVT_END_SEQ1, /**< End of sequence 1 reached. Its data can be 188 safely modified now. */ 189 NRFX_PWM_EVT_STOPPED, ///< The PWM peripheral has been stopped. 190 } nrfx_pwm_evt_type_t; 191 192 /** 193 * @brief PWM driver event handler type. 194 */ 195 typedef void (* nrfx_pwm_handler_t)(nrfx_pwm_evt_type_t event_type); 196 197 198 /** 199 * @brief Function for initializing the PWM driver. 200 * 201 * @param[in] p_instance Pointer to the driver instance structure. 202 * @param[in] p_config Pointer to the structure with initial configuration. 203 * 204 * @param[in] handler Event handler provided by the user. If NULL is passed 205 * instead, event notifications are not done and PWM 206 * interrupts are disabled. 207 * 208 * @retval NRFX_SUCCESS If initialization was successful. 209 * @retval NRFX_ERROR_INVALID_STATE If the driver was already initialized. 210 */ 211 nrfx_err_t nrfx_pwm_init(nrfx_pwm_t const * const p_instance, 212 nrfx_pwm_config_t const * p_config, 213 nrfx_pwm_handler_t handler); 214 215 /** 216 * @brief Function for uninitializing the PWM driver. 217 * 218 * If any sequence playback is in progress, it is stopped immediately. 219 * 220 * @param[in] p_instance Pointer to the driver instance structure. 221 */ 222 void nrfx_pwm_uninit(nrfx_pwm_t const * const p_instance); 223 224 /** 225 * @brief Function for starting a single sequence playback. 226 * 227 * To take advantage of the looping mechanism in the PWM peripheral, both 228 * sequences must be used (single sequence can be played back only once by 229 * the peripheral). Therefore, the provided sequence is internally set and 230 * played back as both sequence 0 and sequence 1. Consequently, if end of 231 * sequence notifications are required, events for both sequences should be 232 * used (that means that both the @ref NRFX_PWM_FLAG_SIGNAL_END_SEQ0 flag 233 * and the @ref NRFX_PWM_FLAG_SIGNAL_END_SEQ1 flag should be specified and 234 * the @ref NRFX_PWM_EVT_END_SEQ0 event and the @ref NRFX_PWM_EVT_END_SEQ1 235 * event should be handled in the same way). 236 * 237 * Use the @ref NRFX_PWM_FLAG_START_VIA_TASK flag if you want the playback 238 * to be only prepared by this function, and you want to start it later by 239 * triggering a task (using PPI for instance). The function will then return 240 * the address of the task to be triggered. 241 * 242 * @note The array containing the duty cycle values for the specified sequence 243 * must be in RAM and cannot be allocated on stack. 244 * For detailed information, see @ref nrf_pwm_sequence_t. 245 * 246 * @param[in] p_instance Pointer to the driver instance structure. 247 * @param[in] p_sequence Sequence to be played back. 248 * @param[in] playback_count Number of playbacks to be performed (must not be 0). 249 * @param[in] flags Additional options. Pass any combination of 250 * @ref nrfx_pwm_flag_t "playback flags", or 0 251 * for default settings. 252 * 253 * @return Address of the task to be triggered to start the playback if the @ref 254 * NRFX_PWM_FLAG_START_VIA_TASK flag was used, 0 otherwise. 255 */ 256 uint32_t nrfx_pwm_simple_playback(nrfx_pwm_t const * const p_instance, 257 nrf_pwm_sequence_t const * p_sequence, 258 uint16_t playback_count, 259 uint32_t flags); 260 261 /** 262 * @brief Function for starting a two-sequence playback. 263 * 264 * Use the @ref NRFX_PWM_FLAG_START_VIA_TASK flag if you want the playback 265 * to be only prepared by this function, and you want to start it later by 266 * triggering a task (using PPI for instance). The function will then return 267 * the address of the task to be triggered. 268 * 269 * @note The array containing the duty cycle values for the specified sequence 270 * must be in RAM and cannot be allocated on stack. 271 * For detailed information, see @ref nrf_pwm_sequence_t. 272 * 273 * @param[in] p_instance Pointer to the driver instance structure. 274 * @param[in] p_sequence_0 First sequence to be played back. 275 * @param[in] p_sequence_1 Second sequence to be played back. 276 * @param[in] playback_count Number of playbacks to be performed (must not be 0). 277 * @param[in] flags Additional options. Pass any combination of 278 * @ref nrfx_pwm_flag_t "playback flags", or 0 279 * for default settings. 280 * 281 * @return Address of the task to be triggered to start the playback if the @ref 282 * NRFX_PWM_FLAG_START_VIA_TASK flag was used, 0 otherwise. 283 */ 284 uint32_t nrfx_pwm_complex_playback(nrfx_pwm_t const * const p_instance, 285 nrf_pwm_sequence_t const * p_sequence_0, 286 nrf_pwm_sequence_t const * p_sequence_1, 287 uint16_t playback_count, 288 uint32_t flags); 289 290 /** 291 * @brief Function for advancing the active sequence. 292 * 293 * This function only applies to @ref NRF_PWM_STEP_TRIGGERED mode. 294 * 295 * @param[in] p_instance Pointer to the driver instance structure. 296 */ 297 __STATIC_INLINE void nrfx_pwm_step(nrfx_pwm_t const * const p_instance); 298 299 /** 300 * @brief Function for stopping the sequence playback. 301 * 302 * The playback is stopped at the end of the current PWM period. 303 * This means that if the active sequence is configured to repeat each duty 304 * cycle value for a certain number of PWM periods, the last played value 305 * might appear on the output less times than requested. 306 * 307 * @note This function can be instructed to wait until the playback is stopped 308 * (by setting @p wait_until_stopped to true). Note that, depending on 309 * the length of the PMW period, this might take a significant amount of 310 * time. Alternatively, the @ref nrfx_pwm_is_stopped function can be 311 * used to poll the status, or the @ref NRFX_PWM_EVT_STOPPED event can 312 * be used to get the notification when the playback is stopped, provided 313 * the event handler is defined. 314 * 315 * @param[in] p_instance Pointer to the driver instance structure. 316 * @param[in] wait_until_stopped If true, the function will not return until 317 * the playback is stopped. 318 * 319 * @retval true If the PWM peripheral is stopped. 320 * @retval false If the PWM peripheral is not stopped. 321 */ 322 bool nrfx_pwm_stop(nrfx_pwm_t const * const p_instance, 323 bool wait_until_stopped); 324 325 /** 326 * @brief Function for checking the status of the PWM peripheral. 327 * 328 * @param[in] p_instance Pointer to the driver instance structure. 329 * 330 * @retval true If the PWM peripheral is stopped. 331 * @retval false If the PWM peripheral is not stopped. 332 */ 333 bool nrfx_pwm_is_stopped(nrfx_pwm_t const * const p_instance); 334 335 /** 336 * @brief Function for updating the sequence data during playback. 337 * 338 * @param[in] p_instance Pointer to the driver instance structure. 339 * @param[in] seq_id Identifier of the sequence (0 or 1). 340 * @param[in] p_sequence Pointer to the new sequence definition. 341 */ 342 __STATIC_INLINE void nrfx_pwm_sequence_update( 343 nrfx_pwm_t const * const p_instance, 344 uint8_t seq_id, 345 nrf_pwm_sequence_t const * p_sequence); 346 347 /** 348 * @brief Function for updating the pointer to the duty cycle values 349 * in the specified sequence during playback. 350 * 351 * @param[in] p_instance Pointer to the driver instance structure. 352 * @param[in] seq_id Identifier of the sequence (0 or 1). 353 * @param[in] values New pointer to the duty cycle values. 354 */ 355 __STATIC_INLINE void nrfx_pwm_sequence_values_update(nrfx_pwm_t const * const p_instance, 356 uint8_t seq_id, 357 nrf_pwm_values_t values); 358 359 /** 360 * @brief Function for updating the number of duty cycle values 361 * in the specified sequence during playback. 362 * 363 * @param[in] p_instance Pointer to the driver instance structure. 364 * @param[in] seq_id Identifier of the sequence (0 or 1). 365 * @param[in] length New number of the duty cycle values. 366 */ 367 __STATIC_INLINE void nrfx_pwm_sequence_length_update(nrfx_pwm_t const * const p_instance, 368 uint8_t seq_id, 369 uint16_t length); 370 371 /** 372 * @brief Function for updating the number of repeats for duty cycle values 373 * in specified sequence during playback. 374 * 375 * @param[in] p_instance Pointer to the driver instance structure. 376 * @param[in] seq_id Identifier of the sequence (0 or 1). 377 * @param[in] repeats New number of repeats. 378 */ 379 __STATIC_INLINE void nrfx_pwm_sequence_repeats_update(nrfx_pwm_t const * const p_instance, 380 uint8_t seq_id, 381 uint32_t repeats); 382 383 /** 384 * @brief Function for updating the additional delay after the specified 385 * sequence during playback. 386 * 387 * @param[in] p_instance Pointer to the driver instance structure. 388 * @param[in] seq_id Identifier of the sequence (0 or 1). 389 * @param[in] end_delay New end delay value (in PWM periods). 390 */ 391 __STATIC_INLINE void nrfx_pwm_sequence_end_delay_update(nrfx_pwm_t const * const p_instance, 392 uint8_t seq_id, 393 uint32_t end_delay); 394 395 /** 396 * @brief Function for returning the address of a specified PWM task that can 397 * be used in PPI module. 398 * 399 * @param[in] p_instance Pointer to the driver instance structure. 400 * @param[in] task Requested task. 401 * 402 * @return Task address. 403 */ 404 __STATIC_INLINE uint32_t nrfx_pwm_task_address_get(nrfx_pwm_t const * const p_instance, 405 nrf_pwm_task_t task); 406 407 /**@brief Function for returning the address of a specified PWM event that can 408 * be used in PPI module. 409 * 410 * @param[in] p_instance Pointer to the driver instance structure. 411 * @param[in] event Requested event. 412 * 413 * @return Event address. 414 */ 415 __STATIC_INLINE uint32_t nrfx_pwm_event_address_get(nrfx_pwm_t const * const p_instance, 416 nrf_pwm_event_t event); 417 418 419 #ifndef SUPPRESS_INLINE_IMPLEMENTATION 420 421 __STATIC_INLINE void nrfx_pwm_step(nrfx_pwm_t const * const p_instance) 422 { 423 nrf_pwm_task_trigger(p_instance->p_registers, NRF_PWM_TASK_NEXTSTEP); 424 } 425 426 __STATIC_INLINE void nrfx_pwm_sequence_update(nrfx_pwm_t const * const p_instance, 427 uint8_t seq_id, 428 nrf_pwm_sequence_t const * p_sequence) 429 { 430 nrf_pwm_sequence_set(p_instance->p_registers, seq_id, p_sequence); 431 } 432 433 __STATIC_INLINE void nrfx_pwm_sequence_values_update(nrfx_pwm_t const * const p_instance, 434 uint8_t seq_id, 435 nrf_pwm_values_t values) 436 { 437 nrf_pwm_seq_ptr_set(p_instance->p_registers, seq_id, values.p_raw); 438 } 439 440 __STATIC_INLINE void nrfx_pwm_sequence_length_update(nrfx_pwm_t const * const p_instance, 441 uint8_t seq_id, 442 uint16_t length) 443 { 444 nrf_pwm_seq_cnt_set(p_instance->p_registers, seq_id, length); 445 } 446 447 __STATIC_INLINE void nrfx_pwm_sequence_repeats_update(nrfx_pwm_t const * const p_instance, 448 uint8_t seq_id, 449 uint32_t repeats) 450 { 451 nrf_pwm_seq_refresh_set(p_instance->p_registers, seq_id, repeats); 452 } 453 454 __STATIC_INLINE void nrfx_pwm_sequence_end_delay_update(nrfx_pwm_t const * const p_instance, 455 uint8_t seq_id, 456 uint32_t end_delay) 457 { 458 nrf_pwm_seq_end_delay_set(p_instance->p_registers, seq_id, end_delay); 459 } 460 461 __STATIC_INLINE uint32_t nrfx_pwm_task_address_get(nrfx_pwm_t const * const p_instance, 462 nrf_pwm_task_t task) 463 { 464 return nrf_pwm_task_address_get(p_instance->p_registers, task); 465 } 466 467 __STATIC_INLINE uint32_t nrfx_pwm_event_address_get(nrfx_pwm_t const * const p_instance, 468 nrf_pwm_event_t event) 469 { 470 return nrf_pwm_event_address_get(p_instance->p_registers, event); 471 } 472 473 #endif // SUPPRESS_INLINE_IMPLEMENTATION 474 475 476 void nrfx_pwm_0_irq_handler(void); 477 void nrfx_pwm_1_irq_handler(void); 478 void nrfx_pwm_2_irq_handler(void); 479 void nrfx_pwm_3_irq_handler(void); 480 481 482 /** @} */ 483 484 #ifdef __cplusplus 485 } 486 #endif 487 488 #endif // NRFX_PWM_H__ 489