/**
 * \addtogroup Pwm
 * @{
 */

/*****************************************************************************/
/**
 * \file Pwm.h
 * Pulse width modulation code for the T89C51AC2 and Keil C51.
 * \author Copyright (c) 2005, Murray R. Van Luyn. <vanluynm@iinet.net.au>
 * \version 0.0
 * \date 07-10-05
 */
/*****************************************************************************/

/*****************************************************************************
 *
 *     THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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.
 *
 *****************************************************************************/

#ifndef PWM_H
#define PWM_H

#include "t89c51ac2.h"

/*****************************************************************************
 *
 *                                    Macros
 *
 *****************************************************************************/

/** 
 * PWM duty cycle percentage representation to unsigned char representation
 * macro. Conversion is approximate i.e. attempts to set 0% duty cycle result
 * in 100% output due to lack of precision errors in integer arithmetic.
 * \param duty_cycle Expressed as an \b unsigned \b char or \b unsigned 
 * \b integer in the range 0 to 100.
 * \return The converted duty cycle value as an \b unsigned \b char.
 * \hideinitializer
 */
#define PWM_DUTY_TO_UCHAR(duty_cycle)   \
                               ((unsigned char)(256 - 256 * duty_cycle / 100))


/*****************************************************************************
 *
 *                               Defined Constants
 *
 *****************************************************************************/
/** 
 * Hardware PWM port bit enables.
 * Uncomment \b PWM_CHANNEL_x_ENABLE where x corresponds to PWM channel to be
 * enabled. Unused channelsare available for general i/o or other hardware
 * functionality.
 */
#define PWM_CHANNEL_x_ENABLE    // DO NOT ADJUST - for documentation purposes.

// THESE ARE THE DEFINES TO ADJUST.
//#define PWM_CHANNEL_0_ENABLE            // PWM output at port P1.3
#define PWM_CHANNEL_1_ENABLE            // PWM output at port P1.4
#define PWM_CHANNEL_2_ENABLE            // PWM output at port P1.5
//#define PWM_CHANNEL_3_ENABLE            // PWM output at port P1.6
//#define PWM_CHANNEL_4_ENABLE            // PWM output at port P1.7

/*
 * PWM channel defines.
 */
#define PWM_CHANNEL_0               0u
#define PWM_CHANNEL_1               1u
#define PWM_CHANNEL_2               2u
#define PWM_CHANNEL_3               3u
#define PWM_CHANNEL_4               4u


/*****************************************************************************
 *
 *                           Public Function Prototypes
 *
 *****************************************************************************/
/**
 * PWM hardware initialisation function.
 * Initialises the 8052 PCA and output ports for PWM use.
 * Must be called once to set-up hardware during program initialisation.
 * \param -
 * \return -
 */
void pwm_init(void);

/**
 * PWM channel duty cycle adjustment function.
 * \param channel An \b unsigned \b char representing the channel to set.
 * \param duty_cycle An \b unsigned \b char representation of the 
 * required duty cycle. (0x00 is 100%, 0xFF is 0%)
 * \return -
 */
void pwm_set_channel(unsigned char channel, unsigned char duty_cycle);

#endif

/** @} */