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