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