Intel® Quark™ Microcontroller Software Interface  1.4.0
Intel® Quark™ Microcontroller BSP
qm_pwm.h
1 /*
2  * {% copyright %}
3  */
4 
5 #ifndef __QM_PWM_H__
6 #define __QM_PWM_H__
7 
8 #include "qm_common.h"
9 #include "qm_soc_regs.h"
10 
11 /**
12  * Pulse width modulation and Timer driver.
13  *
14  * @defgroup groupPWM PWM / Timer
15  * @{
16  */
17 
18 /**
19  * QM PWM mode type.
20  */
21 typedef enum {
22  /**< Timer: Free running mode. */
23  QM_PWM_MODE_TIMER_FREE_RUNNING = QM_PWM_MODE_TIMER_FREE_RUNNING_VALUE,
24  /**< Timer: Counter mode. */
25  QM_PWM_MODE_TIMER_COUNT = QM_PWM_MODE_TIMER_COUNT_VALUE,
26  /**< PWM mode. */
27  QM_PWM_MODE_PWM = QM_PWM_MODE_PWM_VALUE
29 
30 /**
31  * QM PWM / Timer configuration type.
32  */
33 typedef struct {
34  /**
35  * Number of cycles the PWM output is driven low.
36  * In timer mode, this is the timer load count. Must be > 0.
37  */
38  uint32_t lo_count;
39  /**
40  * Number of cycles the PWM output is driven high.
41  * Not applicable in timer mode. Must be > 0.
42  */
43  uint32_t hi_count;
44  bool mask_interrupt; /**< Mask interrupt. */
45  qm_pwm_mode_t mode; /**< Pwm mode. */
46 
47  /**
48  * User callback.
49  *
50  * @param[in] data The callback user data.
51  * @param[in] int_status The timer status.
52  */
53  void (*callback)(void *data, uint32_t int_status);
54  void *callback_data; /**< Callback user data. */
56 
57 /**
58  * Change the configuration of a PWM channel.
59  *
60  * This includes low period load value, high period load value, interrupt
61  * enable/disable. If interrupts are enabled, registers an ISR with the given
62  * user callback function. When operating in PWM mode, 0% and 100% duty cycle
63  * is not available on Quark SE or Quark D2000. When setting the mode to PWM
64  * mode, hi_count must be > 0. In timer mode, the value of high count is
65  * ignored.
66  *
67  * @brief Set PWM channel configuration.
68  * @param[in] pwm Which PWM module to configure.
69  * @param[in] id PWM channel id to configure.
70  * @param[in] cfg New configuration for PWM. This must not be NULL.
71  *
72  * @return Standard errno return type for QMSI.
73  * @retval 0 on success.
74  * @retval Negative @ref errno for possible error codes.
75  */
76 int qm_pwm_set_config(const qm_pwm_t pwm, const qm_pwm_id_t id,
77  const qm_pwm_config_t *const cfg);
78 
79 /**
80  * Set the next period values of a PWM channel.
81  *
82  * This includes low period count and high period count. When operating in PWM
83  * mode, 0% and 100% duty cycle is not available on Quark SE or Quark D2000.
84  * When operating in PWM mode, hi_count must be > 0. In timer mode, the value of
85  * high count is ignored.
86  *
87  * @brief Set PWM period counts.
88  * @param[in] pwm Which PWM module to set the counts of.
89  * @param[in] id PWM channel id to set.
90  * @param[in] lo_count Num of cycles the output is driven low.
91  * @param[in] hi_count Num of cycles the output is driven high.
92  *
93  * @return Standard errno return type for QMSI.
94  * @retval 0 on success.
95  * @retval Negative @ref errno for possible error codes.
96  */
97 int qm_pwm_set(const qm_pwm_t pwm, const qm_pwm_id_t id,
98  const uint32_t lo_count, const uint32_t hi_count);
99 
100 /**
101  * Get the current period values of a PWM channel.
102  *
103  * @param[in] pwm Which PWM module to get the count of.
104  * @param[in] id PWM channel id to read the values of.
105  * @param[out] lo_count Num of cycles the output is driven low. This must not be
106  * NULL.
107  * @param[out] hi_count Num of cycles the output is driven high. This must not
108  * be NULL.
109  *
110  * @return Standard errno return type for QMSI.
111  * @retval 0 on success.
112  * @retval Negative @ref errno for possible error codes.
113  */
114 int qm_pwm_get(const qm_pwm_t pwm, const qm_pwm_id_t id,
115  uint32_t *const lo_count, uint32_t *const hi_count);
116 
117 /**
118  * Start a PWM/timer channel.
119  *
120  * @param[in] pwm Which PWM block the PWM is in.
121  * @param[in] id PWM channel id to start.
122  *
123  * @return Standard errno return type for QMSI.
124  * @retval 0 on success.
125  * @retval Negative @ref errno for possible error codes.
126  */
127 int qm_pwm_start(const qm_pwm_t pwm, const qm_pwm_id_t id);
128 
129 /**
130  * Stop a PWM/timer channel.
131  *
132  * @param[in] pwm Which PWM block the PWM is in.
133  * @param[in] id PWM channel id to stop.
134  *
135  * @return Standard errno return type for QMSI.
136  * @retval 0 on success.
137  * @retval Negative @ref errno for possible error codes.
138  */
139 int qm_pwm_stop(const qm_pwm_t pwm, const qm_pwm_id_t id);
140 
141 /**
142  * Save PWM peripheral's context.
143  *
144  * Saves the configuration of the specified PWM peripheral
145  * before entering sleep.
146  *
147  * @param[in] pwm PWM device.
148  * @param[out] ctx PWM context structure. This must not be NULL.
149  *
150  * @return Standard errno return type for QMSI.
151  * @retval 0 on success.
152  * @retval Negative @ref errno for possible error codes.
153  */
154 int qm_pwm_save_context(const qm_pwm_t pwm, qm_pwm_context_t *const ctx);
155 
156 /**
157  * Restore PWM peripheral's context.
158  *
159  * Restore the configuration of the specified PWM peripheral
160  * after exiting sleep.
161  *
162  * @param[in] pwm PWM device.
163  * @param[in] ctx PWM context structure. This must not be NULL.
164  *
165  * @return Standard errno return type for QMSI.
166  * @retval 0 on success.
167  * @retval Negative @ref errno for possible error codes.
168  */
169 int qm_pwm_restore_context(const qm_pwm_t pwm,
170  const qm_pwm_context_t *const ctx);
171 
172 /**
173  * @}
174  */
175 
176 #endif /* __QM_PWM_H__ */
uint32_t lo_count
Number of cycles the PWM output is driven low.
Definition: qm_pwm.h:38
int qm_pwm_set(const qm_pwm_t pwm, const qm_pwm_id_t id, const uint32_t lo_count, const uint32_t hi_count)
Set the next period values of a PWM channel.
Definition: qm_pwm.c:131
int qm_pwm_restore_context(const qm_pwm_t pwm, const qm_pwm_context_t *const ctx)
Restore PWM peripheral's context.
Definition: qm_pwm.c:210
void * callback_data
Callback user data.
Definition: qm_pwm.h:54
int qm_pwm_start(const qm_pwm_t pwm, const qm_pwm_id_t id)
Start a PWM/timer channel.
Definition: qm_pwm.c:83
qm_pwm_mode_t mode
Pwm mode.
Definition: qm_pwm.h:45
PWM context type.
Definition: qm_soc_regs.h:702
Timer: Free running mode.
Definition: qm_pwm.h:23
qm_pwm_mode_t
QM PWM mode type.
Definition: qm_pwm.h:21
QM PWM / Timer configuration type.
Definition: qm_pwm.h:33
int qm_pwm_set_config(const qm_pwm_t pwm, const qm_pwm_id_t id, const qm_pwm_config_t *const cfg)
Change the configuration of a PWM channel.
Definition: qm_pwm.c:106
int qm_pwm_save_context(const qm_pwm_t pwm, qm_pwm_context_t *const ctx)
Save PWM peripheral's context.
Definition: qm_pwm.c:202
bool mask_interrupt
Mask interrupt.
Definition: qm_pwm.h:44
qm_pwm_id_t
PWM ID type.
Definition: qm_soc_regs.h:386
int qm_pwm_stop(const qm_pwm_t pwm, const qm_pwm_id_t id)
Stop a PWM/timer channel.
Definition: qm_pwm.c:94
qm_pwm_t
Number of PWM / Timer controllers.
Definition: qm_soc_regs.h:383
int qm_pwm_get(const qm_pwm_t pwm, const qm_pwm_id_t id, uint32_t *const lo_count, uint32_t *const hi_count)
Get the current period values of a PWM channel.
Definition: qm_pwm.c:151
uint32_t hi_count
Number of cycles the PWM output is driven high.
Definition: qm_pwm.h:43