PWM.h

Go to the documentation of this file.

/*
 * Copyright (c) 2015-2018, Texas Instruments Incorporated
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * *  Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *
 * *  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.
 *
 * *  Neither the name of Texas Instruments Incorporated nor the names of
 *    its contributors may be used to endorse or promote products derived
 *    from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "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 COPYRIGHT OWNER OR
 * CONTRIBUTORS 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.
 */
/*!****************************************************************************
 *  @file       PWM.h
 *  @brief      PWM driver interface
 *
 *  To use the PWM driver, ensure that the correct driver library for your
 *  device is linked in and include this header file as follows:
 *  @code
 *  #include <ti/drivers/PWM.h>
 *  @endcode
 *
 *  This module serves as the main interface for applications.  Its purpose
 *  is to redirect the PWM APIs to specific driver implementations
 *  which are specified using a pointer to a #PWM_FxnTable.
 *
 *  # Overview #
 *  The PWM driver in TI-RTOS facilitates the generation of Pulse Width
 *  Modulated signals via simple and portable APIs.  PWM instances must be
 *  opened by calling PWM_open() while passing in a PWM index and a parameters
 *  data structure.
 *
 *  The driver APIs serve as an interface to a typical TI-RTOS application.
 *  The specific peripheral implementations are responsible for creating all OS
 *  specific primitives to allow for thread-safe operation.
 *
 *  When a PWM instance is opened, the period, duty cycle and idle level are
 *  configured and the PWM is stopped (waveforms not generated until PWM_start()
 *  is called).  The maximum period and duty supported is device dependent;
 *  refer to the implementation specific documentation for values.
 *
 *  PWM outputs are active-high, meaning the duty will control the duration of
 *  high output on the pin (at 0% duty, the output is always low, at 100% duty,
 *  the output is always high).
 *
 *  # Usage #
 *
 *  @code
 *    PWM_Handle pwm;
 *    PWM_Params pwmParams;
 *    uint32_t   dutyValue;
 *
 *    // Initialize the PWM driver.
 *    PWM_init();
 *
 *    // Initialize the PWM parameters
 *    PWM_Params_init(&pwmParams);
 *    pwmParams.idleLevel = PWM_IDLE_LOW;      // Output low when PWM is not running
 *    pwmParams.periodUnits = PWM_PERIOD_HZ;   // Period is in Hz
 *    pwmParams.periodValue = 1e6;             // 1MHz
 *    pwmParams.dutyUnits = PWM_DUTY_FRACTION; // Duty is in fractional percentage
 *    pwmParams.dutyValue = 0;                 // 0% initial duty cycle
 *
 *    // Open the PWM instance
 *    pwm = PWM_open(Board_PWM0, &pwmParams);
 *
 *    if (pwm == NULL) {
 *        // PWM_open() failed
 *        while (1);
 *    }
 *
 *    PWM_start(pwm);                          // start PWM with 0% duty cycle
 *
 *    dutyValue = (uint32_t) (((uint64_t) PWM_DUTY_FRACTION_MAX * 37) / 100);
 *    PWM_setDuty(pwm, dutyValue);  // set duty cycle to 37%
 *  @endcode
 *
 *  Details for the example code above are described in the following
 *  subsections.
 *
 *  ### PWM Driver Configuration #
 *
 *  In order to use the PWM APIs, the application is required
 *  to provide device-specific PWM configuration in the Board.c file.
 *  The PWM driver interface defines a configuration data structure:
 *
 *  @code
 *  typedef struct PWM_Config_ {
 *      PWM_FxnTable const    *fxnTablePtr;
 *      void                  *object;
 *      void         const    *hwAttrs;
 *  } PWM_Config;
 *  @endcode
 *
 *  The application must declare an array of PWM_Config elements, named
 *  PWM_config[].  Each element of PWM_config[] is populated with
 *  pointers to a device specific PWM driver implementation's function
 *  table, driver object, and hardware attributes.  The hardware attributes
 *  define properties such as which pin will be driven, and which timer peripheral
 *  will be used.  Each element in PWM_config[] corresponds to
 *  a PWM instance, and none of the elements should have NULL pointers.
 *
 *  Additionally, the PWM driver interface defines a global integer variable
 *  'PWM_count' which is initialized to the number of PWM instances the
 *  application has defined in the PWM_Config array.
 *
 *  You will need to check the device-specific PWM driver implementation's
 *  header file for example configuration.  Please also refer to the
 *  Board.c file of any of your examples to see the PWM configuration.
 *
 *  ### Initializing the PWM Driver #
 *
 *  PWM_init() must be called before any other PWM APIs.  This function
 *  calls the device implementation's PWM initialization function, for each
 *  element of PWM_config[].
 *
 *  ### Opening the PWM Driver #
 *
 *  Opening a PWM requires four steps:
 *  1.  Create and initialize a PWM_Params structure.
 *  2.  Fill in the desired parameters.
 *  3.  Call PWM_open(), passing the index of the PWM in the PWM_config
 *      structure, and the address of the PWM_Params structure.  The
 *      PWM instance is specified by the index in the PWM_config structure.
 *  4.  Check that the PWM handle returned by PWM_open() is non-NULL,
 *      and save it.  The handle will be used to read and write to the
 *      PWM you just opened.
 *
 *  Only one PWM index can be used at a time; calling PWM_open() a second
 *  time with the same index previously passed to PWM_open() will result in
 *  an error.  You can, though, re-use the index if the instance is closed
 *  via PWM_close().
 *  In the example code, Board_PWM0 is passed to PWM_open().  This macro
 *  is defined in the example's Board.h file.
 *
 *  ### Modes of Operation #
 *
 *  A PWM instance can be configured to interpret the period as one of three
 *  units:
 *      - #PWM_PERIOD_US: The period is in microseconds.
 *      - #PWM_PERIOD_HZ: The period is in (reciprocal) Hertz.
 *      - #PWM_PERIOD_COUNTS: The period is in timer counts.
 *
 *  A PWM instance can be configured to interpret the duty as one of three
 *  units:
 *      - #PWM_DUTY_US: The duty is in microseconds.
 *      - #PWM_DUTY_FRACTION: The duty is in a fractional part of the period
 *                           where 0 is 0% and #PWM_DUTY_FRACTION_MAX is 100%.
 *      - #PWM_DUTY_COUNTS: The period is in timer counts and must be less than
 *                         the period.
 *
 *  The idle level parameter is used to set the output to high/low when the
 *  PWM is not running (stopped or not started).  The idle level can be
 *  set to:
 *      - #PWM_IDLE_LOW
 *      - #PWM_IDLE_HIGH
 *
 *  The default PWM configuration is to set a duty of 0% with a 1MHz frequency.
 *  The default period units are in PWM_PERIOD_HZ and the default duty units
 *  are in PWM_DUTY_FRACTION.  Finally, the default output idle level is
 *  PWM_IDLE_LOW.  It is the application's responsibility to set the duty for
 *  each PWM output used.
 *
 *  ### Controlling the PWM Duty Cycle #
 *
 *  Once the PWM instance has been opened and started, the primary API used
 *  by the application will be #PWM_setDuty() to control the duty cycle of a
 *  PWM pin:
 *
 *  Below demonstrates setting the duty cycle to 45%.
 *
 *  @code
 *     uint32_t dutyCycle;
 *
 *     dutyCycle = (uint32_t) (((uint64_t) PWM_DUTY_FRACTION_MAX * 45) / 100);
 *     PWM_setDuty(pwm, dutyCycle);
 *  @endcode
 *
 *  ### Setting Duty and Period on a Running Instance ###
 *
 *  If an application needs to modify the duty and period of a running timer,
 *  an API is available to set both with as little interim time as possible.
 *  This minimises the possibility that a timeout will occur between one set
 *  call and the other. For low periods or for instances close to timeout, this
 *  API will pause the instance output briefly and must only be called when the
 *  PWM is already running.
 *
 *  Below demonstrates setting the duty cycle to 75% of the new period (100us).
 *
 *  @code
 *     uint32_t dutyCycle;
 *     uint32_t periodUs = 100;
 *
 *     dutyCycle = (uint32_t) (((uint64_t) PWM_DUTY_FRACTION_MAX * 75) / 100);
 *     PWM_setDutyAndPeriod(pwm, dutyCycle, periodUs);
 *  @endcode
 *
 *  # Implementation #
 *
 *  The PWM driver interface module is joined (at link time) to an
 *  array of PWM_Config data structures named *PWM_config*.
 *  PWM_config is implemented in the application with each entry being a
 *  PWM instance. Each entry in *PWM_config* contains a:
 *  - (PWM_FxnTable *) to a set of functions that implement a PWM peripheral
 *  - (void *) data object that is associated with the PWM_FxnTable
 *  - (void *) hardware attributes that are associated with the PWM_FxnTable
 *
 *  The PWM APIs are redirected to the device specific implementations
 *  using the PWM_FxnTable pointer of the PWM_config entry.
 *  In order to use device specific functions of the PWM driver directly,
 *  link in the correct driver library for your device and include the
 *  device specific PWM driver header file (which in turn includes PWM.h).
 *  For example, for the MSP432 family of devices, you would include the
 *  following header file:
 *    @code
 *    #include <ti/drivers/pwm/PWMTimerMSP432.h>
 *    @endcode
 *
 *****************************************************************************
 */

