pwm.h

Go to the documentation of this file.

#ifndef DRIVER_PWM_H
#define DRIVER_PWM_H
/**********************************************************************/
/*
 * Copyright (c) 2013-2017, Jetro AS
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without modification,
 * are permitted provided that the following conditions are met:
 *
 * 1. Redistributions of source code must retain the above copyright notice,
 *    this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright notice,
 *    this list of conditions and the following disclaimer in the documentation
 *    and/or other materials provided with the distribution.
 * 3. The name of the author may not be used to endorse or promote products
 *    derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONRIBUTORS ``AS IS'' AND ANY EXPRESS
 * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
 * SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
 * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
 * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
 * OF SUCH DAMAGE.
 *
 * This file is part of the EVE platform.
 */

/**
 * \file
 * @brief Driver for PWM in nRF52.
 *
 * @author KLO, Jetro AS
 */ /******************************************************************/

#include <dev/gpio.h>
#include <hal/nrf_pwm.h>

/**
 * \defgroup pwm nRF52 PWM driver
 * \ingroup nrf52
 * \{
 *
 * This PWM driver can be used for PWM0, PWM1 and PWM2.
 * For each PWM instance, state variables must be initilalized in RAM,
 * and configuration data must be initilalized in FLASH.
 *
 * The state variable is of type struct pwm_state_t, and is used to hold
 * a copy of used PWM values. The variable should not be initialized.
 *
 * The configuration data is of type struct pwm_t, and is used to set:
 * - Which PWM block to be used
 * - Clock prescaler
 * - A pointer to the PWM state
 * - Frequency: The frequency in Hz for the generated PWM
 * - Mode: Edge- or center-aligned pulse generation
 * - Range: The range for the PWM (counts from 0 to Range)
     Example:
       100: Result in % resolution (0 to 100)
       1023: 10 bits resolution (0 to 1023)
 * - Which channels to be used and which channels with inverted outputs
 *   (struct pwm_channel_config_t)
 * - Location: Selects location for the PWM output pins (_TIMER_ROUTE_LOCATION_LOC0 -- 6)
 *
 * The timer is counting from 0 to TOP value.
 * TOP value = (16 MHz clock / (2^Prescaler) / Frequency).
 * Care must be taken to obtain enough resolution. Set Prescaler as low as possible.
 *
 */

/***********************************************************************
 * Global defines
***********************************************************************/
/**
 * Number of PWM channels available
 */
#define PWM_NUM_CHANNELS  4

/**
 * pwm_state_t structure holds clock lock state and copy of used PWM values.
 * The structure will be set by the PwmSet() function.
 *
 */
struct pwm_state_t
{
  uint16_t ChannelValue[PWM_NUM_CHANNELS];
  uint16_t TopValue;
  uint8_t Shutdown;
  uint8_t SeqActive;
};

/**
 * pwm_channel_config_t structure is used for configuration of PWM channels
 * without dead time insertion.
 * The structure must be initialized as a part of the PWM configuration.
 *
 */
struct pwm_channel_config_t
{
  uint8_t Pin : GPIO_PIN_ID_WIDTH;                ///< GPIO pin location
  uint8_t Enable : 1;                             ///< true if this channel is allowed for PWM
  uint8_t Invert : 1;                             ///< Invert output
};

/**
 * pwm_t structure is used for configuration of PWM.
 * The structure must be initialized before the PWM driver may be used.
 *
 */
struct pwm_t
{
  NRF_PWM_Type *Dev;
  uint32_t IrqPriority;                           ///< HW IRQ priority (see enum EVE_IRQ_PRIORITIES)
  struct pwm_state_t *State;
  nrf_pwm_clk_t BaseClock;                        ///< Base PWM clock
  uint32_t DefaultFrequency;                      ///< TOP_Value = BaseClock / Frequency - 1
  uint16_t Range;                                 ///< PWM counts from 0 to Range
  struct pwm_channel_config_t ChannelConfig[PWM_NUM_CHANNELS]; ///< Channel config
  nrf_pwm_mode_t Mode;                            ///< Edge- or center-aligned mode
};

 /**
  * @name Functions called from application programs
  * @{
  */

/**********************************************************************/
/**
 * @brief Name:     PwmInit\n
 * Initialize PWM.
 *
 * @param Pwm       Configuration structure for PWM to be used.
 ***********************************************************************/
void PwmInit(const struct pwm_t *Pwm);

/**********************************************************************/
/**
 * @brief Name:     PwmSet\n
 * Sets PWM duty cycle for the selected channel.
 *
 * @param Pwm       Configuration structure for PWM to be used.
 * @param Channel   0-2
 * @param Value     PWM active time (0 to Range set in struct pwm_t)
 ***********************************************************************/
extern void PwmSet(const struct pwm_t *Pwm, uint8_t Channel, uint16_t Value);

/**********************************************************************/
/**
 * @brief Name:     PwmFrequencySet\n
 * Sets the PWM frequency.
 * This frequency will be used for all channels on the selected timer.
 *
 * @param Pwm       Configuration structure for PWM to be used.
 * @param Frequency The frequency in Hz for the generated PWM
 ***********************************************************************/
extern void PwmFrequencySet(const struct pwm_t *Pwm, uint32_t Frequency);

/**********************************************************************/
/**
 * @brief Name:     PwmInterruptHandler\n
 * PWM interrupt handler
 * Called from board.c at hardware interrupt context.
 *
 * @param Pwm       PWM instance
 ***********************************************************************/
extern void PwmInterruptHandler(const struct pwm_t *Pwm);

/** @} */
/** \} */

#endif // DRIVER_PWM_H