Intel® Quark™ Microcontroller Software Interface  1.4.0
Intel® Quark™ Microcontroller BSP
qm_gpio.h
1 /*
2  * {% copyright %}
3  */
4 
5 #ifndef __QM_GPIO_H__
6 #define __QM_GPIO_H__
7 
8 #include "qm_common.h"
9 #include "qm_soc_regs.h"
10 
11 /**
12  * General Purpose IO.
13  *
14  * @defgroup groupGPIO GPIO
15  * @{
16  */
17 
18 /**
19  * GPIO pin states.
20  */
21 typedef enum {
22  QM_GPIO_LOW = 0, /**< GPIO low state. */
23  QM_GPIO_HIGH, /**< GPIO high state. */
24  QM_GPIO_STATE_NUM /**< Number of GPIO states. */
26 
27 /**
28  * GPIO port configuration type.
29  *
30  * Each bit in the registers control a GPIO pin.
31  */
32 typedef struct {
33  uint32_t direction; /**< GPIO direction, 0b: input, 1b: output. */
34  uint32_t int_en; /**< Interrupt enable. */
35  uint32_t int_type; /**< Interrupt type, 0b: level; 1b: edge. */
36  uint32_t int_polarity; /**< Interrupt polarity, 0b: low, 1b: high. */
37  uint32_t int_debounce; /**< Interrupt debounce on/off. */
38  uint32_t int_bothedge; /**< Interrupt on rising and falling edges. */
39 
40  /**
41  * Transfer callback.
42  *
43  * @param[in] data Callback user data.
44  * @param[in] int_status GPIO interrupt status.
45  */
46  void (*callback)(void *data, uint32_t int_status);
47  void *callback_data; /**< Callback user data. */
49 
50 /**
51  * Set GPIO port configuration.
52  *
53  * This includes if interrupts are enabled or not, the level on which an
54  * interrupt is generated, the polarity of interrupts and if GPIO-debounce is
55  * enabled or not. If interrupts are enabled it also registers the user defined
56  * callback function.
57  *
58  * @param[in] gpio GPIO port index to configure.
59  * @param[in] cfg New configuration for GPIO port. This must not be NULL.
60  *
61  * @return Standard errno return type for QMSI.
62  * @retval 0 on success.
63  * @retval Negative @ref errno for possible error codes.
64  *
65  */
66 int qm_gpio_set_config(const qm_gpio_t gpio,
67  const qm_gpio_port_config_t *const cfg);
68 
69 /**
70  * Read the current state of a single pin on a given GPIO port.
71  *
72  * @param[in] gpio GPIO port index.
73  * @param[in] pin Pin of GPIO port to read.
74  * @param[out] state Current state of the pin. This must not be NULL.
75  *
76  * @return Standard errno return type for QMSI.
77  * @retval 0 on success.
78  * @retval Negative @ref errno for possible error codes.
79  */
80 int qm_gpio_read_pin(const qm_gpio_t gpio, const uint8_t pin,
81  qm_gpio_state_t *const state);
82 
83 /**
84  * Set a single pin on a given GPIO port.
85  *
86  * @param[in] gpio GPIO port index.
87  * @param[in] pin Pin of GPIO port to set.
88  *
89  * @return Standard errno return type for QMSI.
90  * @retval 0 on success.
91  * @retval Negative @ref errno for possible error codes.
92  */
93 int qm_gpio_set_pin(const qm_gpio_t gpio, const uint8_t pin);
94 
95 /**
96  * Clear a single pin on a given GPIO port.
97  *
98  * @param[in] gpio GPIO port index.
99  * @param[in] pin Pin of GPIO port to clear.
100  *
101  * @return int 0 on success, error code otherwise.
102  * @retval 0 on success.
103  * @retval Negative @ref errno for possible error codes.
104  */
105 int qm_gpio_clear_pin(const qm_gpio_t gpio, const uint8_t pin);
106 
107 /**
108  * Set or clear a single GPIO pin using a state variable.
109  *
110  * @param[in] gpio GPIO port index.
111  * @param[in] pin Pin of GPIO port to update.
112  * @param[in] state QM_GPIO_LOW for low or QM_GPIO_HIGH for high.
113  *
114  * @return Standard errno return type for QMSI.
115  * @retval 0 on success.
116  * @retval Negative @ref errno for possible error codes.
117  */
118 int qm_gpio_set_pin_state(const qm_gpio_t gpio, const uint8_t pin,
119  const qm_gpio_state_t state);
120 
121 /**
122  * Read the value of every pin on a GPIO port.
123  *
124  * Each bit of the val parameter is set to the current value of each pin on the
125  * port. Maximum 32 pins per port.
126  *
127  * @param[in] gpio GPIO port index.
128  * @param[out] port State of every pin in a GPIO port. This must not be NULL.
129  *
130  * @return Standard errno return type for QMSI.
131  * @retval 0 on success.
132  * @retval Negative @ref errno for possible error codes.
133  */
134 int qm_gpio_read_port(const qm_gpio_t gpio, uint32_t *const port);
135 
136 /**
137  * Write a value to every pin on a GPIO port.
138  *
139  * Each pin on the GPIO port is set to the corresponding value set in the val
140  * parameter. Maximum 32 pins per port.
141  *
142  * @param[in] gpio GPIO port index.
143  * @param[in] val Value of all pins on GPIO port.
144  *
145  * @return Standard errno return type for QMSI.
146  * @retval 0 on success.
147  * @retval Negative @ref errno for possible error codes.
148  */
149 int qm_gpio_write_port(const qm_gpio_t gpio, const uint32_t val);
150 
151 /**
152  * Save GPIO context.
153  *
154  * Save the configuration of the specified GPIO peripheral
155  * before entering sleep.
156  *
157  * @param[in] gpio GPIO port index.
158  * @param[out] ctx GPIO context structure. This must not be NULL.
159  *
160  * @return Standard errno return type for QMSI.
161  * @retval 0 on success.
162  * @retval Negative @ref errno for possible error codes.
163  */
164 int qm_gpio_save_context(const qm_gpio_t gpio, qm_gpio_context_t *const ctx);
165 
166 /**
167  * Restore GPIO context.
168  *
169  * Restore the configuration of the specified GPIO peripheral
170  * after exiting sleep.
171  *
172  * @param[in] gpio GPIO port index.
173  * @param[in] ctx GPIO context structure. This must not be NULL.
174  *
175  * @return Standard errno return type for QMSI.
176  * @retval 0 on success.
177  * @retval Negative @ref errno for possible error codes.
178  */
179 int qm_gpio_restore_context(const qm_gpio_t gpio,
180  const qm_gpio_context_t *const ctx);
181 /**
182  * @}
183  */
184 
185 #endif /* __QM_GPIO_H__ */
int qm_gpio_clear_pin(const qm_gpio_t gpio, const uint8_t pin)
Clear a single pin on a given GPIO port.
Definition: qm_gpio.c:107
uint32_t int_polarity
Interrupt polarity, 0b: low, 1b: high.
Definition: qm_gpio.h:36
uint32_t direction
GPIO direction, 0b: input, 1b: output.
Definition: qm_gpio.h:33
int qm_gpio_read_pin(const qm_gpio_t gpio, const uint8_t pin, qm_gpio_state_t *const state)
Read the current state of a single pin on a given GPIO port.
Definition: qm_gpio.c:85
int qm_gpio_set_pin(const qm_gpio_t gpio, const uint8_t pin)
Set a single pin on a given GPIO port.
Definition: qm_gpio.c:97
int qm_gpio_write_port(const qm_gpio_t gpio, const uint32_t val)
Write a value to every pin on a GPIO port.
Definition: qm_gpio.c:141
uint32_t int_debounce
Interrupt debounce on/off.
Definition: qm_gpio.h:37
uint32_t int_type
Interrupt type, 0b: level; 1b: edge.
Definition: qm_gpio.h:35
GPIO high state.
Definition: qm_gpio.h:23
uint32_t int_bothedge
Interrupt on rising and falling edges.
Definition: qm_gpio.h:38
int qm_gpio_save_context(const qm_gpio_t gpio, qm_gpio_context_t *const ctx)
Save GPIO context.
Definition: qm_gpio.c:151
GPIO low state.
Definition: qm_gpio.h:22
Number of GPIO states.
Definition: qm_gpio.h:24
int qm_gpio_set_pin_state(const qm_gpio_t gpio, const uint8_t pin, const qm_gpio_state_t state)
Set or clear a single GPIO pin using a state variable.
Definition: qm_gpio.c:117
uint32_t int_en
Interrupt enable.
Definition: qm_gpio.h:34
qm_gpio_state_t
GPIO pin states.
Definition: qm_gpio.h:21
GPIO context type.
Definition: qm_soc_regs.h:1399
qm_gpio_t
Number of GPIO controllers.
Definition: qm_soc_regs.h:1014
int qm_gpio_read_port(const qm_gpio_t gpio, uint32_t *const port)
Read the value of every pin on a GPIO port.
Definition: qm_gpio.c:131
int qm_gpio_restore_context(const qm_gpio_t gpio, const qm_gpio_context_t *const ctx)
Restore GPIO context.
Definition: qm_gpio.c:174
void * callback_data
Callback user data.
Definition: qm_gpio.h:47
GPIO port configuration type.
Definition: qm_gpio.h:32
int qm_gpio_set_config(const qm_gpio_t gpio, const qm_gpio_port_config_t *const cfg)
Set GPIO port configuration.
Definition: qm_gpio.c:59