1 /*
2  * Copyright (c) 2019 Intel Corporation
3  *
4  * SPDX-License-Identifier: Apache-2.0
5  */
6 
7 /**
8  * @file
9  * @brief Public API for Keyboard scan matrix devices.
10  * The scope of this API is simply to report which key event was triggered
11  * and users can later decode keys using their desired scan code tables in
12  * their application. In addition, typematic rate and delay can easily be
13  * implemented using a timer if desired.
14  */
15 
16 #ifndef ZEPHYR_INCLUDE_DRIVERS_KB_SCAN_H_
17 #define ZEPHYR_INCLUDE_DRIVERS_KB_SCAN_H_
18 
19 #include <errno.h>
20 #include <zephyr/types.h>
21 #include <stddef.h>
22 #include <zephyr/device.h>
23 
24 #ifdef __cplusplus
25 extern "C" {
26 #endif
27 
28 /**
29  * @brief KSCAN APIs
30  * @defgroup kscan_interface Keyboard Scan Driver APIs
31  * @since 2.1
32  * @version 1.0.0
33  * @deprecated
34  * @ingroup io_interfaces
35  * @{
36  */
37 
38 /**
39  * @deprecated
40  * @brief Keyboard scan callback called when user press/release
41  * a key on a matrix keyboard.
42  *
43  * @param dev Pointer to the device structure for the driver instance.
44  * @param row Describes row change.
45  * @param column Describes column change.
46  * @param pressed Describes the kind of key event.
47  */
48 typedef void (*kscan_callback_t)(const struct device *dev, uint32_t row,
49 				 uint32_t column,
50 				 bool pressed);
51 
52 /**
53  * @deprecated
54  * @cond INTERNAL_HIDDEN
55  *
56  * Keyboard scan driver API definition and system call entry points.
57  *
58  * (Internal use only.)
59  */
60 typedef int (*kscan_config_t)(const struct device *dev,
61 			      kscan_callback_t callback);
62 typedef int (*kscan_disable_callback_t)(const struct device *dev);
63 typedef int (*kscan_enable_callback_t)(const struct device *dev);
64 
65 __subsystem struct kscan_driver_api {
66 	kscan_config_t config;
67 	kscan_disable_callback_t disable_callback;
68 	kscan_enable_callback_t enable_callback;
69 };
70 /**
71  * @endcond
72  */
73 
74 /**
75  * @deprecated
76  * @brief Configure a Keyboard scan instance.
77  *
78  * @param dev Pointer to the device structure for the driver instance.
79  * @param callback called when keyboard devices reply to a keyboard
80  * event such as key pressed/released.
81  *
82  * @retval 0 If successful.
83  * @retval Negative errno code if failure.
84  */
85 __syscall int kscan_config(const struct device *dev,
86 			     kscan_callback_t callback);
87 
z_impl_kscan_config(const struct device * dev,kscan_callback_t callback)88 static inline int z_impl_kscan_config(const struct device *dev,
89 					kscan_callback_t callback)
90 {
91 	const struct kscan_driver_api *api =
92 				(struct kscan_driver_api *)dev->api;
93 
94 	return api->config(dev, callback);
95 }
96 /**
97  * @deprecated
98  * @brief Enables callback.
99  * @param dev Pointer to the device structure for the driver instance.
100  *
101  * @retval 0 If successful.
102  * @retval Negative errno code if failure.
103  */
104 __syscall int kscan_enable_callback(const struct device *dev);
105 
z_impl_kscan_enable_callback(const struct device * dev)106 static inline int z_impl_kscan_enable_callback(const struct device *dev)
107 {
108 	const struct kscan_driver_api *api =
109 			(const struct kscan_driver_api *)dev->api;
110 
111 	if (api->enable_callback == NULL) {
112 		return -ENOSYS;
113 	}
114 
115 	return api->enable_callback(dev);
116 }
117 
118 /**
119  * @deprecated
120  * @brief Disables callback.
121  * @param dev Pointer to the device structure for the driver instance.
122  *
123  * @retval 0 If successful.
124  * @retval Negative errno code if failure.
125  */
126 __syscall int kscan_disable_callback(const struct device *dev);
127 
z_impl_kscan_disable_callback(const struct device * dev)128 static inline int z_impl_kscan_disable_callback(const struct device *dev)
129 {
130 	const struct kscan_driver_api *api =
131 			(const struct kscan_driver_api *)dev->api;
132 
133 	if (api->disable_callback == NULL) {
134 		return -ENOSYS;
135 	}
136 
137 	return api->disable_callback(dev);
138 }
139 
140 #ifdef __cplusplus
141 }
142 #endif
143 
144 /**
145  * @}
146  */
147 
148 #include <zephyr/syscalls/kscan.h>
149 
150 #endif /* ZEPHYR_INCLUDE_DRIVERS_KB_SCAN_H_ */
151