1 /* 2 * Copyright (c) 2020 - 2024 Renesas Electronics Corporation and/or its affiliates 3 * 4 * SPDX-License-Identifier: BSD-3-Clause 5 */ 6 7 /*******************************************************************************************************************//** 8 * @ingroup RENESAS_SYSTEM_INTERFACES 9 * @defgroup IOPORT_API I/O Port Interface 10 * @brief Interface for accessing I/O ports and configuring I/O functionality. 11 * 12 * @section IOPORT_API_SUMMARY Summary 13 * The IOPort shared interface provides the ability to access the IOPorts of a device at both bit and port level. 14 * Port and pin direction can be changed. 15 * 16 * 17 * @{ 18 **********************************************************************************************************************/ 19 20 #ifndef R_IOPORT_API_H 21 #define R_IOPORT_API_H 22 23 /*********************************************************************************************************************** 24 * Includes 25 **********************************************************************************************************************/ 26 27 /* Common error codes and definitions. */ 28 #include "bsp_api.h" 29 30 /* Common macro for FSP header files. There is also a corresponding FSP_FOOTER macro at the end of this file. */ 31 FSP_HEADER 32 33 /********************************************************************************************************************** 34 * Macro definitions 35 **********************************************************************************************************************/ 36 37 /********************************************************************************************************************** 38 * Typedef definitions 39 **********************************************************************************************************************/ 40 #ifndef BSP_OVERRIDE_IOPORT_SIZE_T 41 42 /** IO port type used with ports */ 43 typedef uint16_t ioport_size_t; ///< IO port size 44 #endif 45 46 /** Pin identifier and pin configuration value */ 47 typedef struct st_ioport_pin_cfg 48 { 49 uint32_t pin_cfg; ///< Pin configuration - Use ioport_cfg_options_t parameters to configure 50 bsp_io_port_pin_t pin; ///< Pin identifier 51 } ioport_pin_cfg_t; 52 53 /** Multiple pin configuration data for loading into registers by R_IOPORT_Open() */ 54 typedef struct st_ioport_cfg 55 { 56 uint16_t number_of_pins; ///< Number of pins for which there is configuration data 57 ioport_pin_cfg_t const * p_pin_cfg_data; ///< Pin configuration data 58 const void * p_extend; ///< Pointer to hardware extend configuration 59 } ioport_cfg_t; 60 61 /** IOPORT control block. Allocate an instance specific control block to pass into the IOPORT API calls. 62 */ 63 typedef void ioport_ctrl_t; 64 65 /** IOPort driver structure. IOPort functions implemented at the HAL layer will follow this API. */ 66 typedef struct st_ioport_api 67 { 68 /** Initialize internal driver data and initial pin configurations. Called during startup. Do 69 * not call this API during runtime. Use @ref ioport_api_t::pinsCfg for runtime reconfiguration of 70 * multiple pins. 71 * 72 * @param[in] p_ctrl Pointer to control structure. Must be declared by user. Elements set here. 73 * @param[in] p_cfg Pointer to pin configuration data array. 74 */ 75 fsp_err_t (* open)(ioport_ctrl_t * const p_ctrl, const ioport_cfg_t * p_cfg); 76 77 /** Close the API. 78 * 79 * @param[in] p_ctrl Pointer to control structure. 80 **/ 81 fsp_err_t (* close)(ioport_ctrl_t * const p_ctrl); 82 83 /** Configure multiple pins. 84 * 85 * @param[in] p_ctrl Pointer to control structure. 86 * @param[in] p_cfg Pointer to pin configuration data array. 87 */ 88 fsp_err_t (* pinsCfg)(ioport_ctrl_t * const p_ctrl, const ioport_cfg_t * p_cfg); 89 90 /** Configure settings for an individual pin. 91 * 92 * @param[in] p_ctrl Pointer to control structure. 93 * @param[in] pin Pin to be read. 94 * @param[in] cfg Configuration options for the pin. 95 */ 96 fsp_err_t (* pinCfg)(ioport_ctrl_t * const p_ctrl, bsp_io_port_pin_t pin, uint32_t cfg); 97 98 /** Read the event input data of the specified pin and return the level. 99 * 100 * @param[in] p_ctrl Pointer to control structure. 101 * @param[in] pin Pin to be read. 102 * @param[in] p_pin_event Pointer to return the event data. 103 */ 104 fsp_err_t (* pinEventInputRead)(ioport_ctrl_t * const p_ctrl, bsp_io_port_pin_t pin, bsp_io_level_t * p_pin_event); 105 106 /** Write pin event data. 107 * 108 * @param[in] p_ctrl Pointer to control structure. 109 * @param[in] pin Pin event data is to be written to. 110 * @param[in] pin_value Level to be written to pin output event. 111 */ 112 fsp_err_t (* pinEventOutputWrite)(ioport_ctrl_t * const p_ctrl, bsp_io_port_pin_t pin, bsp_io_level_t pin_value); 113 114 /** Read level of a pin. 115 * 116 * @param[in] p_ctrl Pointer to control structure. 117 * @param[in] pin Pin to be read. 118 * @param[in] p_pin_value Pointer to return the pin level. 119 */ 120 fsp_err_t (* pinRead)(ioport_ctrl_t * const p_ctrl, bsp_io_port_pin_t pin, bsp_io_level_t * p_pin_value); 121 122 /** Write specified level to a pin. 123 * 124 * @param[in] p_ctrl Pointer to control structure. 125 * @param[in] pin Pin to be written to. 126 * @param[in] level State to be written to the pin. 127 */ 128 fsp_err_t (* pinWrite)(ioport_ctrl_t * const p_ctrl, bsp_io_port_pin_t pin, bsp_io_level_t level); 129 130 /** Set the direction of one or more pins on a port. 131 * 132 * @param[in] p_ctrl Pointer to control structure. 133 * @param[in] port Port being configured. 134 * @param[in] direction_values Value controlling direction of pins on port. 135 * @param[in] mask Mask controlling which pins on the port are to be configured. 136 */ 137 fsp_err_t (* portDirectionSet)(ioport_ctrl_t * const p_ctrl, bsp_io_port_t port, ioport_size_t direction_values, 138 ioport_size_t mask); 139 140 /** Read captured event data for a port. 141 * 142 * @param[in] p_ctrl Pointer to control structure. 143 * @param[in] port Port to be read. 144 * @param[in] p_event_data Pointer to return the event data. 145 */ 146 fsp_err_t (* portEventInputRead)(ioport_ctrl_t * const p_ctrl, bsp_io_port_t port, ioport_size_t * p_event_data); 147 148 /** Write event output data for a port. 149 * 150 * @param[in] p_ctrl Pointer to control structure. 151 * @param[in] port Port event data will be written to. 152 * @param[in] event_data Data to be written as event data to specified port. 153 * @param[in] mask_value Each bit set to 1 in the mask corresponds to that bit's value in event data. 154 * being written to port. 155 */ 156 fsp_err_t (* portEventOutputWrite)(ioport_ctrl_t * const p_ctrl, bsp_io_port_t port, ioport_size_t event_data, 157 ioport_size_t mask_value); 158 159 /** Read states of pins on the specified port. 160 * 161 * @param[in] p_ctrl Pointer to control structure. 162 * @param[in] port Port to be read. 163 * @param[in] p_port_value Pointer to return the port value. 164 */ 165 fsp_err_t (* portRead)(ioport_ctrl_t * const p_ctrl, bsp_io_port_t port, ioport_size_t * p_port_value); 166 167 /** Write to multiple pins on a port. 168 * 169 * @param[in] p_ctrl Pointer to control structure. 170 * @param[in] port Port to be written to. 171 * @param[in] value Value to be written to the port. 172 * @param[in] mask Mask controlling which pins on the port are written to. 173 */ 174 fsp_err_t (* portWrite)(ioport_ctrl_t * const p_ctrl, bsp_io_port_t port, ioport_size_t value, ioport_size_t mask); 175 } ioport_api_t; 176 177 /** This structure encompasses everything that is needed to use an instance of this interface. */ 178 typedef struct st_ioport_instance 179 { 180 ioport_ctrl_t * p_ctrl; ///< Pointer to the control structure for this instance 181 ioport_cfg_t const * p_cfg; ///< Pointer to the configuration structure for this instance 182 ioport_api_t const * p_api; ///< Pointer to the API structure for this instance 183 } ioport_instance_t; 184 185 /* Common macro for FSP header files. There is also a corresponding FSP_HEADER macro at the top of this file. */ 186 FSP_FOOTER 187 188 #endif 189 190 /*******************************************************************************************************************//** 191 * @} (end defgroup IOPORT_API) 192 **********************************************************************************************************************/ 193