hsk_pwm.h

Go to the documentation of this file.

/** \file
 * HSK Pulse Width Modulation headers
 *
 * This file provides function prototypes to perform Timer T12 and T13
 * based PWM with CCU6.
 *
 * The CCU6 offers the following PWM channels:
 * - PWM_60
 * - PWM_61
 * - PWM_62
 * - PWM_63
 *
 * Each PWM channel is connected to two IO channels for output:
 * - PWM_CCx
 * - PWM_COUTx
 *
 * The distinction between PWM and IO channels is important to understand
 * the side effects of some operations.
 *
 * Refer to the PWM_OUT_x_* defines to know which channel can be connected to
 * which output pins.
 *
 * The functions are implemented under the assumption, that the use of
 * the timers T12 and T13 as well of the CCU6 is exclusive to this library.
 *
 * The safe boot order for pwm output is the following:
 * - hsk_pwm_init()
 * - hsk_pwm_enable()
 * - hsk_pwm_port_open()
 *
 * @author kami
 */

#ifndef _HSK_PWM_H_
#define _HSK_PWM_H_

/**
 * Type definition for PWM channels.
 */
typedef ubyte hsk_pwm_channel;

/**
 * PWM channel 60, Timer T12 driven.
 */
#define PWM_60            0

/**
 * PWM channel 61, Timer T12 driven.
 */
#define PWM_61            1

/**
 * PWM channel 62, Timer T12 driven.
 */
#define PWM_62            2

/**
 * PWM channel 63, Timer T13 driven.
 */
#define PWM_63            3

/**
 * Type definition for output channels.
 */
typedef ubyte hsk_pwm_outChannel;

/**
 * IO channel configuration for PWM_60.
 */
#define PWM_CC60          0

/**
 * Output channel configuration for PWM_60.
 */
#define PWM_COUT60        1

/**
 * IO channel configuration for PWM_61.
 */
#define PWM_CC61          2

/**
 * Output channel configuration for PWM_61.
 */
#define PWM_COUT61        3

/**
 * IO channel configuration for PWM_62.
 */
#define PWM_CC62          4

/**
 * Output channel configuration for PWM_62,
 */
#define PWM_COUT62        5

/**
 * Output channel configuration for PWM_63.
 */
#define PWM_COUT63        6

/**
 * Type definition for ports.
 */
typedef ubyte hsk_pwm_port;

/**
 * PWM_60 output configuration for P3.0 through PWM_CC60.
 */
#define PWM_OUT_60_P30    0

/**
 * PWM_60 output configuration for P3.1 through PWM_COUT60.
 */
#define PWM_OUT_60_P31    1

/**
 * PWM_60 output configuration for P4.0 through PWM_CC60.
 */
#define PWM_OUT_60_P40    2

/**
 * PWM_60 output configuration for P4.1 through PWM_COUT60.
 */
#define PWM_OUT_60_P41    3

/**
 * PWM_61 output configuration for P0.0 through PWM_CC61.
 */
#define PWM_OUT_61_P00    4

/**
 * PWM_61 output configuration for P0.1 through  PWM_COUT61.
 */
#define PWM_OUT_61_P01    5

/**
 * PWM_61 output configuration for P3.1 through  PWM_CC61.
 */
#define PWM_OUT_61_P31    6

/**
 * PWM_61 output configuration for P3.2 through PWM_CC61.
 */
#define PWM_OUT_61_P32    7

/**
 * PWM_61 output configuration for P3.3 through PWM_COUT61.
 */
#define PWM_OUT_61_P33    8

/**
 * PWM_61 output configuration for P4.4 through PWM_CC61.
 */
#define PWM_OUT_61_P44    9

/**
 * PWM_61 output configuration for P4.5 through PWM_COUT61.
 */
#define PWM_OUT_61_P45    10

/**
 * PWM_62 output configuration for P0.4 through PWM_CC62.
 */
#define PWM_OUT_62_P04    11

/**
 * PWM_62 output configuration for P0.5 through PWM_COUT62.
 */
#define PWM_OUT_62_P05    12

/**
 * PWM_62 output configuration for P3.4 through PWM_CC62.
 */
#define PWM_OUT_62_P34    13

