Keil Studio Cloud
Mistake on this page?
Report an issue in GitHub or email us
gpio_api.h
1 
2 /** \addtogroup hal */
3 /** @{*/
4 /* mbed Microcontroller Library
5  * Copyright (c) 2006-2020 ARM Limited
6  * SPDX-License-Identifier: Apache-2.0
7  *
8  * Licensed under the Apache License, Version 2.0 (the "License");
9  * you may not use this file except in compliance with the License.
10  * You may obtain a copy of the License at
11  *
12  * http://www.apache.org/licenses/LICENSE-2.0
13  *
14  * Unless required by applicable law or agreed to in writing, software
15  * distributed under the License is distributed on an "AS IS" BASIS,
16  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17  * See the License for the specific language governing permissions and
18  * limitations under the License.
19  */
20 #ifndef MBED_GPIO_API_H
21 #define MBED_GPIO_API_H
22 
23 #include <stdint.h>
24 #include "device.h"
25 #include "pinmap.h"
26 
27 #ifdef __cplusplus
28 extern "C" {
29 #endif
30 
31 /**
32  * \defgroup hal_gpio GPIO HAL functions
33  *
34  * # Defined behavior
35  * * ::gpio_init and other init functions can be called with NC or a valid PinName for the target - Verified by ::gpio_nc_test
36  * * ::gpio_is_connected can be used to test whether a gpio_t object was initialized with NC - Verified by ::gpio_nc_test
37  * * ::gpio_init initializes the GPIO pin
38  * * ::gpio_free returns the pin owned by the GPIO object to its reset state
39  * * ::gpio_mode sets the mode of the given pin
40  * * ::gpio_dir sets the direction of the given pin
41  * * ::gpio_write sets the gpio output value
42  * * ::gpio_read reads the input value
43  * * ::gpio_init_in inits the input pin and sets mode to PullDefault
44  * * ::gpio_init_in_ex inits the input pin and sets the mode
45  * * ::gpio_init_out inits the pin as an output, with predefined output value 0
46  * * ::gpio_init_out_ex inits the pin as an output and sets the output value
47  * * ::gpio_init_inout inits the pin to be input/output and set pin mode and value
48  * * The GPIO operations ::gpio_write, ::gpio_read take less than 20us to complete
49  * * The function ::gpio_get_capabilities fills the given
50  * `gpio_capabilities_t` instance according to pin capabilities.
51  *
52  * # Undefined behavior
53  * * Calling any ::gpio_mode, ::gpio_dir, ::gpio_write or ::gpio_read on a gpio_t object that was initialized
54  * with NC.
55  * * Calling ::gpio_set with NC.
56  *
57  * @{
58  */
59 
60 /**
61  * \defgroup hal_gpio_tests GPIO HAL tests
62  * The GPIO HAL tests ensure driver conformance to defined behaviour.
63  *
64  * To run the GPIO hal tests use the command:
65  *
66  * mbed test -t <toolchain> -m <target> -n tests-mbed_hal_fpga_ci_test_shield-gpio,tests-mbed_hal-gpio
67  *
68  */
69 
70 /** GPIO capabilities for a given pin
71  */
72 typedef struct {
73  uint8_t pull_none : 1;
74  uint8_t pull_down : 1;
75  uint8_t pull_up : 1;
76 } gpio_capabilities_t;
77 
78 /** Set the given pin as GPIO
79  *
80  * @param pin The pin to be set as GPIO
81  * @return The GPIO port mask for this pin
82  **/
83 uint32_t gpio_set(PinName pin);
84 
85 /** Checks if gpio object is connected (pin was not initialized with NC)
86  * @param obj The GPIO object
87  * @return 0 if object was initialized with NC
88  * @return non-zero if object was initialized with a valid PinName
89  **/
90 int gpio_is_connected(const gpio_t *obj);
91 
92 /** Initialize the GPIO pin
93  *
94  * @param obj The GPIO object to initialize
95  * @param pin The GPIO pin to initialize (may be NC)
96  */
97 void gpio_init(gpio_t *obj, PinName pin);
98 
99 /** Releases the GPIO pin
100  *
101  * @param obj The GPIO object to release
102  */
103 void gpio_free(gpio_t *obj);
104 
105 /** Set the input pin mode
106  *
107  * @param obj The GPIO object (must be connected)
108  * @param mode The pin mode to be set
109  */
110 void gpio_mode(gpio_t *obj, PinMode mode);
111 
112 /** Set the pin direction
113  *
114  * @param obj The GPIO object (must be connected)
115  * @param direction The pin direction to be set
116  */
117 void gpio_dir(gpio_t *obj, PinDirection direction);
118 
119 /** Set the output value
120  *
121  * @param obj The GPIO object (must be connected)
122  * @param value The value to be set
123  */
124 void gpio_write(gpio_t *obj, int value);
125 
126 /** Read the input value
127  *
128  * @param obj The GPIO object (must be connected)
129  * @return An integer value 1 or 0
130  */
131 int gpio_read(gpio_t *obj);
132 
133 // the following functions are generic and implemented in the common gpio.c file
134 // TODO: fix, will be moved to the common gpio header file
135 
136 /** Init the input pin and set mode to PullDefault
137  *
138  * @param gpio The GPIO object
139  * @param pin The pin name (may be NC)
140  */
141 void gpio_init_in(gpio_t *gpio, PinName pin);
142 
143 /** Init the input pin and set the mode
144  *
145  * @param gpio The GPIO object
146  * @param pin The pin name (may be NC)
147  * @param mode The pin mode to be set
148  */
149 void gpio_init_in_ex(gpio_t *gpio, PinName pin, PinMode mode);
150 
151 /** Init the output pin as an output, with predefined output value 0
152  *
153  * @param gpio The GPIO object
154  * @param pin The pin name (may be NC)
155  * @return An integer value 1 or 0
156  */
157 void gpio_init_out(gpio_t *gpio, PinName pin);
158 
159 /** Init the pin as an output and set the output value
160  *
161  * @param gpio The GPIO object
162  * @param pin The pin name (may be NC)
163  * @param value The value to be set
164  */
165 void gpio_init_out_ex(gpio_t *gpio, PinName pin, int value);
166 
167 /** Init the pin to be in/out
168  *
169  * @param gpio The GPIO object
170  * @param pin The pin name (may be NC)
171  * @param direction The pin direction to be set
172  * @param mode The pin mode to be set
173  * @param value The value to be set for an output pin
174  */
175 void gpio_init_inout(gpio_t *gpio, PinName pin, PinDirection direction, PinMode mode, int value);
176 
177 /** Fill the given gpio_capabilities_t instance according to pin capabilities.
178  */
179 void gpio_get_capabilities(gpio_t *gpio, gpio_capabilities_t *cap);
180 
181 /** Get the pins that support all GPIO tests
182  *
183  * Return a PinMap array of pins that support GPIO. The
184  * array is terminated with {NC, NC, 0}.
185  *
186  * Targets should override the weak implementation of this
187  * function to provide the actual pinmap for GPIO testing.
188  *
189  * @return PinMap array
190  */
191 const PinMap *gpio_pinmap(void);
192 
193 /**@}*/
194 
195 #ifdef __cplusplus
196 }
197 #endif
198 
199 #endif
200 
201 /** @}*/
gpio_init_inout
void gpio_init_inout(gpio_t *gpio, PinName pin, PinDirection direction, PinMode mode, int value)
Init the pin to be in/out.
gpio_pinmap
const PinMap * gpio_pinmap(void)
Get the pins that support all GPIO tests.
gpio_init
void gpio_init(gpio_t *obj, PinName pin)
Initialize the GPIO pin.
gpio_get_capabilities
void gpio_get_capabilities(gpio_t *gpio, gpio_capabilities_t *cap)
Fill the given gpio_capabilities_t instance according to pin capabilities.
gpio_is_connected
int gpio_is_connected(const gpio_t *obj)
Checks if gpio object is connected (pin was not initialized with NC)
gpio_write
void gpio_write(gpio_t *obj, int value)
Set the output value.
gpio_read
int gpio_read(gpio_t *obj)
Read the input value.
gpio_capabilities_t
GPIO capabilities for a given pin.
Definition: gpio_api.h:72
gpio_dir
void gpio_dir(gpio_t *obj, PinDirection direction)
Set the pin direction.
gpio_set
uint32_t gpio_set(PinName pin)
Set the given pin as GPIO.
PinMap
Definition: pinmap.h:31
gpio_init_out
void gpio_init_out(gpio_t *gpio, PinName pin)
Init the output pin as an output, with predefined output value 0.
gpio_mode
void gpio_mode(gpio_t *obj, PinMode mode)
Set the input pin mode.
gpio_init_out_ex
void gpio_init_out_ex(gpio_t *gpio, PinName pin, int value)
Init the pin as an output and set the output value.
gpio_init_in
void gpio_init_in(gpio_t *gpio, PinName pin)
Init the input pin and set mode to PullDefault.
gpio_free
void gpio_free(gpio_t *obj)
Releases the GPIO pin.
gpio_init_in_ex
void gpio_init_in_ex(gpio_t *gpio, PinName pin, PinMode mode)
Init the input pin and set the mode.
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.