1 /*
2 * Copyright (c) 2015 - 2020, 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 /** @brief PWM driver instance data structure. */
50 typedef struct
51 {
52 NRF_PWM_Type * p_registers; ///< Pointer to the structure with PWM peripheral instance registers.
53 uint8_t drv_inst_idx; ///< Index of the driver instance. For internal use only.
54 } nrfx_pwm_t;
55
56 /** @brief Macro for creating a PWM driver instance. */
57 #define NRFX_PWM_INSTANCE(id) \
58 { \
59 .p_registers = NRFX_CONCAT_2(NRF_PWM, id), \
60 .drv_inst_idx = NRFX_CONCAT_3(NRFX_PWM, id, _INST_IDX), \
61 }
62
63 #ifndef __NRFX_DOXYGEN__
64 enum {
65 #if NRFX_CHECK(NRFX_PWM0_ENABLED)
66 NRFX_PWM0_INST_IDX,
67 #endif
68 #if NRFX_CHECK(NRFX_PWM1_ENABLED)
69 NRFX_PWM1_INST_IDX,
70 #endif
71 #if NRFX_CHECK(NRFX_PWM2_ENABLED)
72 NRFX_PWM2_INST_IDX,
73 #endif
74 #if NRFX_CHECK(NRFX_PWM3_ENABLED)
75 NRFX_PWM3_INST_IDX,
76 #endif
77 NRFX_PWM_ENABLED_COUNT
78 };
79 #endif
80
81 /**
82 * @brief This value can be provided instead of a pin number for any channel
83 * to specify that its output is not used and therefore does not need
84 * to be connected to a pin.
85 */
86 #define NRFX_PWM_PIN_NOT_USED 0xFF
87
88 /** @brief This value can be added to a pin number to invert its polarity (set idle state = 1). */
89 #define NRFX_PWM_PIN_INVERTED 0x80
90
91 /** @brief PWM driver configuration structure. */
92 typedef struct
93 {
94 uint8_t output_pins[NRF_PWM_CHANNEL_COUNT]; ///< Pin numbers for individual output channels (optional).
95 /**< Use @ref NRFX_PWM_PIN_NOT_USED
96 * if a given output channel is not needed. */
97 uint8_t irq_priority; ///< Interrupt priority.
98 nrf_pwm_clk_t base_clock; ///< Base clock frequency.
99 nrf_pwm_mode_t count_mode; ///< Operating mode of the pulse generator counter.
100 uint16_t top_value; ///< Value up to which the pulse generator counter counts.
101 nrf_pwm_dec_load_t load_mode; ///< Mode of loading sequence data from RAM.
102 nrf_pwm_dec_step_t step_mode; ///< Mode of advancing the active sequence.
103 bool skip_gpio_cfg; ///< Skip the GPIO configuration
104 /**< When this flag is set, the user is responsible for
105 * providing the proper configuration of the output pins,
106 * as the driver does not touch it at all. */
107 } nrfx_pwm_config_t;
108
109 /**
110 * @brief PWM driver default configuration.
111 *
112 * This configuration sets up PWM with the following options:
113 * - clock frequency: 1 MHz
114 * - count up
115 * - top value: 1000 clock ticks
116 * - load mode: common
117 * - step mode: auto
118 *
119 * @param[in] _out_0 PWM output 0 pin.
120 * @param[in] _out_1 PWM output 1 pin.
121 * @param[in] _out_2 PWM output 2 pin.
122 * @param[in] _out_3 PWM output 3 pin.
123 */
124 #define NRFX_PWM_DEFAULT_CONFIG(_out_0, _out_1, _out_2, _out_3) \
125 { \
126 .output_pins = { _out_0, \
127 _out_1, \
128 _out_2, \
129 _out_3 \
130 }, \
131 .irq_priority = NRFX_PWM_DEFAULT_CONFIG_IRQ_PRIORITY, \
132 .base_clock = NRF_PWM_CLK_1MHz, \
133 .count_mode = NRF_PWM_MODE_UP, \
134 .top_value = 1000, \
135 .load_mode = NRF_PWM_LOAD_COMMON, \
136 .step_mode = NRF_PWM_STEP_AUTO, \
137 .skip_gpio_cfg = false \
138 }
139
140 /** @brief PWM flags providing additional playback options. */
141 typedef enum
142 {
143 NRFX_PWM_FLAG_STOP = 0x01, /**< When the requested playback is finished,
144 the peripheral will be stopped.
145 @note The STOP task is triggered when
146 the last value of the final sequence is
147 loaded from RAM, and the peripheral stops
148 at the end of the current PWM period.
149 For sequences with configured repeating
150 of duty cycle values, this might result in
151 less than the requested number of repeats
152 of the last value. */
153 NRFX_PWM_FLAG_LOOP = 0x02, /**< When the requested playback is finished,
154 it will be started from the beginning.
155 This flag is ignored if used together
156 with @ref NRFX_PWM_FLAG_STOP.
157 @note The playback restart is done via a
158 shortcut configured in the PWM peripheral.
159 This shortcut triggers the proper starting
160 task when the final value of previous
161 playback is read from RAM and applied to
162 the pulse generator counter.
163 When this mechanism is used together with
164 the @ref NRF_PWM_STEP_TRIGGERED mode,
165 the playback restart will occur right
166 after switching to the final value (this
167 final value will be played only once). */
168 NRFX_PWM_FLAG_SIGNAL_END_SEQ0 = 0x04, /**< The event handler is to be
169 called when the last value
170 from sequence 0 is loaded. */
171 NRFX_PWM_FLAG_SIGNAL_END_SEQ1 = 0x08, /**< The event handler is to be
172 called when the last value
173 from sequence 1 is loaded. */
174 NRFX_PWM_FLAG_NO_EVT_FINISHED = 0x10, /**< The playback finished event
175 (enabled by default) is to be
176 suppressed. */
177 NRFX_PWM_FLAG_START_VIA_TASK = 0x80, /**< The playback must not be
178 started directly by the called
179 function. Instead, the function
180 must only prepare it and
181 return the address of the task
182 to be triggered to start the
183 playback. */
184 } nrfx_pwm_flag_t;
185
186 /** @brief PWM driver event type. */
187 typedef enum
188 {
189 NRFX_PWM_EVT_FINISHED, ///< Sequence playback finished.
190 NRFX_PWM_EVT_END_SEQ0, /**< End of sequence 0 reached. Its data can be
191 safely modified now. */
192 NRFX_PWM_EVT_END_SEQ1, /**< End of sequence 1 reached. Its data can be
193 safely modified now. */
194 NRFX_PWM_EVT_STOPPED, ///< The PWM peripheral has been stopped.
195 } nrfx_pwm_evt_type_t;
196
197 /** @brief PWM driver event handler type. */
198 typedef void (* nrfx_pwm_handler_t)(nrfx_pwm_evt_type_t event_type, void * p_context);
199
200 /**
201 * @brief Function for initializing the PWM driver.
202 *
203 * @param[in] p_instance Pointer to the driver instance structure.
204 * @param[in] p_config Pointer to the structure with the initial configuration.
205 * @param[in] handler Event handler provided by the user. If NULL is passed
206 * instead, event notifications are not done and PWM
207 * interrupts are disabled.
208 * @param[in] p_context Context passed to the event handler.
209 *
210 * @retval NRFX_SUCCESS Initialization was successful.
211 * @retval NRFX_ERROR_INVALID_STATE The driver was already initialized.
212 */
213 nrfx_err_t nrfx_pwm_init(nrfx_pwm_t const * p_instance,
214 nrfx_pwm_config_t const * p_config,
215 nrfx_pwm_handler_t handler,
216 void * p_context);
217
218 /**
219 * @brief Function for uninitializing the PWM driver.
220 *
221 * If any sequence playback is in progress, it is stopped immediately.
222 *
223 * @param[in] p_instance Pointer to the driver instance structure.
224 */
225 void nrfx_pwm_uninit(nrfx_pwm_t const * p_instance);
226
227 /**
228 * @brief Function for starting a single sequence playback.
229 *
230 * To take advantage of the looping mechanism in the PWM peripheral, both
231 * sequences must be used (single sequence can be played back only once by
232 * the peripheral). Therefore, the provided sequence is internally set and
233 * played back as both sequence 0 and sequence 1. Consequently, if the end of
234 * sequence notifications are required, events for both sequences must be
235 * used (that is, both the @ref NRFX_PWM_FLAG_SIGNAL_END_SEQ0 flag
236 * and the @ref NRFX_PWM_FLAG_SIGNAL_END_SEQ1 flag must be specified, and
237 * the @ref NRFX_PWM_EVT_END_SEQ0 event and the @ref NRFX_PWM_EVT_END_SEQ1
238 * event must be handled in the same way).
239 *
240 * Use the @ref NRFX_PWM_FLAG_START_VIA_TASK flag if you want the playback
241 * to be only prepared by this function, and you want to start it later by
242 * triggering a task (for example, by using PPI). The function will then return
243 * the address of the task to be triggered.
244 *
245 * @note The array containing the duty cycle values for the specified sequence
246 * must be in RAM and cannot be allocated on the stack.
247 * For detailed information, see @ref nrf_pwm_sequence_t.
248 *
249 * @param[in] p_instance Pointer to the driver instance structure.
250 * @param[in] p_sequence Sequence to be played back.
251 * @param[in] playback_count Number of playbacks to be performed (must not be 0).
252 * @param[in] flags Additional options. Pass any combination of
253 * @ref nrfx_pwm_flag_t "playback flags", or 0
254 * for default settings.
255 *
256 * @return Address of the task to be triggered to start the playback if the @ref
257 * NRFX_PWM_FLAG_START_VIA_TASK flag was used, 0 otherwise.
258 */
259 uint32_t nrfx_pwm_simple_playback(nrfx_pwm_t const * p_instance,
260 nrf_pwm_sequence_t const * p_sequence,
261 uint16_t playback_count,
262 uint32_t flags);
263
264 /**
265 * @brief Function for starting a two-sequence playback.
266 *
267 * Use the @ref NRFX_PWM_FLAG_START_VIA_TASK flag if you want the playback
268 * to be only prepared by this function, and you want to start it later by
269 * triggering a task (using PPI for instance). The function will then return
270 * the address of the task to be triggered.
271 *
272 * @note The array containing the duty cycle values for the specified sequence
273 * must be in RAM and cannot be allocated on the stack.
274 * For detailed information, see @ref nrf_pwm_sequence_t.
275 *
276 * @param[in] p_instance Pointer to the driver instance structure.
277 * @param[in] p_sequence_0 First sequence to be played back.
278 * @param[in] p_sequence_1 Second sequence to be played back.
279 * @param[in] playback_count Number of playbacks to be performed (must not be 0).
280 * @param[in] flags Additional options. Pass any combination of
281 * @ref nrfx_pwm_flag_t "playback flags", or 0
282 * for default settings.
283 *
284 * @return Address of the task to be triggered to start the playback if the @ref
285 * NRFX_PWM_FLAG_START_VIA_TASK flag was used, 0 otherwise.
286 */
287 uint32_t nrfx_pwm_complex_playback(nrfx_pwm_t const * p_instance,
288 nrf_pwm_sequence_t const * p_sequence_0,
289 nrf_pwm_sequence_t const * p_sequence_1,
290 uint16_t playback_count,
291 uint32_t flags);
292
293 /**
294 * @brief Function for advancing the active sequence.
295 *
296 * This function only applies to @ref NRF_PWM_STEP_TRIGGERED mode.
297 *
298 * @param[in] p_instance Pointer to the driver instance structure.
299 */
300 NRFX_STATIC_INLINE void nrfx_pwm_step(nrfx_pwm_t const * p_instance);
301
302 /**
303 * @brief Function for stopping the sequence playback.
304 *
305 * The playback is stopped at the end of the current PWM period.
306 * This means that if the active sequence is configured to repeat each duty
307 * cycle value for a certain number of PWM periods, the last played value
308 * might appear on the output less times than requested.
309 *
310 * @note This function can be instructed to wait until the playback is stopped
311 * (by setting @p wait_until_stopped to true). Depending on
312 * the length of the PMW period, this might take a significant amount of
313 * time. Alternatively, the @ref nrfx_pwm_is_stopped function can be
314 * used to poll the status, or the @ref NRFX_PWM_EVT_STOPPED event can
315 * be used to get the notification when the playback is stopped, provided
316 * the event handler is defined.
317 *
318 * @param[in] p_instance Pointer to the driver instance structure.
319 * @param[in] wait_until_stopped If true, the function will not return until
320 * the playback is stopped.
321 *
322 * @retval true The PWM peripheral is stopped.
323 * @retval false The PWM peripheral is not stopped.
324 */
325 bool nrfx_pwm_stop(nrfx_pwm_t const * p_instance, bool wait_until_stopped);
326
327 /**
328 * @brief Function for checking the status of the PWM peripheral.
329 *
330 * @param[in] p_instance Pointer to the driver instance structure.
331 *
332 * @retval true The PWM peripheral is stopped.
333 * @retval false The PWM peripheral is not stopped.
334 */
335 bool nrfx_pwm_is_stopped(nrfx_pwm_t const * p_instance);
336
337 /**
338 * @brief Function for updating the sequence data during playback.
339 *
340 * @param[in] p_instance Pointer to the driver instance structure.
341 * @param[in] seq_id Identifier of the sequence (0 or 1).
342 * @param[in] p_sequence Pointer to the new sequence definition.
343 */
344 NRFX_STATIC_INLINE void nrfx_pwm_sequence_update(nrfx_pwm_t const * p_instance,
345 uint8_t seq_id,
346 nrf_pwm_sequence_t const * p_sequence);
347
348 /**
349 * @brief Function for updating the pointer to the duty cycle values
350 * in the specified sequence during playback.
351 *
352 * @param[in] p_instance Pointer to the driver instance structure.
353 * @param[in] seq_id Identifier of the sequence (0 or 1).
354 * @param[in] values New pointer to the duty cycle values.
355 */
356 NRFX_STATIC_INLINE void nrfx_pwm_sequence_values_update(nrfx_pwm_t const * p_instance,
357 uint8_t seq_id,
358 nrf_pwm_values_t values);
359
360 /**
361 * @brief Function for updating the number of duty cycle values
362 * in the specified sequence during playback.
363 *
364 * @param[in] p_instance Pointer to the driver instance structure.
365 * @param[in] seq_id Identifier of the sequence (0 or 1).
366 * @param[in] length New number of the duty cycle values.
367 */
368 NRFX_STATIC_INLINE void nrfx_pwm_sequence_length_update(nrfx_pwm_t const * p_instance,
369 uint8_t seq_id,
370 uint16_t length);
371
372 /**
373 * @brief Function for updating the number of repeats for duty cycle values
374 * in the specified sequence during playback.
375 *
376 * @param[in] p_instance Pointer to the driver instance structure.
377 * @param[in] seq_id Identifier of the sequence (0 or 1).
378 * @param[in] repeats New number of repeats.
379 */
380 NRFX_STATIC_INLINE void nrfx_pwm_sequence_repeats_update(nrfx_pwm_t const * p_instance,
381 uint8_t seq_id,
382 uint32_t repeats);
383
384 /**
385 * @brief Function for updating the additional delay after the specified
386 * sequence during playback.
387 *
388 * @param[in] p_instance Pointer to the driver instance structure.
389 * @param[in] seq_id Identifier of the sequence (0 or 1).
390 * @param[in] end_delay New end delay value (in PWM periods).
391 */
392 NRFX_STATIC_INLINE void nrfx_pwm_sequence_end_delay_update(nrfx_pwm_t const * p_instance,
393 uint8_t seq_id,
394 uint32_t end_delay);
395
396 /**
397 * @brief Function for returning the address of a specified PWM task that can
398 * be used in PPI module.
399 *
400 * @param[in] p_instance Pointer to the driver instance structure.
401 * @param[in] task Requested task.
402 *
403 * @return Task address.
404 */
405 NRFX_STATIC_INLINE uint32_t nrfx_pwm_task_address_get(nrfx_pwm_t const * p_instance,
406 nrf_pwm_task_t task);
407
408 /**
409 * @brief Function for returning the address of a specified PWM event that can
410 * be used in PPI module.
411 *
412 * @param[in] p_instance Pointer to the driver instance structure.
413 * @param[in] event Requested event.
414 *
415 * @return Event address.
416 */
417 NRFX_STATIC_INLINE uint32_t nrfx_pwm_event_address_get(nrfx_pwm_t const * p_instance,
418 nrf_pwm_event_t event);
419
420 #ifndef NRFX_DECLARE_ONLY
nrfx_pwm_step(nrfx_pwm_t const * p_instance)421 NRFX_STATIC_INLINE void nrfx_pwm_step(nrfx_pwm_t const * p_instance)
422 {
423 nrf_pwm_task_trigger(p_instance->p_registers, NRF_PWM_TASK_NEXTSTEP);
424 }
425
nrfx_pwm_sequence_update(nrfx_pwm_t const * p_instance,uint8_t seq_id,nrf_pwm_sequence_t const * p_sequence)426 NRFX_STATIC_INLINE void nrfx_pwm_sequence_update(nrfx_pwm_t 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
nrfx_pwm_sequence_values_update(nrfx_pwm_t const * p_instance,uint8_t seq_id,nrf_pwm_values_t values)433 NRFX_STATIC_INLINE void nrfx_pwm_sequence_values_update(nrfx_pwm_t 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
nrfx_pwm_sequence_length_update(nrfx_pwm_t const * p_instance,uint8_t seq_id,uint16_t length)440 NRFX_STATIC_INLINE void nrfx_pwm_sequence_length_update(nrfx_pwm_t 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
nrfx_pwm_sequence_repeats_update(nrfx_pwm_t const * p_instance,uint8_t seq_id,uint32_t repeats)447 NRFX_STATIC_INLINE void nrfx_pwm_sequence_repeats_update(nrfx_pwm_t 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
nrfx_pwm_sequence_end_delay_update(nrfx_pwm_t const * p_instance,uint8_t seq_id,uint32_t end_delay)454 NRFX_STATIC_INLINE void nrfx_pwm_sequence_end_delay_update(nrfx_pwm_t 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
nrfx_pwm_task_address_get(nrfx_pwm_t const * p_instance,nrf_pwm_task_t task)461 NRFX_STATIC_INLINE uint32_t nrfx_pwm_task_address_get(nrfx_pwm_t const * p_instance,
462 nrf_pwm_task_t task)
463 {
464 return nrf_pwm_task_address_get(p_instance->p_registers, task);
465 }
466
nrfx_pwm_event_address_get(nrfx_pwm_t const * p_instance,nrf_pwm_event_t event)467 NRFX_STATIC_INLINE uint32_t nrfx_pwm_event_address_get(nrfx_pwm_t const * p_instance,
468 nrf_pwm_event_t event)
469 {
470 return nrf_pwm_event_address_get(p_instance->p_registers, event);
471 }
472 #endif // NRFX_DECLARE_ONLY
473
474 /** @} */
475
476
477 void nrfx_pwm_0_irq_handler(void);
478 void nrfx_pwm_1_irq_handler(void);
479 void nrfx_pwm_2_irq_handler(void);
480 void nrfx_pwm_3_irq_handler(void);
481
482
483 #ifdef __cplusplus
484 }
485 #endif
486
487 #endif // NRFX_PWM_H__
488