#ifndef ti_drivers_PWM__include
#define ti_drivers_PWM__include

#ifdef __cplusplus
extern "C" {
#endif

#include <stdint.h>

#define PWM_DUTY_FRACTION_MAX        ((uint32_t) ~0)

#define PWM_CMD_RESERVED             (32)

#define PWM_STATUS_RESERVED          (-32)

#define PWM_STATUS_SUCCESS           (0)

#define PWM_STATUS_ERROR             (-1)

#define PWM_STATUS_UNDEFINEDCMD      (-2)

#define PWM_STATUS_INVALID_PERIOD    (-3)

#define PWM_STATUS_INVALID_DUTY      (-4)

typedef enum PWM_Period_Units_ {
    PWM_PERIOD_US,    
    PWM_PERIOD_HZ,    
    PWM_PERIOD_COUNTS 
} PWM_Period_Units;

typedef enum PWM_Duty_Units_ {
    PWM_DUTY_US,       
    PWM_DUTY_FRACTION, 
    PWM_DUTY_COUNTS    
} PWM_Duty_Units;

typedef enum PWM_IdleLevel_ {
    PWM_IDLE_LOW  = 0,
    PWM_IDLE_HIGH = 1,
} PWM_IdleLevel;

typedef struct PWM_Params_ {
    PWM_Period_Units periodUnits; 
    uint32_t         periodValue; 
    PWM_Duty_Units   dutyUnits;   
    uint32_t         dutyValue;   
    PWM_IdleLevel    idleLevel;   
    void            *custom;      
} PWM_Params;

typedef struct PWM_Config_ *PWM_Handle;

typedef void (*PWM_CloseFxn) (PWM_Handle handle);

typedef int_fast16_t (*PWM_ControlFxn) (PWM_Handle handle, uint_fast16_t cmd,
                                        void *arg);
typedef void (*PWM_InitFxn) (PWM_Handle handle);

typedef PWM_Handle (*PWM_OpenFxn) (PWM_Handle handle, PWM_Params *params);

typedef int_fast16_t (*PWM_SetDutyFxn) (PWM_Handle handle,
                                        uint32_t duty);

typedef int_fast16_t (*PWM_SetPeriodFxn) (PWM_Handle handle,
        uint32_t period);

typedef int_fast16_t (*PWM_SetDutyAndPeriodFxn) (PWM_Handle handle,
        uint32_t duty, uint32_t period);

typedef void (*PWM_StartFxn) (PWM_Handle handle);

typedef void (*PWM_StopFxn) (PWM_Handle handle);

typedef struct PWM_FxnTable_ {
    PWM_CloseFxn     closeFxn;
    PWM_ControlFxn   controlFxn;
    PWM_InitFxn      initFxn;
    PWM_OpenFxn      openFxn;
    PWM_SetDutyFxn   setDutyFxn;
    PWM_SetPeriodFxn setPeriodFxn;
    PWM_SetDutyAndPeriodFxn setDutyAndPeriodFxn;
    PWM_StartFxn     startFxn;
    PWM_StopFxn      stopFxn;
} PWM_FxnTable;

typedef struct PWM_Config_ {
    PWM_FxnTable const *fxnTablePtr;
    void               *object;
    void         const *hwAttrs;
} PWM_Config;

extern void PWM_close(PWM_Handle handle);

extern int_fast16_t PWM_control(PWM_Handle handle, uint_fast16_t cmd,
                                void *arg);

extern void PWM_init(void);

extern PWM_Handle PWM_open(uint_least8_t index, PWM_Params *params);

extern void PWM_Params_init(PWM_Params *params);

extern int_fast16_t PWM_setDuty(PWM_Handle handle, uint32_t duty);

extern int_fast16_t PWM_setPeriod(PWM_Handle handle, uint32_t period);

extern int_fast16_t PWM_setDutyAndPeriod(PWM_Handle handle, uint32_t duty, uint32_t period);

extern void PWM_start(PWM_Handle handle);

extern void PWM_stop(PWM_Handle handle);

#ifdef __cplusplus
}
#endif
#endif /* ti_drivers_PWM__include */