|
HALFRED
0.4.0
|
Introduction.
This module provides an interface for handling general purpose input/output pins. It provides an interface for changing pin direction settings, reading pin state and controlling the output state.
Pin identification.
On the application level, every pin is identified only by it's name. Typical name examples would be: MEM_CS, LCD_RESET, PWR_SHUTDOWN etc. The pin is assumed to belong to an i/o port (i/o bank), as this is the most common case in general purpose microcontrollers.
The actual pin identifier is created by adding "_PIN" suffix to the pin name. For the above examples, the actual pin identifiers would be MEM_CS_PIN, LCD_RESET_PIN, PWR_SHUTDOWN_PIN etc. Similarly, port identifiers comes form pin name and "_PORT" suffix, for example: MEM_CS_PORT, LCD_RESET_PORT, PWR_SUTDOWN_PORT etc. HAL does not typecast the pin and port identifiers, as all the GPIO handling is done by macros. This means that for example MEM_CS_PIN and MEM_CS_PORT can represent any type of data. Most often pins would be represented as integers (either pin number or bitmask) but ports may be represented as integers or pointers to internal register banks in the address space of the microcontroller.
Pin configuration.
Any pin can be configured to serve several purposes. It may be configured as input, then as push-pull output or open drain etc. Pin reconfiguration can be done dynamically at runtime, so the GPIO module must provide a way to identify the configurations. In the context of GPIO module, pin configurations also have names. Typical would be: OUTPUT_PP, OUTPUT_OD, INPUT_PU, but the name can also be strongly coupled with the application. TODO: decide whether or not define standard configuration names The actual configuration identifier is created by adding name of configuration as a suffix to the pin name, for example MEM_CS_OUTPUT_PP, MEM_CS_OUTPUT_OD etc. These identifier are not type-casted by HAL, so they may represent any type of data.
Pin definitions.
On the application level, pin handling comes down to using GPIO API with pin names and pin configuration names. These (along with port identifiers) must be visible during compile time. HAL expects to find them in a file called gpio_config.h. This file in most cases sits in the application folder. As discussed above, for every pin there are 3 definitions needed: pin, port and at least one configuration. Let's look at the following example of a hypothetical pin being a half-duplex serial communication line on the first pin of imaginary port A.
Such code placed in the GPIO section of hal_config.h enables the application to use pin named "SERIAL_DATA" in two configurations named "OUTPUT" and "INPUT". Additionally, a default configuration has been distinguished. The following code initializes the GPIO module, configures the pin as output and sets it to a high state.
GPIO events.
The GPIO events mechanism provides a way to handle external interrupts triggered on GPIO pins. The pins are identified using the same pin name as described above. Additional API for events consists of the following items: HAL_GPIO_EnableEvent, HAL_GPIO_DisableEvent, HAL_GPIO_SetEventHandler and HAL_GPIO_IsEventEnabled. At least one additional application definition is required to configure the source of an event.
For example, if an interrupt is needed on a SERIAL_DATA line, when it transits from high to low state the application must provide at least 3 definitions:
Such code placed in the GPIO section of hal_config.h enables the application to use pin named "SERIAL_DATA" with an event which source is set as "falling_edge_trigger" (note that this is purely port-specific definition). The following code initializes the GPIO module, configures the pin event and sets its handler.
where the handler is defined as:
Please note, that it's usually a good idea to setup the handler BEFORE the event is actually enabled.
Module configuration.
To enable the GPIO module, HAL_ENABLE_GPIO definition must be set to 1, in hal_config.h.
Macros | |
| #define | HAL_GPIO_Init() HAL_GPIO_PORT_Init() |
| #define | HAL_GPIO_Deinit() HAL_GPIO_PORT_Deinit() |
| #define | HAL_GPIO_ConfigurePin(name, config) HAL_GPIO_PORT_ConfigurePin(HAL_GPIO_GET_PORT_NAME(name), HAL_GPIO_GET_PIN_NAME(name), HAL_GPIO_GET_CONFIG_NAME(name, config)) |
| #define | HAL_GPIO_ConfigurePort(name, config) HAL_GPIO_PORT_ConfigurePort(HAL_GPIO_GET_PORT_NAME(name), HAL_GPIO_GET_PORT_MASK_NAME(name), HAL_GPIO_GET_CONFIG_NAME(name, config)) |
| #define | HAL_GPIO_GetConfig(name) HAL_GPIO_PORT_GetConfig(HAL_GPIO_GET_PORT_NAME(name), HAL_GPIO_GET_PIN_NAME(name)) |
| #define | HAL_GPIO_ReadPin(name) HAL_GPIO_PORT_ReadPin(HAL_GPIO_GET_PORT_NAME(name), HAL_GPIO_GET_PIN_NAME(name)) |
| #define | HAL_GPIO_SetPinHigh(name) HAL_GPIO_PORT_SetPinHigh(HAL_GPIO_GET_PORT_NAME(name), HAL_GPIO_GET_PIN_NAME(name)) |
| #define | HAL_GPIO_SetPinLow(name) HAL_GPIO_PORT_SetPinLow(HAL_GPIO_GET_PORT_NAME(name), HAL_GPIO_GET_PIN_NAME(name)) |
| #define | HAL_GPIO_TogglePin(name) HAL_GPIO_PORT_TogglePin(HAL_GPIO_GET_PORT_NAME(name), HAL_GPIO_GET_PIN_NAME(name)) |
| #define | HAL_GPIO_ReadPort(name) HAL_GPIO_PORT_ReadPort(HAL_GPIO_GET_PORT_NAME(name)) |
| #define | HAL_GPIO_WritePort(name, data) HAL_GPIO_PORT_WritePort(HAL_GPIO_GET_PORT_NAME(name), data) |
| #define | HAL_GPIO_SetPortHigh(name, data) HAL_GPIO_PORT_SetPortHigh(HAL_GPIO_GET_PORT_NAME(name), (data)) |
| #define | HAL_GPIO_SetPortLow(name, data) HAL_GPIO_PORT_SetPortLow(HAL_GPIO_GET_PORT_NAME(name), (data)) |
| #define | HAL_GPIO_EnableEvent(name, source) HAL_GPIO_PORT_EnableEvent(HAL_GPIO_GET_PORT_NAME(name), HAL_GPIO_GET_PIN_NAME(name), (source)) |
| #define | HAL_GPIO_DisableEvent(name) HAL_GPIO_PORT_DisableEvent(HAL_GPIO_GET_PORT_NAME(name), HAL_GPIO_GET_PIN_NAME(name)) |
| #define | HAL_GPIO_SetEventHandler(name, handler) HAL_GPIO_PORT_SetEventHandler(HAL_GPIO_GET_PORT_NAME(name), HAL_GPIO_GET_PIN_NAME(name), (handler)) |
| #define | HAL_GPIO_IsEventEnabled(name) HAL_GPIO_PORT_IsEventEnabled(HAL_GPIO_GET_PORT_NAME(name), HAL_GPIO_GET_PIN_NAME(name)) |
| #define | HAL_GPIO_SaveConfiguration() HAL_GPIO_PORT_SaveConfiguration() |
| #define | HAL_GPIO_RestoreConfiguration() HAL_GPIO_PORT_RestoreConfiguration() |
| #define HAL_GPIO_Init | ( | ) | HAL_GPIO_PORT_Init() |
Initializes the GPIO module. Must be called before any other GPIO functions. The functionality of this procedure is system dependent. This API call is provided to satisfy special requirements, such as initial state configuration of all pins etc.
| #define HAL_GPIO_Deinit | ( | ) | HAL_GPIO_PORT_Deinit() |
Deinitializes the GPIO module. The functionality of this procedure is system dependent.
| #define HAL_GPIO_ConfigurePin | ( | name, | |
| config | |||
| ) | HAL_GPIO_PORT_ConfigurePin(HAL_GPIO_GET_PORT_NAME(name), HAL_GPIO_GET_PIN_NAME(name), HAL_GPIO_GET_CONFIG_NAME(name, config)) |
Sets up pin to the specified configuration.
| name | name of the pin |
| config | name of the configuration |
| #define HAL_GPIO_ConfigurePort | ( | name, | |
| config | |||
| ) | HAL_GPIO_PORT_ConfigurePort(HAL_GPIO_GET_PORT_NAME(name), HAL_GPIO_GET_PORT_MASK_NAME(name), HAL_GPIO_GET_CONFIG_NAME(name, config)) |
Sets up group of pins associated with specified port to the specified configuration.
| name | name of the pins group |
| config | name of the configuration |
| #define HAL_GPIO_GetConfig | ( | name | ) | HAL_GPIO_PORT_GetConfig(HAL_GPIO_GET_PORT_NAME(name), HAL_GPIO_GET_PIN_NAME(name)) |
Returns the current pin configuration.
| name | name of the pin |
| #define HAL_GPIO_ReadPin | ( | name | ) | HAL_GPIO_PORT_ReadPin(HAL_GPIO_GET_PORT_NAME(name), HAL_GPIO_GET_PIN_NAME(name)) |
Reads pin state, if the pin is configured as input or the hardware allows to read the state of an output pin. Otherwise the result of this macro is undefined.
| name | name of the pin |
| #define HAL_GPIO_SetPinHigh | ( | name | ) | HAL_GPIO_PORT_SetPinHigh(HAL_GPIO_GET_PORT_NAME(name), HAL_GPIO_GET_PIN_NAME(name)) |
Set the state of the output pin to high voltage state (logic 1). If the pin is not configured as output this function does nothing.
| name | name of the output pin |
| #define HAL_GPIO_SetPinLow | ( | name | ) | HAL_GPIO_PORT_SetPinLow(HAL_GPIO_GET_PORT_NAME(name), HAL_GPIO_GET_PIN_NAME(name)) |
Set the state of the output pin to low voltage state (logic 0). If the pin is not configured as output this function does nothing.
| name | name of the output pin |
| #define HAL_GPIO_TogglePin | ( | name | ) | HAL_GPIO_PORT_TogglePin(HAL_GPIO_GET_PORT_NAME(name), HAL_GPIO_GET_PIN_NAME(name)) |
Changes the state of the output pin to the oposite one. If the pin is not configured as output this function does nothing.
| name | name of the output pin |
| #define HAL_GPIO_ReadPort | ( | name | ) | HAL_GPIO_PORT_ReadPort(HAL_GPIO_GET_PORT_NAME(name)) |
Reads port state, if the port is configured as input or the hardware allows to read the state of an output port. Otherwise the result of this macro is undefined. This macro reads whole port data (each bit), so if some bits are not used or configured as outputs it is recommended to use some mask to clear unused bits cause their values may be undefined.
| name | name of the port |
| #define HAL_GPIO_WritePort | ( | name, | |
| data | |||
| ) | HAL_GPIO_PORT_WritePort(HAL_GPIO_GET_PORT_NAME(name), data) |
Writes data to the output port. If the port is not configured as output this function does nothing. This macro writes data to whole port (each bit), so if some bits of port are used as other group of pins it is necessary to read port, modify requested bits and then write new value to the port
| name | name of the output port |
| data | uint32_t type data to be written to port |
| #define HAL_GPIO_SetPortHigh | ( | name, | |
| data | |||
| ) | HAL_GPIO_PORT_SetPortHigh(HAL_GPIO_GET_PORT_NAME(name), (data)) |
Set the state of the group of pins of port to high voltage state (logic 1). If the pins are not configured as output this function does nothing.
| name | name of the output pins group |
| data | mask with bits to be set high |
| #define HAL_GPIO_SetPortLow | ( | name, | |
| data | |||
| ) | HAL_GPIO_PORT_SetPortLow(HAL_GPIO_GET_PORT_NAME(name), (data)) |
Set the state of the group of pins of port to low voltage state (logic 0). If the pins are not configured as output this function does nothing.
| name | name of the output pins group |
| data | mask with bits to be set low |
| #define HAL_GPIO_EnableEvent | ( | name, | |
| source | |||
| ) | HAL_GPIO_PORT_EnableEvent(HAL_GPIO_GET_PORT_NAME(name), HAL_GPIO_GET_PIN_NAME(name), (source)) |
Configures and enables an event on the specified pin. Pin have to be configured before calling HAL_GPIO_EnableEvent
| name | name of the pin |
| source | of the event |
| #define HAL_GPIO_DisableEvent | ( | name | ) | HAL_GPIO_PORT_DisableEvent(HAL_GPIO_GET_PORT_NAME(name), HAL_GPIO_GET_PIN_NAME(name)) |
Disables an event on the specified pin.
| name | name of the pin |
| #define HAL_GPIO_SetEventHandler | ( | name, | |
| handler | |||
| ) | HAL_GPIO_PORT_SetEventHandler(HAL_GPIO_GET_PORT_NAME(name), HAL_GPIO_GET_PIN_NAME(name), (handler)) |
Associates an event handler func to be called when an event is triggered on the specified pin.
| name | name of the pin |
| handler | event handler function. This function does not have any parameters and returns nothing, in ex.: void MyHandler(void) |
| #define HAL_GPIO_IsEventEnabled | ( | name | ) | HAL_GPIO_PORT_IsEventEnabled(HAL_GPIO_GET_PORT_NAME(name), HAL_GPIO_GET_PIN_NAME(name)) |
Checks, if an event on the specified pin is enabled.
| name | name of the pin |
1.8.7