FreeCalypso > hg > fc-tourmaline

comparison src/cs/drivers/drv_app/kpd/kpd_api.h @ 0:4e78acac3d88

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
src/{condat,cs,gpf,nucleus}: import from Selenite
author Mychaela Falconia <falcon@freecalypso.org>
date Fri, 16 Oct 2020 06:23:26 +0000
parents
children
comparison
equal deleted inserted replaced
-1:000000000000 0:4e78acac3d88
1 /**
2 * @file kpd_api.h
3 *
4 * API Definition for keypad driver.
5 *
6 * This file gathers all the constants, structure and functions declaration
7 * useful for a keypad driver user.
8 *
9 * @author Laurent Sollier (l-sollier@ti.com)
10 * @version 0.1
11 */
12
13 /*
14 * History:
15 *
16 * Date Author Modification
17 * ----------------------------------------
18 * 10/10/2001 L Sollier Create
19 *
20 *
21 * (C) Copyright 2001 by Texas Instruments Incorporated, All Rights Reserved
22 */
23
24 #ifndef _KPD_API_H_
25 #define _KPD_API_H_
26
27 #include "kpd/kpd_cfg.h"
28
29 #include "rv/rv_general.h"
30 #include "rvf/rvf_api.h"
31
32 /**
33 * @name External types
34 *
35 * Types used in API.
36 *
37 */
38 /*@{*/
39
40 /** Definition of the subscriber identification. */
41 typedef void* T_KPD_SUBSCRIBER;
42
43 /** Definition of the virtual key identification. */
44 typedef UINT8 T_KPD_VIRTUAL_KEY_ID;
45
46 /** Definition of the notification level (First press, long press, infinite repeat, release). */
47 typedef UINT8 T_KPD_NOTIF_LEVEL;
48
49 /** Definition of a set of keys. */
50 typedef struct { UINT8 nb_notified_keys;
51 T_KPD_VIRTUAL_KEY_ID notified_keys[KPD_NB_PHYSICAL_KEYS];
52 } T_KPD_VIRTUAL_KEY_TABLE;
53
54 /*@}*/
55
56
57 /** Allowed values for T_KPD_NOTIF_LEVEL type.
58 * If a key is defined with KPD_NO_NOTIF, this key will be deleted from the key list
59 * notified to the client.
60 * But client will can set later as KPD_RELEASE_NOTIF (for exemple)
61 * without calling unsubscribe, subscribe functions.
62 */
63 #define KPD_NO_NOTIF (0x00)
64
65 /** Allowed values for T_KPD_NOTIF_LEVEL type.
66 * If a key is defined with KPD_FIRST_PRESS_NOTIF, client will be notified by :
67 * - The immediate key press
68 */
69 #define KPD_FIRST_PRESS_NOTIF (0x01)
70
71 /** Allowed values for T_KPD_NOTIF_LEVEL type.
72 * If a key is defined with KPD_LONG_PRESS, client will be notified by :
73 * - The long press if the key is still pressed for a defined time
74 * (defined in kpd_define_repeat_keys function)
75 */
76 #define KPD_LONG_PRESS_NOTIF (0x02)
77
78 /** Allowed values for T_KPD_NOTIF_LEVEL type.
79 * If a key is defined with KPD_INFINITE_REPEAT_NOTIF, client will be notified by :
80 * - The long press if the key is still pressed for a defined time
81 * (defined in kpd_define_repeat_keys function)
82 * - The key pressed every defined time (defined in kpd_define_repeat_keys function),
83 * until the key is released
84 */
85 #define KPD_INFINITE_REPEAT_NOTIF (0x04)
86
87 /** Allowed values for T_KPD_NOTIF_LEVEL type.
88 * If a key is defined with KPD_RELEASE_NOTIF, client will be notified by :
89 * - the key release
90 */
91 #define KPD_RELEASE_NOTIF (0x08)
92
93
94 /*************************************************************************/
95 /************************** FUNCTIONS PROTOTYPES *************************/
96 /*************************************************************************/
97
98 /**
99 * @name API functions
100 *
101 * API functions declarations.
102 */
103 /*@{*/
104
105 /**
106 * function: kpd_subscribe
107 *
108 * This function is called by the client before any use of the keypad driver services
109 * It is called only once.
110 *
111 * @param subscriber_p Subscriber identification value (OUT).
112 * @param mode Mode used by the keypad client.
113 * @param notified_keys_p Define all the keys the client want to be notified.
114 * @param return_path Return path for key pressed.
115 * @return
116 * - RV_OK if operation is successfull,
117 * - RV_INTERNAL_ERR if
118 * - the max of subscriber is reached,
119 * - the software entity is not started, not yet initialized or initialization has
120 * failed
121 * - RV_INVALID_PARAMETER if number of virtual keys is not correct.
122 * - RV_MEMORY_ERR if memory reach its size limit.
123 *
124 * Message returned: KPD_STATUS_MSG with operation = KPD_SUBSCRIBE_OP.
125 * Available values for status_value are:
126 * - KPD_PROCESS_OK if asynchronous operation is successfull,
127 * - KPD_ERR_KEYS_TABLE if at least one key is not available in the requested mode,
128 * - KPD_ERR_RETURN_PATH_EXISTING if subscriber return path is already defined by
129 * another subscriber,
130 * - KPD_ERR_INTERNAL if an internal error occured.
131 *
132 * @note
133 * - If number of notified key is KPD_NB_PHYSICAL_KEYS, client has not to fulfill
134 * the structure, this will be automatically done by the software entity.
135 */
136 T_RV_RET kpd_subscribe(T_KPD_SUBSCRIBER* subscriber_p,
137 T_KPD_MODE mode,
138 T_KPD_VIRTUAL_KEY_TABLE* notified_keys_p,
139 T_RV_RETURN return_path);
140
141 /**
142 * function: kpd_unsubscribe
143 *
144 * This function unsubscribes a client from the keypad driver.
145 *
146 * @param subscriber_p Subscriber identification value (IN/OUT).
147 * @return
148 * - RV_OK if operation is successfull,
149 * - RV_INVALID_PARAMETER if subscriber identification is incorrect.
150 * - RV_MEMORY_ERR if memory reach its size limit.
151 *
152 * - Message: No message is returned for asynchronous processing.
153 */
154 T_RV_RET kpd_unsubscribe( T_KPD_SUBSCRIBER* subscriber_p);
155
156 /**
157 * function: kpd_define_key_notification
158 *
159 * This function defines notification type for a set of keys.
160 * By default, all the keys are defined as KPD_RELEASE_NOTIF.
161 * It's not mandatory that all the key defined in the notif_key_table be
162 * notified to the subscriber. If at least one key is set in this table but
163 * is not notified to the subscriber, this will have no effect.
164 *
165 * @param subscriber Subscriber identification value.
166 * @param notif_key_table_p Set of keys for level notification definition.
167 * @param notif_level Define level of notification is set for all the keys.
168 * @param long_press_time Time in tenth of seconds before long press time notification (>0).
169 * @param repeat_time Time in tenth of seconds for key repetition (>0).
170 * @return
171 * - RV_OK if operation is successfull
172 * - RV_INVALID_PARAMETER if :
173 * - subscriber identification is incorrect,
174 * - number of virtual keys is incorrect,
175 * - long_press_time = 0 and repeat_level = KPD_LONG_PRESS_NOTIF or KPD_INFINITE_REPEAT_NOTIF,
176 * - repeat_time = 0 and repeat_level = KPD_INFINITE_REPEAT_NOTIF.
177 * - RV_MEMORY_ERR if memory reach its size limit.
178 *
179 * Message returned: KPD_STATUS_MSG with operation = KPD_REPEAT_KEYS_OP.
180 * Available values for status_value are:
181 * - KPD_PROCESS_OK if asynchronous operation is successfull,
182 * - KPD_ERR_KEYS_TABLE if at least one key is not available in the subscriber mode.
183 *
184 * @note - Values for long_press_time and repeat_time are available for the subscriber but
185 * for all the keys defined in repeat mode. So, if a subscriber call the function
186 * twice with different values of long_press_time and repeat_time, only the latest
187 * values will be taken into account.
188 * - If number of notified key is KPD_NB_PHYSICAL_KEYS, client has not to fulfill
189 * the structure, this will be automatically done by the software entity.
190 * - If the client set a key to KPD_INFINITE_REPEAT_NOTIF, it will be notified of
191 * the long key pressed and the repeat press.
192 */
193 T_RV_RET kpd_define_key_notification(T_KPD_SUBSCRIBER subscriber,
194 T_KPD_VIRTUAL_KEY_TABLE* notif_key_table_p,
195 T_KPD_NOTIF_LEVEL notif_level,
196 UINT16 long_press_time,
197 UINT16 repeat_time);
198
199 /**
200 * function: kpd_change_mode
201 *
202 * This function changes the mode for the specific client.
203 *
204 * @param subscriber Subscriber identification value.
205 * @param notified_keys_p Define all the keys the client want to be notified in the new mode.
206 * @param new_mode New mode in which the client want to switch.
207 * @return
208 * - RV_OK if operation is successfull
209 * - RV_INVALID_PARAMETER if :
210 * - subscriber identification is incorrect,
211 * - number of virtual keys is incorrect.
212 * - RV_MEMORY_ERR if memory reach its size limit.
213 *
214 * Message returned: KPD_STATUS_MSG with operation = KPD_CHANGE_MODE_OP.
215 * Available values for status_value are:
216 * - KPD_PROCESS_OK if asynchronous operation is successfull,
217 * - KPD_ERR_KEYS_TABLE if at least one key is not available in the new requested mode,
218 *
219 * @note - Call to this function cancel, for the subscriber, all the repeat mode defined
220 * for the all thekeys with the function kpd_define_repeat_keys.
221 * - If the subscriber was the owner of the keypad, this privilege is cancelled and
222 * keypad is set in multi-notified mode.
223 * - If RV_INVALID_PARAMETER is returned, the current mode for the subscriber is
224 * the old mode and the subscriber is still the keypad owner if it was.
225 * - If number of notified key is KPD_NB_PHYSICAL_KEYS, client has not to fulfill
226 * the structure, this will be automatically done by the software entity.
227 */
228 T_RV_RET kpd_change_mode( T_KPD_SUBSCRIBER subscriber,
229 T_KPD_VIRTUAL_KEY_TABLE* notified_keys_p,
230 T_KPD_MODE new_mode);
231
232 /**
233 * function: kpd_own_keypad
234 *
235 * This function allows a subscriber being the only client to be notified by action
236 * on keypad (less CPU time used).
237 * After this call, the keypad is in the "single notified" state.
238 * This action is cancelled when:
239 * - The function is called with parameter is_keypad_owner to FALSE,
240 * - The subscriber (keypad owner) unsubscribe from keypad,
241 * - The subscriber (keypad owner) changes its mode.
242 *
243 * Note that keypad is in the "multi notified" state if there is no subscriber (particularly
244 * at the keypad initialisation).
245 *
246 * @param subscriber Subscriber identification value.
247 * @param is_keypad_owner Define the state to change.
248 * TRUE: keypad pass in "single notified" state
249 * FALSE: keypad pass in "multi notified" state
250 * @param keys_owner_p Set of keys only notified to the subscriber that call this function.
251 * This is mandatory a subset of the keys defined at subscription.
252 * @return
253 * - RV_OK if operation is successfull
254 * - RV_INVALID_PARAMETER if :
255 * - subscriber identification is incorrect,
256 * - number of virtual keys is incorrect.
257 * - RV_MEMORY_ERR if memory reach its size limit.
258 *
259 * Message returned: KPD_STATUS_MSG with operation = KPD_OWN_KEYPAD_OP.
260 * Available values for status_value are:
261 * - KPD_PROCESS_OK if asynchronous operation is successfull,
262 * - KPD_ERR_KEYS_TABLE if at least one key is not defined in the subscriber mode,
263 * - KPD_ERR_SN_MODE if keypad driver is already in SN mode,
264 * - KPD_ERR_ID_OWNER_KEYPAD if the subscriber try to remove own keypad privilege
265 * whereas it is not the keypad owner.
266 */
267 T_RV_RET kpd_own_keypad( T_KPD_SUBSCRIBER subscriber,
268 BOOL is_keypad_owner,
269 T_KPD_VIRTUAL_KEY_TABLE* keys_owner_p);
270
271 /**
272 * function: kpd_set_key_config
273 *
274 * This function allows setting dynamically a configuration for new or existing virtual keys.
275 * The two tables define a mapping between each entry (new_keys[1] is mapped with reference_keys[1],
276 * new_keys[2] is mapped with reference_keys[2], ...).
277 * The call of this function doesn't change the mode of the client.
278 *
279 * @param subscriber Subscriber identification value.
280 * @param reference_keys_p Set of keys available on keypad in default mode.
281 * @param new_keys_p Set of keys which must map with the reference keys.
282 * @return
283 * - RV_OK if operation is successfull,
284 * - RV_INVALID_PARAMETER if :
285 * - subscriber identification is incorrect,
286 * - at least one reference key is not defined in the default mode,
287 * - number of virtual keys is incorrect (in reference keys or new keys table,
288 * - RV_NOT_SUPPORTED if configurable mode is not supported.
289 * - RV_MEMORY_ERR if memory reach its size limit.
290 *
291 * Message returned: KPD_STATUS_MSG with operation = KPD_SET_CONFIG_MODE_OP.
292 * Available values for status_value are:
293 * - KPD_PROCESS_OK if asynchronous operation is successfull,
294 * - KPD_ERR_CONFIG_MODE_USED if config mode is used by some subscribers.
295 */
296 T_RV_RET kpd_set_key_config(T_KPD_SUBSCRIBER subscriber,
297 T_KPD_VIRTUAL_KEY_TABLE* reference_keys_p,
298 T_KPD_VIRTUAL_KEY_TABLE* new_keys_p);
299
300 /**
301 * function: kpd_get_available_keys
302 *
303 * This function allows knowing all the available keys in default mode.
304 *
305 * @param available_keys_p Set of keys available on keypad in default mode. The structure
306 * must be declared by the caller, and is filled by the function (OUT).
307 * @return RV_OK.
308 */
309 T_RV_RET kpd_get_available_keys( T_KPD_VIRTUAL_KEY_TABLE* available_keys_p);
310
311 /**
312 * function: kpd_get_ascii_key_code
313 *
314 * This function return associated ASCII value to defined key.
315 *
316 * @param key Key identification value.
317 * @param mode Mode in which is defined the link between "key" and "ascii code".
318 * @param ascii_code Associated ASCII code to parameter "key" (OUT).
319 * @return
320 * - RV_OK if operation is successfull,
321 * - RV_INVALID_PARAMETER if :
322 * - mode is different of KPD_DEFAULT_MODE or KPD_ALPHANUMERIC_MODE,
323 * - the key doesn't exist in the defined mode.
324 *
325 * @note If return value is RV_INVALID_PARAMETER, empty string is set in ascii_code_pp variable.
326 */
327 T_RV_RET kpd_get_ascii_key_code( T_KPD_VIRTUAL_KEY_ID key,
328 T_KPD_MODE mode,
329 char** ascii_code_pp);
330
331 /**
332 * function: KP_Init
333 *
334 * This function is defined for backward compatibility with Condat.
335 * It register two functions which notify Condat that Power key is long pressed.
336 * It is used by PWR SWE.
337 *
338 * @param pressed Callback function to notify that Power key is long pressed.
339 * @param released Callback function to notify that Power key is released.
340 */
341 void KP_Init( void(pressed(T_KPD_VIRTUAL_KEY_ID)), void(released(void)) );
342
343 /*@}*/
344
345
346 /*************************************************************************/
347 /************************** MESSAGES DEFINITION **************************/
348 /*************************************************************************/
349
350 /**
351 * The message offset must differ for each SWE in order to have
352 * unique msg_id in the system.
353 */
354 #define KPD_MESSAGES_OFFSET (0x36 << 10)
355
356
357
358 /**
359 * @name KPD_KEY_EVENT_MSG
360 *
361 * This message is sent to a subscriber when a key is pressed or released.
362 *
363 * Message issued by KPD to a subscriber.
364 */
365 /*@{*/
366
367 /** Definition of the key state (pressed or released). */
368 typedef UINT8 T_KPD_KEY_STATE;
369
370 /** Definition of the key press state (first press, long press, repeat press). */
371 typedef UINT8 T_KPD_PRESS_STATE;
372
373
374 /** Information sent to a client for a key notification. */
375 typedef struct { T_KPD_VIRTUAL_KEY_ID virtual_key_id;
376 T_KPD_KEY_STATE state;
377 T_KPD_PRESS_STATE press_state;
378 char* ascii_value_p;
379 } T_KPD_KEY_INFO;
380
381 /** Allowed values for T_KPD_KEY_STATE type. */
382 #define KPD_KEY_PRESSED (0)
383 /** Allowed values for T_KPD_KEY_STATE type. */
384 #define KPD_KEY_RELEASED (1)
385
386 /** Allowed value for T_KPD_PRESS_STATE type. */
387 #define KPD_FIRST_PRESS (0)
388 /** Allowed value for T_KPD_PRESS_STATE type. */
389 #define KPD_LONG_PRESS (1)
390 /** Allowed value for T_KPD_PRESS_STATE type. */
391 #define KPD_REPEAT_PRESS (2)
392 /** Allowed value for T_KPD_PRESS_STATE type (when state==KPD_KEY_RELEASED). */
393 #define KPD_INSIGNIFICANT_VALUE (0xff)
394
395 /** Message ID. */
396 #define KPD_KEY_EVENT_MSG (KPD_MESSAGES_OFFSET | 0x001)
397
398 /** Message structure. */
399 typedef struct
400 {
401 /** Message header. */
402 T_RV_HDR hdr;
403
404 /** Informations about key event. */
405 T_KPD_KEY_INFO key_info;
406
407 } T_KPD_KEY_EVENT_MSG;
408 /*@}*/
409
410
411 /**
412 * @name KPD_STATUS_MSG
413 *
414 * Status message.
415 *
416 * Message issued by KPD to a subscriber.
417 * This message is used to return the status of an asynchronous process
418 * requested by a subscriber.
419 */
420 /*@{*/
421
422 /* Allowed values for 'operation" field */
423 #define KPD_SUBSCRIBE_OP 1
424 #define KPD_REPEAT_KEYS_OP 2
425 #define KPD_CHANGE_MODE_OP 3
426 #define KPD_OWN_KEYPAD_OP 4
427 #define KPD_SET_CONFIG_MODE_OP 5
428
429 /* Available values for "status_value" field */
430 /* This define value is set when asynchronous process is successfull. */
431 #define KPD_PROCESS_OK 1
432 /* This define value is set in a status message (KPD_STATUS_MSG) when a client try to
433 subscribe whereas keypad is in single-notified mode. Subscription
434 is so rejected. */
435 #define KPD_ERR_SN_MODE 2
436 /* This defined value is set in a status message (KPD_STATUS_MSG) when a client try to
437 modify configuration mode whereas this mode is already used. */
438 #define KPD_ERR_CONFIG_MODE_USED 3
439 /* This defined value is set in a status message (KPD_STATUS_MSG) when a client try to
440 change keypad state from single-notified to multi-notified whereas it is not
441 the keypad owner. */
442 #define KPD_ERR_ID_OWNER_KEYPAD 4
443 /* This defined value is set in a status message (KPD_STATUS_MSG) when a client
444 defines a key table which is not correct. */
445 #define KPD_ERR_KEYS_TABLE 5
446 /* This defined value is set in a status message (KPD_STATUS_MSG) when a client
447 try to subscribe to the keypad driver with a return path which is already
448 defined by another subscriber. */
449 #define KPD_ERR_RETURN_PATH_EXISTING 6
450 /* This defined value is set in a status message (KPD_STATUS_MSG) when an internal
451 error cause the failure of the process. */
452 #define KPD_ERR_INTERNAL 7
453
454
455 /** Message ID. */
456 #define KPD_STATUS_MSG (KPD_MESSAGES_OFFSET | 0x002)
457
458 /** Message structure. */
459 typedef struct
460 {
461 /** Message header. */
462 T_RV_HDR hdr;
463
464 /** Operation. */
465 UINT8 operation;
466
467 /** Return status value. */
468 UINT8 status_value;
469
470 } T_KPD_STATUS_MSG;
471 /*@}*/
472
473 #endif /* #ifndef _KPD_API_H_ */