1 /*********************************************************************************************************************** 2 * Copyright [2020-2024] Renesas Electronics Corporation and/or its affiliates. All Rights Reserved. 3 * 4 * This software and documentation are supplied by Renesas Electronics Corporation and/or its affiliates and may only 5 * be used with products of Renesas Electronics Corp. and its affiliates ("Renesas"). No other uses are authorized. 6 * Renesas products are sold pursuant to Renesas terms and conditions of sale. Purchasers are solely responsible for 7 * the selection and use of Renesas products and Renesas assumes no liability. No license, express or implied, to any 8 * intellectual property right is granted by Renesas. This software is protected under all applicable laws, including 9 * copyright laws. Renesas reserves the right to change or discontinue this software and/or this documentation. 10 * THE SOFTWARE AND DOCUMENTATION IS DELIVERED TO YOU "AS IS," AND RENESAS MAKES NO REPRESENTATIONS OR WARRANTIES, AND 11 * TO THE FULLEST EXTENT PERMISSIBLE UNDER APPLICABLE LAW, DISCLAIMS ALL WARRANTIES, WHETHER EXPLICITLY OR IMPLICITLY, 12 * INCLUDING WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT, WITH RESPECT TO THE 13 * SOFTWARE OR DOCUMENTATION. RENESAS SHALL HAVE NO LIABILITY ARISING OUT OF ANY SECURITY VULNERABILITY OR BREACH. 14 * TO THE MAXIMUM EXTENT PERMITTED BY LAW, IN NO EVENT WILL RENESAS BE LIABLE TO YOU IN CONNECTION WITH THE SOFTWARE OR 15 * DOCUMENTATION (OR ANY PERSON OR ENTITY CLAIMING RIGHTS DERIVED FROM YOU) FOR ANY LOSS, DAMAGES, OR CLAIMS WHATSOEVER, 16 * INCLUDING, WITHOUT LIMITATION, ANY DIRECT, CONSEQUENTIAL, SPECIAL, INDIRECT, PUNITIVE, OR INCIDENTAL DAMAGES; ANY 17 * LOST PROFITS, OTHER ECONOMIC DAMAGE, PROPERTY DAMAGE, OR PERSONAL INJURY; AND EVEN IF RENESAS HAS BEEN ADVISED OF THE 18 * POSSIBILITY OF SUCH LOSS, DAMAGES, CLAIMS OR COSTS. 19 **********************************************************************************************************************/ 20 21 /*******************************************************************************************************************//** 22 * @ingroup RENESAS_SYSTEM_INTERFACES 23 * @defgroup IOPORT_API I/O Port Interface 24 * @brief Interface for accessing I/O ports and configuring I/O functionality. 25 * 26 * @section IOPORT_API_SUMMARY Summary 27 * The IOPort shared interface provides the ability to access the IOPorts of a device at both bit and port level. 28 * Port and pin direction can be changed. 29 * 30 * 31 * @{ 32 **********************************************************************************************************************/ 33 34 #ifndef R_IOPORT_API_H 35 #define R_IOPORT_API_H 36 37 /*********************************************************************************************************************** 38 * Includes 39 **********************************************************************************************************************/ 40 41 /* Common error codes and definitions. */ 42 #include "bsp_api.h" 43 44 /* Common macro for FSP header files. There is also a corresponding FSP_FOOTER macro at the end of this file. */ 45 FSP_HEADER 46 47 /********************************************************************************************************************** 48 * Macro definitions 49 **********************************************************************************************************************/ 50 51 /********************************************************************************************************************** 52 * Typedef definitions 53 **********************************************************************************************************************/ 54 #ifndef BSP_OVERRIDE_IOPORT_SIZE_T 55 56 /** IO port type used with ports */ 57 typedef uint16_t ioport_size_t; ///< IO port size 58 #endif 59 60 /** Pin identifier and pin configuration value */ 61 typedef struct st_ioport_pin_cfg 62 { 63 uint32_t pin_cfg; ///< Pin configuration - Use ioport_cfg_options_t parameters to configure 64 bsp_io_port_pin_t pin; ///< Pin identifier 65 } ioport_pin_cfg_t; 66 67 /** Multiple pin configuration data for loading into registers by R_IOPORT_Open() */ 68 typedef struct st_ioport_cfg 69 { 70 uint16_t number_of_pins; ///< Number of pins for which there is configuration data 71 ioport_pin_cfg_t const * p_pin_cfg_data; ///< Pin configuration data 72 const void * p_extend; ///< Pointer to hardware extend configuration 73 } ioport_cfg_t; 74 75 /** IOPORT control block. Allocate an instance specific control block to pass into the IOPORT API calls. 76 */ 77 typedef void ioport_ctrl_t; 78 79 /** IOPort driver structure. IOPort functions implemented at the HAL layer will follow this API. */ 80 typedef struct st_ioport_api 81 { 82 /** Initialize internal driver data and initial pin configurations. Called during startup. Do 83 * not call this API during runtime. Use @ref ioport_api_t::pinsCfg for runtime reconfiguration of 84 * multiple pins. 85 * 86 * @param[in] p_ctrl Pointer to control structure. Must be declared by user. Elements set here. 87 * @param[in] p_cfg Pointer to pin configuration data array. 88 */ 89 fsp_err_t (* open)(ioport_ctrl_t * const p_ctrl, const ioport_cfg_t * p_cfg); 90 91 /** Close the API. 92 * 93 * @param[in] p_ctrl Pointer to control structure. 94 **/ 95 fsp_err_t (* close)(ioport_ctrl_t * const p_ctrl); 96 97 /** Configure multiple pins. 98 * 99 * @param[in] p_ctrl Pointer to control structure. 100 * @param[in] p_cfg Pointer to pin configuration data array. 101 */ 102 fsp_err_t (* pinsCfg)(ioport_ctrl_t * const p_ctrl, const ioport_cfg_t * p_cfg); 103 104 /** Configure settings for an individual pin. 105 * 106 * @param[in] p_ctrl Pointer to control structure. 107 * @param[in] pin Pin to be read. 108 * @param[in] cfg Configuration options for the pin. 109 */ 110 fsp_err_t (* pinCfg)(ioport_ctrl_t * const p_ctrl, bsp_io_port_pin_t pin, uint32_t cfg); 111 112 /** Read the event input data of the specified pin and return the level. 113 * 114 * @param[in] p_ctrl Pointer to control structure. 115 * @param[in] pin Pin to be read. 116 * @param[in] p_pin_event Pointer to return the event data. 117 */ 118 fsp_err_t (* pinEventInputRead)(ioport_ctrl_t * const p_ctrl, bsp_io_port_pin_t pin, bsp_io_level_t * p_pin_event); 119 120 /** Write pin event data. 121 * 122 * @param[in] p_ctrl Pointer to control structure. 123 * @param[in] pin Pin event data is to be written to. 124 * @param[in] pin_value Level to be written to pin output event. 125 */ 126 fsp_err_t (* pinEventOutputWrite)(ioport_ctrl_t * const p_ctrl, bsp_io_port_pin_t pin, bsp_io_level_t pin_value); 127 128 /** Read level of a pin. 129 * 130 * @param[in] p_ctrl Pointer to control structure. 131 * @param[in] pin Pin to be read. 132 * @param[in] p_pin_value Pointer to return the pin level. 133 */ 134 fsp_err_t (* pinRead)(ioport_ctrl_t * const p_ctrl, bsp_io_port_pin_t pin, bsp_io_level_t * p_pin_value); 135 136 /** Write specified level to a pin. 137 * 138 * @param[in] p_ctrl Pointer to control structure. 139 * @param[in] pin Pin to be written to. 140 * @param[in] level State to be written to the pin. 141 */ 142 fsp_err_t (* pinWrite)(ioport_ctrl_t * const p_ctrl, bsp_io_port_pin_t pin, bsp_io_level_t level); 143 144 /** Set the direction of one or more pins on a port. 145 * 146 * @param[in] p_ctrl Pointer to control structure. 147 * @param[in] port Port being configured. 148 * @param[in] direction_values Value controlling direction of pins on port. 149 * @param[in] mask Mask controlling which pins on the port are to be configured. 150 */ 151 fsp_err_t (* portDirectionSet)(ioport_ctrl_t * const p_ctrl, bsp_io_port_t port, ioport_size_t direction_values, 152 ioport_size_t mask); 153 154 /** Read captured event data for a port. 155 * 156 * @param[in] p_ctrl Pointer to control structure. 157 * @param[in] port Port to be read. 158 * @param[in] p_event_data Pointer to return the event data. 159 */ 160 fsp_err_t (* portEventInputRead)(ioport_ctrl_t * const p_ctrl, bsp_io_port_t port, ioport_size_t * p_event_data); 161 162 /** Write event output data for a port. 163 * 164 * @param[in] p_ctrl Pointer to control structure. 165 * @param[in] port Port event data will be written to. 166 * @param[in] event_data Data to be written as event data to specified port. 167 * @param[in] mask_value Each bit set to 1 in the mask corresponds to that bit's value in event data. 168 * being written to port. 169 */ 170 fsp_err_t (* portEventOutputWrite)(ioport_ctrl_t * const p_ctrl, bsp_io_port_t port, ioport_size_t event_data, 171 ioport_size_t mask_value); 172 173 /** Read states of pins on the specified port. 174 * 175 * @param[in] p_ctrl Pointer to control structure. 176 * @param[in] port Port to be read. 177 * @param[in] p_port_value Pointer to return the port value. 178 */ 179 fsp_err_t (* portRead)(ioport_ctrl_t * const p_ctrl, bsp_io_port_t port, ioport_size_t * p_port_value); 180 181 /** Write to multiple pins on a port. 182 * 183 * @param[in] p_ctrl Pointer to control structure. 184 * @param[in] port Port to be written to. 185 * @param[in] value Value to be written to the port. 186 * @param[in] mask Mask controlling which pins on the port are written to. 187 */ 188 fsp_err_t (* portWrite)(ioport_ctrl_t * const p_ctrl, bsp_io_port_t port, ioport_size_t value, ioport_size_t mask); 189 } ioport_api_t; 190 191 /** This structure encompasses everything that is needed to use an instance of this interface. */ 192 typedef struct st_ioport_instance 193 { 194 ioport_ctrl_t * p_ctrl; ///< Pointer to the control structure for this instance 195 ioport_cfg_t const * p_cfg; ///< Pointer to the configuration structure for this instance 196 ioport_api_t const * p_api; ///< Pointer to the API structure for this instance 197 } ioport_instance_t; 198 199 /* Common macro for FSP header files. There is also a corresponding FSP_HEADER macro at the top of this file. */ 200 FSP_FOOTER 201 202 #endif 203 204 /*******************************************************************************************************************//** 205 * @} (end defgroup IOPORT_API) 206 **********************************************************************************************************************/ 207