/**
 * PWM_62 output configuration for P3.5 through PWM_COUT62.
 */
#define PWM_OUT_62_P35    14

/**
 * PWM_62 output configuration for P4.6 through PWM_CC62.
 */
#define PWM_OUT_62_P46    15

/**
 * PWM_62 output configuration for P4.7 through PWM_COUT62.
 */
#define PWM_OUT_62_P47    16

/**
 * PWM_63 output configuration for P0.3 through PWM_COUT63.
 */
#define PWM_OUT_63_P03    17

/**
 * PWM_63 output configuration for P3.7 through PWM_COUT63.
 */
#define PWM_OUT_63_P37    18

/**
 * PWM_63 output configuration for P4.3 through PWM_COUT63.
 */
#define PWM_OUT_63_P43    19

/**
 * Sets up the the CCU6 timer frequencies that control the PWM
 * cycle.
 *
 * The channels PWM_60, PWM_61 and PWM_62 share the timer T12, thus
 * initializing one of them, initializes them all.
 * The channel PWM_63 has exclusive use of the timer T13 and can thus be used
 * with its own operating frequency.
 *
 * Frequencies up to ~732.4Hz are always between 15 and 16 bits precision.
 *
 * Frequencies above 48kHz offer less than 1/1000 precision.
 * From there it is a linear function, i.e. 480kHz still offer 1/100
 * precision.
 *
 * The freq value 0 will result in ~0.02Hz (\f$48000000 / 2^{31}\f$).
 *
 * The following formula results in the freq value that yields exactly the
 * desired precision, this is useful to avoid precision loss by rounding:
 *      \f[freq(precision) = 480000000 * precision\f]
 *
 * E.g. 10 bit precision: \f$freq(1/2^{10}) = 468750\f$
 *
 * @param channel
 *      The channel to change the frequency for
 * @param freq
 *      The desired PWM cycle frequency in units of 0.1Hz
 */
void hsk_pwm_init(const hsk_pwm_channel channel, const ulong freq);

/**
 * Set up a PWM output port.
 *
 * This configures the necessary port direction bits and activates the
 * corresponding output channels.
 *
 * The port can be any one of the PWM_OUT_x_* defines.
 *
 * @pre
 *      This function should only be called after hsk_pwm_enable(), otherwise
 *      the output port will be driven (1) until PWM is enabled
 * @param port
 *      The output port to activate
 */
void hsk_pwm_port_open(const hsk_pwm_port port);

/**
 * Close a PWM output port.
 *
 * This configures the necessary port direction bits.
 *
 * The port can be any one of the PWM_OUT_x_* defines.
 *
 * @param port
 *      The output port to deactivate
 */
void hsk_pwm_port_close(const hsk_pwm_port port);

/**
 * Set the duty cycle for the given channel.
 *
 * I.e. the active time frame slice of period can be set with max and value.
 *
 * To set the duty cycle in percent specify a max of 100 and values from 0 to
 * 100.
 *
 * @param channel
 *      The PWM channel to set the duty cycle for, check the PWM_6x defines
 * @param max
 *      Defines the scope value can move in
 * @param value
 *      The current duty cycle value
 */
void hsk_pwm_channel_set(const hsk_pwm_channel channel,
                         const uword max, const uword value);

/**
 * Set the direction of an output channel.
 *
 * The channel value can be taken from any of the PWM_CCx/PWM_COUTx defines.
 *
 * @param channel
 *      The IO channel to set the direction bit for
 * @param up
 *      Set 1 to output a 1 during the cycle set with hsk_pwm_channel_set(),
 *      set 0 to output a 0 during the cycle set with hsk_pwm_channel_set()
 */
void hsk_pwm_outChannel_dir(hsk_pwm_outChannel channel,
                            const bool up);

/**
 * Turns on the CCU6.
 *
 * Deactivates the power disable mode and sets the T12 and T13 Timer Run bits.
 *
 * @pre
 *      All hsk_pwm_init() calls have to be completed to call this
 */
void hsk_pwm_enable(void);

/**
 * Deactivates the CCU6 to reduce power consumption.
 */
void hsk_pwm_disable(void);

#endif /* _HSK_PWM_H_ */