0ef1717155
Some checks failed
Basic Checks / license-check (push) Has been cancelled
Basic Checks / include-check (push) Has been cancelled
Basic Checks / style-check (push) Has been cancelled
Basic Checks / docs-check (push) Has been cancelled
Basic Checks / python-tests (push) Has been cancelled
Basic Checks / pin-validation (push) Has been cancelled
Basic Checks / cmake-checks (push) Has been cancelled
Basic Checks / frozen-tools-check (push) Has been cancelled
Publish or Update docker image for head of branch / prepare-tags (push) Has been cancelled
Release or update docker image for a released mbed-os version / prepare-tags (push) Has been cancelled
Publish or Update docker image for head of branch / build-container (push) Has been cancelled
Publish or Update docker image for head of branch / test-container (linux/amd64) (push) Has been cancelled
Publish or Update docker image for head of branch / test-container (linux/arm64) (push) Has been cancelled
Publish or Update docker image for head of branch / deploy-container (push) Has been cancelled
Release or update docker image for a released mbed-os version / build-container (push) Has been cancelled
Release or update docker image for a released mbed-os version / test-container (linux/amd64) (push) Has been cancelled
Release or update docker image for a released mbed-os version / test-container (linux/arm64) (push) Has been cancelled
Release or update docker image for a released mbed-os version / deploy-container (push) Has been cancelled
Prune temporary docker images / prune-images (push) Has been cancelled
301 lines
14 KiB
C
301 lines
14 KiB
C
/***************************************************************************//**
|
|
* \file cyhal_gpio.h
|
|
*
|
|
* \brief
|
|
* Provides a high level interface for interacting with the GPIO on Cypress devices.
|
|
* This interface abstracts out the chip specific details. If any chip specific
|
|
* functionality is necessary, or performance is critical the low level functions
|
|
* can be used directly.
|
|
*
|
|
********************************************************************************
|
|
* \copyright
|
|
* Copyright 2018-2021 Cypress Semiconductor Corporation
|
|
* SPDX-License-Identifier: Apache-2.0
|
|
*
|
|
* Licensed under the Apache License, Version 2.0 (the "License");
|
|
* you may not use this file except in compliance with the License.
|
|
* You may obtain a copy of the License at
|
|
*
|
|
* http://www.apache.org/licenses/LICENSE-2.0
|
|
*
|
|
* Unless required by applicable law or agreed to in writing, software
|
|
* distributed under the License is distributed on an "AS IS" BASIS,
|
|
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
* See the License for the specific language governing permissions and
|
|
* limitations under the License.
|
|
*******************************************************************************/
|
|
|
|
/**
|
|
* \addtogroup group_hal_gpio GPIO (General Purpose Input Output)
|
|
* \ingroup group_hal
|
|
* \{
|
|
* High level interface for configuring and interacting with general purpose input/outputs (GPIO).
|
|
*
|
|
* The GPIO driver provides functions to configure and initialize GPIO, and to read and write data to the pin.
|
|
* The driver also supports interrupt generation on GPIO signals with rising, falling or both edges.
|
|
*
|
|
* \note The APIs in this driver need not be used if a GPIO is to be used as an input or output of peripherals like I2C or PWM.
|
|
* The respective peripheral's driver will utilize the GPIO interface to configure and initialize its GPIO pins.
|
|
*
|
|
* \section subsection_gpio_features Features
|
|
* * Configurable GPIO pin direction - \ref cyhal_gpio_direction_t
|
|
* * Configurable GPIO pin drive modes - \ref cyhal_gpio_drive_mode_t
|
|
* * Configurable analog and digital characteristics
|
|
* * Configurable edge-triggered interrupts and callback assignment on GPIO events - \ref cyhal_gpio_event_t
|
|
*
|
|
* \section subsection_gpio_quickstart Quick Start
|
|
* \ref cyhal_gpio_init can be used for a simple GPIO initialization by providing the pin number (<b>pin</b>), pin direction (<b>direction</b>),
|
|
* pin drive mode (<b>drive_mode</b>) and the initial value on the pin (<b>init_val</b>).
|
|
*
|
|
* \section subsection_gpio_sample_snippets Code Snippets
|
|
*
|
|
* \subsection subsection_gpio_snippet_1 Snippet 1: Reading value from GPIO
|
|
* The following snippet initializes GPIO pin \ref P0_0 as an input with high impedance digital drive mode and initial value = <b>false</b> (low). A value is read
|
|
* from the pin and stored to a uint8_t variable (<b>read_val</b>).
|
|
|
|
* \snippet hal_gpio.c snippet_cyhal_gpio_read
|
|
|
|
* \subsection subsection_gpio_snippet_2 Snippet 2: Writing value to a GPIO
|
|
* The following snippet initializes GPIO pin \ref P0_0 as an output pin with strong drive mode and initial value = <b>false</b> (low).
|
|
* A value = <b>true</b> (high) is written to the output driver.
|
|
|
|
* \snippet hal_gpio.c snippet_cyhal_gpio_write
|
|
|
|
* \subsection subsection_gpio_snippet_3 Snippet 3: Reconfiguring a GPIO
|
|
* The following snippet shows how to reconfigure a GPIO pin during run-time using the firmware. The GPIO pin \ref P0_0
|
|
* is first initialized as an output pin with strong drive mode. The pin is then reconfigured as an input with high impedance digital drive mode.
|
|
* \note \ref cyhal_gpio_configure only changes the <b>direction</b> and the <b>drive_mode</b>
|
|
* of the pin. Previously set pin value is retained.
|
|
*
|
|
* \snippet hal_gpio.c snippet_cyhal_gpio_reconfigure
|
|
|
|
* \subsection subsection_gpio_snippet_4 Snippet 4: Interrupts on GPIO events
|
|
* GPIO events can be mapped to an interrupt and assigned to a callback function. The callback function needs to be first registered and
|
|
* then the event needs to be enabled.
|
|
** The following snippet initializes GPIO pin \ref P0_0 as an input pin. It registers a callback function and enables detection
|
|
* of a falling edge event to trigger the callback.
|
|
* \note If no argument needs to be passed to the callback function then a NULL can be passed during registering. <br>
|
|
*
|
|
* \snippet hal_gpio.c snippet_cyhal_gpio_interrupt
|
|
*/
|
|
|
|
#pragma once
|
|
|
|
#include <stdint.h>
|
|
#include <stdbool.h>
|
|
#include "cy_result.h"
|
|
#include "cyhal_hw_types.h"
|
|
#include "cyhal_interconnect.h"
|
|
|
|
#if defined(__cplusplus)
|
|
extern "C" {
|
|
#endif /* __cplusplus */
|
|
|
|
/** \addtogroup group_hal_results_gpio GPIO HAL Results
|
|
* GPIO specific return codes
|
|
* \ingroup group_hal_results
|
|
* \{ *//**
|
|
*/
|
|
|
|
/** The specified pin has no supported input signal */
|
|
#define CYHAL_GPIO_RSLT_ERR_NO_INPUT_SIGNAL \
|
|
(CYHAL_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CYHAL_RSLT_MODULE_GPIO, 0))
|
|
/** The specified pin has no supported output signal */
|
|
#define CYHAL_GPIO_RSLT_ERR_NO_OUTPUT_SIGNAL \
|
|
(CYHAL_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CYHAL_RSLT_MODULE_GPIO, 1))
|
|
|
|
/**
|
|
* \}
|
|
*/
|
|
|
|
/*******************************************************************************
|
|
* Defines
|
|
*******************************************************************************/
|
|
|
|
/** Integer representation of no connect pin (required to exist in all BSPs) */
|
|
#define CYHAL_NC_PIN_VALUE (NC)
|
|
|
|
/*******************************************************************************
|
|
* Enumerations
|
|
*******************************************************************************/
|
|
|
|
/** Pin events */
|
|
typedef enum {
|
|
CYHAL_GPIO_IRQ_NONE = 0, /**< No interrupt */
|
|
CYHAL_GPIO_IRQ_RISE = 1 << 0, /**< Interrupt on rising edge */
|
|
CYHAL_GPIO_IRQ_FALL = 1 << 1, /**< Interrupt on falling edge */
|
|
CYHAL_GPIO_IRQ_BOTH = (CYHAL_GPIO_IRQ_RISE | CYHAL_GPIO_IRQ_FALL), /**< Interrupt on both rising and falling edges */
|
|
} cyhal_gpio_event_t;
|
|
|
|
/** Pin direction */
|
|
typedef enum {
|
|
CYHAL_GPIO_DIR_INPUT, /**< Input pin */
|
|
CYHAL_GPIO_DIR_OUTPUT, /**< Output pin */
|
|
CYHAL_GPIO_DIR_BIDIRECTIONAL, /**< Input and output pin */
|
|
} cyhal_gpio_direction_t;
|
|
|
|
/** Pin drive mode */
|
|
|
|
/** \note When the <b> drive_mode </b> of the <b> pin </b> is set to <b> CYHAL_GPIO_DRIVE_PULL_NONE </b>,
|
|
* it is set to <b> CYHAL_GPIO_DRIVE_STRONG </b> if the <b> direction </b>
|
|
* of the <b> pin </b> is <b> CYHAL_GPIO_DIR_OUTPUT </b> or <b> CYHAL_GPIO_DIR_BIDIRECTIONAL</b>.
|
|
* If not, the <b> drive_mode </b> of the <b> pin </b> is set to <b> CYHAL_GPIO_DRIVE_NONE</b>.
|
|
*/
|
|
typedef enum {
|
|
CYHAL_GPIO_DRIVE_NONE, /**< Digital Hi-Z. Input only. Input init value(s): 0 or 1 */
|
|
CYHAL_GPIO_DRIVE_ANALOG, /**< Analog Hi-Z. Use only for analog purpose */
|
|
CYHAL_GPIO_DRIVE_PULLUP, /**< Pull-up resistor. Input and output. Input init value(s): 1, output value(s): 0 */
|
|
CYHAL_GPIO_DRIVE_PULLDOWN, /**< Pull-down resistor. Input and output. Input init value(s): 0, output value(s): 1 */
|
|
CYHAL_GPIO_DRIVE_OPENDRAINDRIVESLOW, /**< Open-drain, Drives Low. Input and output. Input init value(s): 1, output value(s): 0 */
|
|
CYHAL_GPIO_DRIVE_OPENDRAINDRIVESHIGH, /**< Open-drain, Drives High. Input and output. Input init value(s): 0, output value(s): 1 */
|
|
CYHAL_GPIO_DRIVE_STRONG, /**< Strong output. Output only. Output init value(s): 0 or 1 */
|
|
CYHAL_GPIO_DRIVE_PULLUPDOWN, /**< Pull-up and pull-down resistors. Input and output. Input init value(s): 0 or 1, output value(s): 0 or 1 */
|
|
CYHAL_GPIO_DRIVE_PULL_NONE, /**< No Pull-up or pull-down resistors. Input and output. Input init value(s): 0 or 1, output value(s): 0 or 1 */
|
|
} cyhal_gpio_drive_mode_t;
|
|
|
|
/** GPIO callback function type */
|
|
typedef void (*cyhal_gpio_event_callback_t)(void *callback_arg, cyhal_gpio_event_t event);
|
|
|
|
/*******************************************************************************
|
|
* Functions
|
|
*******************************************************************************/
|
|
|
|
/** Initialize the GPIO pin <br>
|
|
* See \ref subsection_gpio_snippet_1.
|
|
*
|
|
* @param[in] pin The GPIO pin to initialize
|
|
* @param[in] direction The pin direction
|
|
* @param[in] drive_mode The pin drive mode
|
|
* @param[in] init_val Initial value on the pin
|
|
*
|
|
* @return The status of the init request
|
|
*
|
|
* Guidance for using gpio drive modes ( \ref cyhal_gpio_drive_mode_t for details).
|
|
* For default use drive modes:
|
|
* Input GPIO direction - \ref CYHAL_GPIO_DRIVE_NONE
|
|
* Output GPIO direction - \ref CYHAL_GPIO_DRIVE_STRONG
|
|
* Bidirectional GPIO - \ref CYHAL_GPIO_DRIVE_PULLUPDOWN
|
|
* \warning Don't use \ref CYHAL_GPIO_DRIVE_STRONG for input GPIO direction. It may cause an overcurrent issue.
|
|
*/
|
|
cy_rslt_t cyhal_gpio_init(cyhal_gpio_t pin, cyhal_gpio_direction_t direction, cyhal_gpio_drive_mode_t drive_mode, bool init_val);
|
|
|
|
/** Uninitialize the gpio peripheral and the cyhal_gpio_t object
|
|
*
|
|
* @param[in] pin Pin number
|
|
*/
|
|
void cyhal_gpio_free(cyhal_gpio_t pin);
|
|
|
|
/** Configure the GPIO pin <br>
|
|
* See \ref subsection_gpio_snippet_3.
|
|
*
|
|
* @param[in] pin The GPIO pin
|
|
* @param[in] direction The pin direction
|
|
* @param[in] drive_mode The pin drive mode
|
|
*
|
|
* @return The status of the configure request
|
|
*/
|
|
cy_rslt_t cyhal_gpio_configure(cyhal_gpio_t pin, cyhal_gpio_direction_t direction, cyhal_gpio_drive_mode_t drive_mode);
|
|
|
|
/** Set the output value for the pin. This only works for output & in_out pins. <br>
|
|
* See \ref subsection_gpio_snippet_2.
|
|
*
|
|
* @param[in] pin The GPIO object
|
|
* @param[in] value The value to be set (high = true, low = false)
|
|
*/
|
|
void cyhal_gpio_write(cyhal_gpio_t pin, bool value);
|
|
|
|
/** Read the input value. This only works for \ref CYHAL_GPIO_DIR_INPUT & \ref CYHAL_GPIO_DIR_BIDIRECTIONAL pins. <br>
|
|
* See \ref subsection_gpio_snippet_1.
|
|
*
|
|
* @param[in] pin The GPIO object
|
|
* @return The value of the IO (true = high, false = low)
|
|
*/
|
|
bool cyhal_gpio_read(cyhal_gpio_t pin);
|
|
|
|
/** Toggle the output value <br>
|
|
* See \ref subsection_gpio_snippet_4.
|
|
* @param[in] pin The GPIO object
|
|
*/
|
|
void cyhal_gpio_toggle(cyhal_gpio_t pin);
|
|
|
|
/** Register/clear a callback handler for pin events <br>
|
|
*
|
|
* This function will be called when one of the events enabled by \ref cyhal_gpio_enable_event occurs.
|
|
*
|
|
* See \ref subsection_gpio_snippet_4.
|
|
*
|
|
* @param[in] pin The pin number
|
|
* @param[in] callback The function to call when the specified event happens. Pass NULL to unregister the handler.
|
|
* @param[in] callback_arg Generic argument that will be provided to the callback when called, can be NULL
|
|
*/
|
|
void cyhal_gpio_register_callback(cyhal_gpio_t pin, cyhal_gpio_event_callback_t callback, void *callback_arg);
|
|
|
|
/** Enable or Disable the specified GPIO event <br>
|
|
*
|
|
* When an enabled event occurs, the function specified by \ref cyhal_gpio_register_callback will be called.
|
|
*
|
|
* See \ref subsection_gpio_snippet_4.
|
|
*
|
|
* @param[in] pin The GPIO object
|
|
* @param[in] event The GPIO event
|
|
* @param[in] intr_priority The priority for NVIC interrupt events. Interrupt priorities specific to a pin may not
|
|
* be supported on all platforms. Refer to platform implementation specific documentation
|
|
* for details.
|
|
* @param[in] enable True to turn on interrupts, False to turn off
|
|
*/
|
|
void cyhal_gpio_enable_event(cyhal_gpio_t pin, cyhal_gpio_event_t event, uint8_t intr_priority, bool enable);
|
|
|
|
/** Connects a source signal and enables an input to a pin that, when triggered, will set the pins output
|
|
*
|
|
* @param[in] pin GPIO object
|
|
* @param[in] source Source signal obtained from another driver's cyhal_<PERIPH>_enable_output
|
|
* @param[in] type Whether the incoming signal will act as a edge or level input
|
|
* @return The status of the connection
|
|
* */
|
|
cy_rslt_t cyhal_gpio_connect_digital(cyhal_gpio_t pin, cyhal_source_t source, cyhal_signal_type_t type);
|
|
|
|
/** Enables an output signal from a pin that is triggered by the pins input
|
|
*
|
|
* @param[in] pin GPIO object
|
|
* @param[out] source Pointer to user-allocated source signal object which
|
|
* will be initialized by enable_output. \p source should be passed to
|
|
* (dis)connect_digital functions to (dis)connect the associated endpoints.
|
|
* @return The status of the output enable
|
|
* */
|
|
cy_rslt_t cyhal_gpio_enable_output(cyhal_gpio_t pin, cyhal_source_t *source);
|
|
|
|
/** Disconnects a source signal and disables an input to a pin
|
|
*
|
|
* @param[in] pin GPIO object
|
|
* @param[in] source Source signal from cyhal_<PERIPH>_enable_output to disable
|
|
* @return The status of the disconnection
|
|
* */
|
|
cy_rslt_t cyhal_gpio_disconnect_digital(cyhal_gpio_t pin, cyhal_source_t source);
|
|
|
|
/** Disables an output signal from a pin
|
|
*
|
|
* @param[in] pin GPIO object
|
|
* @return The status of the output enable
|
|
* */
|
|
cy_rslt_t cyhal_gpio_disable_output(cyhal_gpio_t pin);
|
|
|
|
/*******************************************************************************
|
|
* Backward compatibility macro. The following code is DEPRECATED and must
|
|
* not be used in new projects
|
|
*******************************************************************************/
|
|
/** \cond INTERNAL */
|
|
#define cyhal_gpio_register_irq(pin, priority, handler, handler_arg) cyhal_gpio_register_callback(pin, handler, handler_arg)
|
|
#define cyhal_gpio_irq_enable(pin, event, enable) cyhal_gpio_enable_event(pin, event, CYHAL_ISR_PRIORITY_DEFAULT, enable)
|
|
typedef cyhal_gpio_event_t cyhal_gpio_irq_event_t;
|
|
/** \endcond */
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif /* __cplusplus */
|
|
|
|
#ifdef CYHAL_GPIO_IMPL_HEADER
|
|
#include CYHAL_GPIO_IMPL_HEADER
|
|
#endif /* CYHAL_GPIO_IMPL_HEADER */
|
|
|
|
/** \} group_hal_gpio */
|