gpio_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_GPIO_API_H
00021 #define MBED_GPIO_API_H
00022 
00023 #include <stdint.h>
00024 #include "device.h"
00025 #include "pinmap.h"
00026 
00027 #ifdef __cplusplus
00028 extern "C" {
00029 #endif
00030 
00031 /**
00032  * \defgroup hal_gpio GPIO HAL functions
00033  *
00034  * # Defined behavior
00035  * * ::gpio_init and other init functions can be called with NC or a valid PinName for the target - Verified by ::gpio_nc_test
00036  * * ::gpio_is_connected can be used to test whether a gpio_t object was initialized with NC - Verified by ::gpio_nc_test
00037  * * ::gpio_init initializes the GPIO pin
00038  * * ::gpio_free returns the pin owned by the GPIO object to its reset state
00039  * * ::gpio_mode sets the mode of the given pin
00040  * * ::gpio_dir sets the direction of the given pin
00041  * * ::gpio_write sets the gpio output value
00042  * * ::gpio_read reads the input value
00043  * * ::gpio_init_in inits the input pin and sets mode to PullDefault
00044  * * ::gpio_init_in_ex inits the input pin and sets the mode
00045  * * ::gpio_init_out inits the pin as an output, with predefined output value 0
00046  * * ::gpio_init_out_ex inits the pin as an output and sets the output value
00047  * * ::gpio_init_inout inits the pin to be input/output and set pin mode and value
00048  * * The GPIO operations ::gpio_write, ::gpio_read take less than 20us to complete
00049  *
00050  * # Undefined behavior
00051  * * Calling any ::gpio_mode, ::gpio_dir, ::gpio_write or ::gpio_read on a gpio_t object that was initialized
00052  *   with NC.
00053  * * Calling ::gpio_set with NC.
00054  *
00055  * @{
00056  */
00057 
00058 /**
00059  * \defgroup hal_gpio_tests GPIO HAL tests
00060  * The GPIO HAL tests ensure driver conformance to defined behaviour.
00061  *
00062  * To run the GPIO hal tests use the command:
00063  *
00064  *     mbed test -t <toolchain> -m <target> -n tests-mbed_hal_fpga_ci_test_shield-gpio,tests-mbed_hal-gpio
00065  *
00066  */
00067 
00068 /** Set the given pin as GPIO
00069  *
00070  * @param pin The pin to be set as GPIO
00071  * @return The GPIO port mask for this pin
00072  **/
00073 uint32_t gpio_set(PinName pin);
00074 
00075 /** Checks if gpio object is connected (pin was not initialized with NC)
00076  * @param obj The GPIO object
00077  * @return 0 if object was initialized with NC
00078  * @return non-zero if object was initialized with a valid PinName
00079  **/
00080 int gpio_is_connected(const gpio_t *obj);
00081 
00082 /** Initialize the GPIO pin
00083  *
00084  * @param obj The GPIO object to initialize
00085  * @param pin The GPIO pin to initialize (may be NC)
00086  */
00087 void gpio_init(gpio_t *obj, PinName pin);
00088 
00089 /** Releases the GPIO pin
00090  *
00091  * @param obj The GPIO object to release
00092  */
00093 void gpio_free(gpio_t *obj);
00094 
00095 /** Set the input pin mode
00096  *
00097  * @param obj  The GPIO object (must be connected)
00098  * @param mode The pin mode to be set
00099  */
00100 void gpio_mode(gpio_t *obj, PinMode mode);
00101 
00102 /** Set the pin direction
00103  *
00104  * @param obj       The GPIO object (must be connected)
00105  * @param direction The pin direction to be set
00106  */
00107 void gpio_dir(gpio_t *obj, PinDirection direction);
00108 
00109 /** Set the output value
00110  *
00111  * @param obj   The GPIO object (must be connected)
00112  * @param value The value to be set
00113  */
00114 void gpio_write(gpio_t *obj, int value);
00115 
00116 /** Read the input value
00117  *
00118  * @param obj The GPIO object (must be connected)
00119  * @return An integer value 1 or 0
00120  */
00121 int gpio_read(gpio_t *obj);
00122 
00123 // the following functions are generic and implemented in the common gpio.c file
00124 // TODO: fix, will be moved to the common gpio header file
00125 
00126 /** Init the input pin and set mode to PullDefault
00127  *
00128  * @param gpio The GPIO object
00129  * @param pin  The pin name (may be NC)
00130  */
00131 void gpio_init_in(gpio_t *gpio, PinName pin);
00132 
00133 /** Init the input pin and set the mode
00134  *
00135  * @param gpio  The GPIO object
00136  * @param pin   The pin name (may be NC)
00137  * @param mode  The pin mode to be set
00138  */
00139 void gpio_init_in_ex(gpio_t *gpio, PinName pin, PinMode mode);
00140 
00141 /** Init the output pin as an output, with predefined output value 0
00142  *
00143  * @param gpio The GPIO object
00144  * @param pin  The pin name (may be NC)
00145  * @return     An integer value 1 or 0
00146  */
00147 void gpio_init_out(gpio_t *gpio, PinName pin);
00148 
00149 /** Init the pin as an output and set the output value
00150  *
00151  * @param gpio  The GPIO object
00152  * @param pin   The pin name (may be NC)
00153  * @param value The value to be set
00154  */
00155 void gpio_init_out_ex(gpio_t *gpio, PinName pin, int value);
00156 
00157 /** Init the pin to be in/out
00158  *
00159  * @param gpio      The GPIO object
00160  * @param pin       The pin name (may be NC)
00161  * @param direction The pin direction to be set
00162  * @param mode      The pin mode to be set
00163  * @param value     The value to be set for an output pin
00164  */
00165 void gpio_init_inout(gpio_t *gpio, PinName pin, PinDirection direction, PinMode mode, int value);
00166 
00167 /** Get the pins that support all GPIO tests
00168  *
00169  * Return a PinMap array of pins that support GPIO. The
00170  * array is terminated with {NC, NC, 0}.
00171  *
00172  * Targets should override the weak implementation of this
00173  * function to provide the actual pinmap for GPIO testing.
00174  *
00175  * @return PinMap array
00176  */
00177 const PinMap *gpio_pinmap(void);
00178 
00179 /**@}*/
00180 
00181 #ifdef __cplusplus
00182 }
00183 #endif
00184 
00185 #endif
00186 
00187 /** @}*/