Boot Linux faster!

Check our new training course

Boot Linux faster!

Check our new training course
and Creative Commons CC-BY-SA
lecture and lab materials

Bootlin logo

Elixir Cross Referencer

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
/*
 * Copyright (c) 2016 Intel Corporation.
 *
 * SPDX-License-Identifier: Apache-2.0
 */

/**
 * @file
 * @brief Public PWM Driver APIs
 */

#ifndef __PWM_H__
#define __PWM_H__

/**
 * @brief PWM Interface
 * @defgroup pwm_interface PWM Interface
 * @ingroup io_interfaces
 * @{
 */

#ifdef __cplusplus
extern "C" {
#endif

#define PWM_ACCESS_BY_PIN	0
#define PWM_ACCESS_ALL		1

#include <errno.h>
#include <stdint.h>
#include <stddef.h>
#include <device.h>

/**
 * @typedef pwm_config_t
 * @brief Callback API upon configuration
 * See @a pwm_pin_configure() for argument description
 */
typedef int (*pwm_config_t)(struct device *dev, int access_op,
			    uint32_t pwm, int flags);

/**
 * @typedef pwm_set_values_t
 * @brief Callback API upon setting PIN values
 * See @a pwm_pin_set_values() for argument description
 */
typedef int (*pwm_set_values_t)(struct device *dev, int access_op,
				uint32_t pwm, uint32_t on, uint32_t off);

/**
 * @typedef pwm_set_duty_cycle_t
 * @brief Callback API upon setting the duty cycle
 * See @a pwm_pin_set_duty_cycle() for argument description
 */
typedef int (*pwm_set_duty_cycle_t)(struct device *dev, int access_op,
				    uint32_t pwm, uint8_t duty);

/**
 * @typedef pwm_set_phase_t
 * @brief Callback API upon setting the phase
 * See @a pwm_pin_set_phase() for argument description
 */
typedef int (*pwm_set_phase_t)(struct device *dev, int access_op,
			       uint32_t pwm, uint8_t phase);

/**
 * @typedef pwm_set_period_t
 * @brief Callback API upon setting the period
 * See @a pwm_pin_set_period() for argument description
 */
typedef int (*pwm_set_period_t)(struct device *dev, int access_op,
				uint32_t pwm, uint32_t period);

/**
 * @typedef pwm_pin_set_t
 * @brief Callback API upon setting the pin
 * See @a pwm_pin_set_cycles() for argument description
 */
typedef int (*pwm_pin_set_t)(struct device *dev, uint32_t pwm,
			     uint32_t period_cycles, uint32_t pulse_cycles);

/**
 * @typedef pwm_get_cycles_per_sec_t
 * @brief Callback API upon getting cycles per second
 * See @a pwm_get_cycles_per_sec() for argument description
 */
typedef int (*pwm_get_cycles_per_sec_t)(struct device *dev, uint32_t pwm,
					uint64_t *cycles);

/** @brief PWM driver API definition. */
struct pwm_driver_api {
	pwm_config_t config;
	pwm_set_values_t set_values;
	pwm_set_period_t set_period;
	pwm_set_duty_cycle_t set_duty_cycle;
	pwm_set_phase_t set_phase;
	pwm_pin_set_t pin_set;
	pwm_get_cycles_per_sec_t get_cycles_per_sec;
};

/**
 * @brief Set the period and pulse width for a single PWM output.
 *
 * @param dev Pointer to the device structure for the driver instance.
 * @param pwm PWM pin.
 * @param period Period (in clock cycle) set to the PWM. HW specific.
 * @param pulse Pulse width (in clock cycle) set to the PWM. HW specific.
 *
 * @retval 0 If successful.
 * @retval Negative errno code if failure.
 */
static inline int pwm_pin_set_cycles(struct device *dev, uint32_t pwm,
				     uint32_t period, uint32_t pulse)
{
	struct pwm_driver_api *api;

	api = (struct pwm_driver_api *)dev->driver_api;
	return api->pin_set(dev, pwm, period, pulse);
}

/**
 * @brief Set the period and pulse width for a single PWM output.
 *
 * @param dev Pointer to the device structure for the driver instance.
 * @param pwm PWM pin.
 * @param period Period (in micro second) set to the PWM.
 * @param pulse Pulse width (in micro second) set to the PWM.
 *
 * @retval 0 If successful.
 * @retval Negative errno code if failure.
 */
static inline int pwm_pin_set_usec(struct device *dev, uint32_t pwm,
				   uint32_t period, uint32_t pulse)
{
	struct pwm_driver_api *api;
	uint64_t period_cycles, pulse_cycles, cycles_per_sec;

	api = (struct pwm_driver_api *)dev->driver_api;

	if (api->get_cycles_per_sec(dev, pwm, &cycles_per_sec) != 0) {
		return -EIO;
	}

	period_cycles = (period * cycles_per_sec) / USEC_PER_SEC;
	if (period_cycles >= ((uint64_t)1 << 32)) {
		return -ENOTSUP;
	}

	pulse_cycles = (pulse * cycles_per_sec) / USEC_PER_SEC;
	if (pulse_cycles >= ((uint64_t)1 << 32)) {
		return -ENOTSUP;
	}

	return api->pin_set(dev, pwm, (uint32_t)period_cycles,
			    (uint32_t)pulse_cycles);
}

/**
 * @brief Get the clock rate (cycles per second) for a single PWM output.
 *
 * @param dev Pointer to the device structure for the driver instance.
 * @param pwm PWM pin.
 * @param cycles Pointer to the memory to store clock rate (cycles per sec).
 *		 HW specific.
 *
 * @retval 0 If successful.
 * @retval Negative errno code if failure.
 */
static inline int pwm_get_cycles_per_sec(struct device *dev, uint32_t pwm,
					 uint64_t *cycles)
{
	struct pwm_driver_api *api;

	api = (struct pwm_driver_api *)dev->driver_api;
	return api->get_cycles_per_sec(dev, pwm, cycles);
}

/**
 * @brief Configure a single PWM output.
 *
 * @deprecated This API will be deprecated.
 *
 * @param dev Pointer to the device structure for the driver instance.
 * @param pwm PWM output.
 * @param flags PWM configuration flags.
 *
 * @retval 0 If successful,
 * @retval Negative errno code if failure.
 */
static inline int __deprecated pwm_pin_configure(struct device *dev,
						 uint8_t pwm, int flags)
{
	const struct pwm_driver_api *api = dev->driver_api;

	return api->config(dev, PWM_ACCESS_BY_PIN, pwm, flags);
}

/**
 * @brief Set the ON/OFF values for a single PWM output.
 *
 * @deprecated This API will be deprecated. Please use the new API
 *	       pwm_pin_set_cycles.
 *
 * @param dev Pointer to the device structure for the driver instance.
 * @param pwm PWM output.
 * @param on ON value (number of timer count) set to the PWM. HW specific.
 *	     How far from the beginning of a PWM cycle the PWM pulse starts.
 * @param off OFF value (number of timer count) set to the PWM. HW specific.
 *	      How far from the beginning of a PWM cycle the PWM pulse stops.
 *
 * @retval 0 If successful.
 * @retval Negative errno code if failure.
 */
static inline int __deprecated pwm_pin_set_values(struct device *dev,
						  uint32_t pwm, uint32_t on,
						  uint32_t off)
{
	const struct pwm_driver_api *api = dev->driver_api;

	return api->set_values(dev, PWM_ACCESS_BY_PIN, pwm, on, off);
}

/**
 * @brief Set the period of a single PWM output.
 *
 * @deprecated This API will be deprecated. Please use the new API
 *	       pwm_pin_set_usec.
 *
 * It is optional to call this API. If not called, there is a default
 * period.
 *
 * @param dev Pointer to the device structure for the driver instance.
 * @param pwm PWM output.
 * @param period Period duration of the cycle to set in microseconds
 *
 * @retval 0 If successful.
 * @retval Negative errno code if failure.
 */
static inline int __deprecated pwm_pin_set_period(struct device *dev,
						  uint32_t pwm,
						  uint32_t period)
{
	const struct pwm_driver_api *api = dev->driver_api;

	return api->set_period(dev, PWM_ACCESS_BY_PIN, pwm, period);
}

/**
 * @brief Set the duty cycle of a single PWM output.
 *
 * @deprecated This API will be deprecated. Please use the new API
 *	       pwm_pin_set_cycles or pwm_pin_set_usec.
 *
 * This routine overrides any ON/OFF values set before.
 *
 * @param dev Pointer to the device structure for the driver instance.
 * @param pwm PWM output.
 * @param duty Duty cycle to set to the PWM in %, for example,
 *        50 sets to 50%.
 *
 * @retval 0 If successful.
 * @retval Negative errno code if failure.
 */
static inline int __deprecated pwm_pin_set_duty_cycle(struct device *dev,
						      uint32_t pwm,
						      uint8_t duty)
{
	const struct pwm_driver_api *api = dev->driver_api;

	return api->set_duty_cycle(dev, PWM_ACCESS_BY_PIN, pwm, duty);
}

/**
 * @brief Set the phase of a single PWM output.
 *
 * @deprecated This API will be deprecated. Set_phase will not be supported
 *	       any more.
 *
 * This routine sets the delay before pulses.
 *
 * @param dev Pointer to the device structure for the driver instance.
 * @param pwm PWM output.
 * @param phase The number of clock ticks to delay before the start of pulses.
 *
 * @retval 0 If successful.
 * @retval Negative errno code if failure.
 */
static inline int __deprecated pwm_pin_set_phase(struct device *dev,
						 uint32_t pwm, uint8_t phase)
{
	const struct pwm_driver_api *api = dev->driver_api;

	if ((api != NULL) && (api->set_phase != NULL)) {
		return api->set_phase(dev, PWM_ACCESS_BY_PIN, pwm, phase);
	}

	return -ENOTSUP;
}

/**
 * @brief Configure all the PWM outputs.
 *
 * @deprecated This API will be deprecated.
 *
 * @param dev Pointer to the device structure for the driver instance.
 * @param flags PWM configuration flags.
 *
 * @retval 0 If successful.
 * @retval Negative errno code if failure.
 */
static inline int __deprecated pwm_all_configure(struct device *dev, int flags)
{
	const struct pwm_driver_api *api = dev->driver_api;

	return api->config(dev, PWM_ACCESS_ALL, 0, flags);
}

/**
 * @brief Set the ON/OFF values for all PWM outputs.
 *
 * @deprecated This API will be deprecated. Please use the new API
 *	       pwm_pin_set_cycles or pwm_pin_set_usec to set the pins
 *	       individually.
 *
 * @param dev Pointer to the device structure for the driver instance.
 * @param on ON value (number of timer count) set to the PWM. HW specific.
 *	     How far from the beginning of a PWM cycle the PWM pulse starts.
 * @param off OFF value (number of timer count) set to the PWM. HW specific.
 *	      How far from the beginning of a PWM cycle the PWM pulse stops.
 *
 * @retval 0 If successful.
 * @retval Negative errno code if failure.
 */
static inline int __deprecated pwm_all_set_values(struct device *dev,
						  uint32_t on, uint32_t off)
{
	const struct pwm_driver_api *api = dev->driver_api;

	return api->set_values(dev, PWM_ACCESS_ALL, 0, on, off);
}

/**
 * @brief Set the period of all PWM outputs.
 *
 * @deprecated This API will be deprecated. Please use the new API
 *	       pwm_pin_set_cycles or pwm_pin_set_usec to set the pins
 *	       individually.
 *
 * It is optional to call this API. If not called, there is a default
 * period.
 *
 * @param dev Pointer to the device structure for the driver instance.
 * @param period Period duration of the cycle to set in microseconds
 *
 * @retval 0 If successful.
 * @retval Negative errno code if failure.
 */
static inline int __deprecated pwm_all_period(struct device *dev,
					      uint32_t period)
{
	const struct pwm_driver_api *api = dev->driver_api;

	return api->set_period(dev, PWM_ACCESS_ALL, 0, period);
}

/**
 * @brief Set the duty cycle of all PWM outputs.
 *
 * @deprecated This API will be deprecated. Please use the new API
 *	       pwm_pin_set_cycles or pwm_pin_set_usec to set the pins
 *	       individually.
 *
 * This overrides any ON/OFF values being set before.
 *
 * @param dev Pointer to the device structure for the driver instance.
 * @param duty Duty cycle to set to the PWM in %, for example,
 *        50 sets to 50%.
 *
 * @retval 0 If successful.
 * @retval Negative errno code if failure.
 */
static inline int __deprecated pwm_all_set_duty_cycle(struct device *dev,
						      uint8_t duty)
{
	const struct pwm_driver_api *api = dev->driver_api;

	return api->set_duty_cycle(dev, PWM_ACCESS_ALL, 0, duty);
}

/**
 * @brief Set the phase of all PWM outputs.
 *
 * @deprecated This API will be deprecated. Set_phase will not be supported
 *	       any more.
 *
 * This routine sets the delay before pulses.
 *
 * @param dev Pointer to the device structure for the driver instance.
 * @param phase The number of clock ticks to delay before the start of pulses.
 *
 * @retval 0 If successful.
 * @retval Negative errno code if failure.
 */
static inline int __deprecated pwm_all_set_phase(struct device *dev,
						 uint8_t phase)
{
	const struct pwm_driver_api *api = dev->driver_api;

	if ((api != NULL) && (api->set_phase != NULL)) {
		return api->set_phase(dev, PWM_ACCESS_ALL, 0, phase);
	}

	return -ENOTSUP;
}

#ifdef __cplusplus
}
#endif

/**
 * @}
 */

#endif /* __PWM_H__ */