pwmout_api.h

00001 
00002 /** \addtogroup hal */
00003 /** @{*/
00004 /* mbed Microcontroller Library
00005  * Copyright (c) 2006-2013 ARM Limited
00006  * SPDX-License-Identifier: Apache-2.0
00007  *
00008  * Licensed under the Apache License, Version 2.0 (the "License");
00009  * you may not use this file except in compliance with the License.
00010  * You may obtain a copy of the License at
00011  *
00012  *     http://www.apache.org/licenses/LICENSE-2.0
00013  *
00014  * Unless required by applicable law or agreed to in writing, software
00015  * distributed under the License is distributed on an "AS IS" BASIS,
00016  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00017  * See the License for the specific language governing permissions and
00018  * limitations under the License.
00019  */
00020 #ifndef MBED_PWMOUT_API_H
00021 #define MBED_PWMOUT_API_H
00022 
00023 #include "device.h"
00024 #include "pinmap.h"
00025 
00026 #if DEVICE_PWMOUT
00027 
00028 #ifdef __cplusplus
00029 extern "C" {
00030 #endif
00031 
00032 /** Pwmout hal structure. pwmout_s is declared in the target's hal
00033  */
00034 typedef struct pwmout_s pwmout_t;
00035 
00036 /**
00037  * \defgroup hal_pwmout Pwmout hal functions
00038  *
00039  * # Defined behavior
00040  * * ::pwmout_init initializes the pwmout_t control structure
00041  * * ::pwmout_free deinitializes the pwmout object
00042  * * ::pwmout_write sets the output duty-cycle in range <0.0f, 1.0f>
00043  * * ::pwmout_read returns the current float-point output duty-cycle in range <0.0f, 1.0f>
00044  * * ::pwmout_period sets the PWM period specified in seconds, keeping the duty cycle the same
00045  * * ::pwmout_period_ms sets the PWM period specified in miliseconds, keeping the duty cycle the same
00046  * * ::pwmout_period_us sets the PWM period specified in microseconds, keeping the duty cycle the same
00047  * * ::pwmout_pulsewidth sets the PWM pulsewidth specified in seconds, keeping the period the same
00048  * * ::pwmout_pulsewidth_ms sets the PWM pulsewidth specified in miliseconds, keeping the period the same
00049  * * ::pwmout_pulsewidth_us sets the PWM pulsewidth specified in microseconds, keeping the period the same
00050  * * The accuracy of the PWM is +/- 10%
00051  * * The PWM operations ::pwmout_write, ::pwmout_read, ::pwmout_read, ::pwmout_period_ms, ::pwmout_period_us
00052  *   ::pwmout_pulsewidth, ::pwmout_pulsewidth_ms, ::pwmout_pulsewidth_us take less than 20us to complete
00053  *
00054  * # Undefined behavior
00055  * * Calling other function before ::pwmout_init
00056  * * Calling ::pwmout_init with NC as pwmout pin
00057  *
00058  * @{
00059  */
00060 
00061 /**
00062  * \defgroup hal_pwmout_tests GPIO IRQ HAL tests
00063  * The Pwmout HAL tests ensure driver conformance to defined behaviour.
00064  *
00065  * To run the Pwmout hal tests use the command:
00066  *
00067  *     mbed test -t <toolchain> -m <target> -n tests-mbed_hal_fpga_ci_test_shield-pwm
00068  *
00069  */
00070 
00071 /** Initialize the pwm out peripheral and configure the pin
00072  *
00073  * @param obj The pwmout object to initialize
00074  * @param pinmap pointer to structure which holds static pinmap
00075  */
00076 void pwmout_init_direct(pwmout_t *obj, const PinMap *pinmap);
00077 
00078 /** Initialize the pwm out peripheral and configure the pin
00079  *
00080  * @param obj The pwmout object to initialize
00081  * @param pin The pwmout pin to initialize
00082  */
00083 void pwmout_init(pwmout_t *obj, PinName pin);
00084 
00085 /** Deinitialize the pwmout object
00086  *
00087  * @param obj The pwmout object
00088  */
00089 void pwmout_free(pwmout_t *obj);
00090 
00091 /** Set the output duty-cycle in range <0.0f, 1.0f>
00092  *
00093  * Value 0.0f represents 0 percentage, 1.0f represents 100 percent.
00094  * @param obj     The pwmout object
00095  * @param percent The floating-point percentage number
00096  */
00097 void pwmout_write(pwmout_t *obj, float percent);
00098 
00099 /** Read the current float-point output duty-cycle
00100  *
00101  * @param obj The pwmout object
00102  * @return A floating-point output duty-cycle
00103  */
00104 float pwmout_read(pwmout_t *obj);
00105 
00106 /** Set the PWM period specified in seconds, keeping the duty cycle the same
00107  *
00108  * Periods smaller than microseconds (the lowest resolution) are set to zero.
00109  * @param obj     The pwmout object
00110  * @param seconds The floating-point seconds period
00111  */
00112 void pwmout_period(pwmout_t *obj, float seconds);
00113 
00114 /** Set the PWM period specified in miliseconds, keeping the duty cycle the same
00115  *
00116  * @param obj The pwmout object
00117  * @param ms  The milisecond period
00118  */
00119 void pwmout_period_ms(pwmout_t *obj, int ms);
00120 
00121 /** Set the PWM period specified in microseconds, keeping the duty cycle the same
00122  *
00123  * @param obj The pwmout object
00124  * @param us  The microsecond period
00125  */
00126 void pwmout_period_us(pwmout_t *obj, int us);
00127 
00128 /** Set the PWM pulsewidth specified in seconds, keeping the period the same.
00129  *
00130  * @param obj     The pwmout object
00131  * @param seconds The floating-point pulsewidth in seconds
00132  */
00133 void pwmout_pulsewidth(pwmout_t *obj, float seconds);
00134 
00135 /** Set the PWM pulsewidth specified in miliseconds, keeping the period the same.
00136  *
00137  * @param obj The pwmout object
00138  * @param ms  The floating-point pulsewidth in miliseconds
00139  */
00140 void pwmout_pulsewidth_ms(pwmout_t *obj, int ms);
00141 
00142 /** Set the PWM pulsewidth specified in microseconds, keeping the period the same.
00143  *
00144  * @param obj The pwmout object
00145  * @param us  The floating-point pulsewidth in microseconds
00146  */
00147 void pwmout_pulsewidth_us(pwmout_t *obj, int us);
00148 
00149 /** Get the pins that support PWM
00150  *
00151  * Return a PinMap array of pins that support PWM.
00152  * The array is terminated with {NC, NC, 0}.
00153  *
00154  * @return PinMap array
00155  */
00156 const PinMap *pwmout_pinmap(void);
00157 
00158 /**@}*/
00159 
00160 #ifdef __cplusplus
00161 }
00162 #endif
00163 
00164 #endif
00165 
00166 #endif
00167 
00168 /** @}*/