1 /** 2 * @file skbd.h 3 * @brief Secure Keyboard(SKBD) function prototypes and data types. 4 */ 5 6 /****************************************************************************** 7 * 8 * Copyright (C) 2022-2023 Maxim Integrated Products, Inc. (now owned by 9 * Analog Devices, Inc.), 10 * Copyright (C) 2023-2024 Analog Devices, Inc. 11 * 12 * Licensed under the Apache License, Version 2.0 (the "License"); 13 * you may not use this file except in compliance with the License. 14 * You may obtain a copy of the License at 15 * 16 * http://www.apache.org/licenses/LICENSE-2.0 17 * 18 * Unless required by applicable law or agreed to in writing, software 19 * distributed under the License is distributed on an "AS IS" BASIS, 20 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 21 * See the License for the specific language governing permissions and 22 * limitations under the License. 23 * 24 ******************************************************************************/ 25 26 #ifndef LIBRARIES_PERIPHDRIVERS_INCLUDE_MAX32570_SKBD_H_ 27 #define LIBRARIES_PERIPHDRIVERS_INCLUDE_MAX32570_SKBD_H_ 28 29 #include <stddef.h> 30 #include "mxc_assert.h" 31 #include "mxc_pins.h" 32 #include "mxc_lock.h" 33 #include "mxc_delay.h" 34 #include "mxc_device.h" 35 #include "mxc_errors.h" 36 #include "skbd_regs.h" 37 #include "gcr_regs.h" 38 39 #ifdef __cplusplus 40 extern "C" { 41 #endif 42 43 /** @defgroup skbd Secure Keyboard (SKBD) 44 * 45 * @ingroup periphlibs 46 * 47 * @{ 48 */ 49 50 #define xstr(s) str(s) 51 #define str(s) #s 52 #define MXC_SKBD_VERS_MAJOR <VERSMAJ> 53 #define MXC_SKBD_VERS_MINOR <VERSMIN> 54 #define MXC_SKBD_VERS_PATCH <VERSPAT> 55 #define MXC_SKBD_VERSION_STRING \ 56 "v" xstr(MXC_SKBD_VERS_MAJOR) "." xstr(MXC_SKBD_VERS_MINOR) "." xstr(MXC_SKBD_VERS_PATCH) 57 58 /* COBRA adaptation */ 59 #define MXC_KEYPAD_BASE_ERR 0 //COBRA_KEYPAD_BASE_ERR 60 /* Number of key registers present in the keypad interface */ 61 #define MXC_SKBD_TOTAL_KEY_REGS 4 62 63 /** 64 * @brief Keypad errors list 65 * 66 */ 67 typedef enum { 68 MXC_SKBD_ERR_MIN = MXC_KEYPAD_BASE_ERR, 69 MXC_SKBD_ERR_NOT_INITIALIZED, ///< Error Code: Keypad not initialized 70 MXC_SKBD_ERR_ALREAD_INITIALIZED, ///< Error Code: Keypad already initialized 71 MXC_SKBD_ERR_INVALID_OPERATION, ///< Error Code: Invalid keypad operation 72 MXC_SKBD_ERR_OUT_OF_RANGE, ///< Error Code: Invalid parameter or value 73 MXC_SKBD_ERR_OVERRUN, ///< Error Code: Keypad Over run error 74 MXC_SKBD_ERR_IRQ, ///< Error Code: IRQ setup error 75 MXC_SKBD_ERR_IRQ_NULL, ///< Error Code: NULL IRQ handler 76 MXC_SKBD_ERR_INVALID_PIN_CONFIGURATION, ///< Error Code: One or more keypad I/O pins are overlapped or input/output pin configurations are invalid 77 MXC_SKBD_ERR_BUSY, ///< Error Code: Keypad is busy 78 MXC_SKBD_ERR_UNKNOWN, ///< Error Code: Generic error for unknown behavior 79 MXC_SKBD_ERR_MAX = MXC_SKBD_ERR_UNKNOWN 80 } mxc_skbd_errors_t; 81 82 /** 83 * @brief Keypad initialization state FSM 84 * 85 */ 86 typedef enum { 87 MXC_SKBD_STATE_MIN = 0, 88 MXC_SKBD_STATE_NOT_INITIALIZED = MXC_SKBD_STATE_MIN, ///< State not initialized 89 MXC_SKBD_STATE_INITIALIZED, ///< State initialized 90 MXC_SKBD_STATE_CLOSED, ///< State closed 91 MXC_SKBD_STATE_MAX = MXC_SKBD_STATE_CLOSED, 92 MXC_SKBD_STATE_COUNT 93 } mxc_skbd_state_t; 94 95 /** 96 * @brief Keypad events 97 * 98 */ 99 typedef enum { 100 MXC_SKBD_EVENT_PUSH = MXC_F_SKBD_IER_PUSHIE, ///< Push Event 101 MXC_SKBD_EVENT_RELEASE = MXC_F_SKBD_IER_RELEASEIE, ///< Release Event 102 MXC_SKBD_EVENT_OVERRUN = MXC_F_SKBD_IER_OVERIE ///< Overrun Event 103 } mxc_skbd_events_t; 104 105 /** 106 * @brief Keypad Interrupt Status 107 * 108 */ 109 typedef enum { 110 MXC_SKBD_INTERRUPT_STATUS_PUSHIS = MXC_F_SKBD_ISR_PUSHIS, ///< Push Interupt flag 111 MXC_SKBD_INTERRUPT_STATUS_RELEASEIS = MXC_F_SKBD_ISR_RELEASEIS, ///< Release Interupt flag 112 MXC_SKBD_INTERRUPT_STATUS_OVERIS = MXC_F_SKBD_ISR_OVERIS ///< Overrun Interupt flag 113 } mxc_interrupt_status_t; 114 115 /** 116 * @brief Keypad I/O's IOSEL 117 * 118 */ 119 typedef enum { 120 MXC_SKBD_KBDIO0 = (0x01 << 0), ///< SKBD pin 0 121 MXC_SKBD_KBDIO1 = (0x01 << 1), ///< SKBD pin 1 122 MXC_SKBD_KBDIO2 = (0x01 << 2), ///< SKBD pin 2 123 MXC_SKBD_KBDIO3 = (0x01 << 3), ///< SKBD pin 3 124 MXC_SKBD_KBDIO4 = (0x01 << 4), ///< SKBD pin 4 125 MXC_SKBD_KBDIO5 = (0x01 << 5), ///< SKBD pin 5 126 MXC_SKBD_KBDIO6 = (0x01 << 6), ///< SKBD pin 6 127 MXC_SKBD_KBDIO7 = (0x01 << 7), ///< SKBD pin 7 128 MXC_SKBD_KBDIO8 = (0x01 << 8), ///< SKBD pin 8 129 MXC_SKBD_KBDIO9 = (0x01 << 9), ///< SKBD pin 9 130 } mxc_skbd_io_pins_t; 131 132 /** 133 * @brief Keypad IRQ handler function 134 * 135 */ 136 typedef void (*irq_handler_t)(void); 137 138 /** 139 * @brief Keypad configuration structure 140 * 141 */ 142 typedef struct { 143 uint16_t ioselect; ///< I/O pin direction selection for the corresponding keypad pins 144 unsigned int reg_erase; ///< key register erase flag on key is released 145 int outputs; ///< Specifies the keypad pins to be configured as output 146 int inputs; ///< Specifies the keypad pins to be configured as input 147 uint32_t debounce; ///< Keypad Debouncing Time 148 irq_handler_t irq_handler; ///< IRQ handler 149 } mxc_skbd_config_t; 150 151 /** 152 * @brief Keypad channel context information 153 * 154 */ 155 typedef struct { 156 unsigned int first_init; ///< 1 - initialize 157 unsigned int irq; ///< Interrupt request(IRQ) number 158 irq_handler_t irq_handler; ///< IRQ handler 159 mxc_skbd_state_t state; ///< keypad initialization state 160 } mxc_skbd_req_t; 161 162 /** 163 * @brief Keyboard Key's scan codes 164 * 165 */ 166 typedef struct { 167 /* 168 * key scan code format as follows 169 * key(x) bits[3-0] : Input scan code 170 * key(x) bits[7-4] : Output scan code 171 * key(x) bit[8] : Next Key Flag 172 */ 173 uint16_t key0; ///< Key0 scan code 174 uint16_t key1; ///< Key1 scan code 175 uint16_t key2; ///< Key2 scan code 176 uint16_t key3; ///< Key3 scan code 177 } mxc_skbd_keys_t; 178 179 /** 180 * @brief Return the version of the SKBD driver 181 * 182 * @return const char* 183 */ 184 const char *MXC_SKBD_GetVersion(void); 185 186 /** 187 * @brief Configure Keypad interrupt 188 * 189 * @return int see \ref mxc_skbd_errors_t for a list of return codes 190 */ 191 int MXC_SKBD_PreInit(void); 192 193 /** 194 * @brief The function is used to initialize the keypad controller 195 * @param [in] config Configuration to set 196 * @retval NO_ERROR No error 197 * @retval COMMON_ERR_UNKNOWN Unknown error 198 * @retval MXC_SKBD_ERR_IRQ_NULL Handler is null 199 * @retval MXC_SKBD_ERR_INVALID_PIN_CONFIGURATION One or more keypad I/O pins are overlapped or 200 * input/output pin configurations are invalid 201 * @retval int see \ref mxc_skbd_errors_t for a list of return codes 202 */ 203 int MXC_SKBD_Init(mxc_skbd_config_t config); 204 205 /** 206 * @brief Function is used to enable the interrupt events 207 * @param [in] events Input interrupt events to set 208 * @retval NO_ERROR No error 209 * @retval COMMON_ERR_UNKNOWN Unknown error 210 * @retval MXC_SKBD_ERR_NOT_INITIALIZED SKBD not initialized 211 */ 212 int MXC_SKBD_EnableInterruptEvents(unsigned int events); 213 214 /** 215 * @brief Function to disable the interrupt events 216 * @param [in] events Input interrupt events to disable 217 * @retval int see \ref mxc_skbd_errors_t for a list of return codes 218 */ 219 int MXC_SKBD_DisableInterruptEvents(unsigned int events); 220 221 /** 222 * @brief Function is used to clear the interrupt events 223 * @param [in] status Interrupt status to clear 224 * @retval int see \ref mxc_skbd_errors_t for a list of return codes 225 */ 226 int MXC_SKBD_ClearInterruptStatus(unsigned int status); 227 228 /** 229 * @brief Function is used to read the interrupt status 230 * @param [in] status Interrupt status to clear 231 * @retval int see \ref mxc_skbd_errors_t for a list of return codes 232 */ 233 int MXC_SKBD_InterruptStatus(unsigned int *status); 234 235 /** 236 * @brief Function to read the key scan codes 237 * @param [in] keys Pointer on the keyboard Key's scan codes 238 * @retval int see \ref mxc_skbd_errors_t for a list of return codes 239 */ 240 int MXC_SKBD_ReadKeys(mxc_skbd_keys_t *keys); 241 242 /** 243 * @brief Function to close the keypad 244 * @retval int see \ref mxc_skbd_errors_t for a list of return codes 245 */ 246 int MXC_SKBD_Close(void); 247 248 /** @} end of group skbd */ 249 250 #ifdef __cplusplus 251 } 252 #endif 253 254 #endif // LIBRARIES_PERIPHDRIVERS_INCLUDE_MAX32570_SKBD_H_ 255
