[23] | 1 | /* |
---|
[669] | 2 | * alarm.h - timer based kernel alarm specification |
---|
[23] | 3 | * |
---|
[669] | 4 | * Author Alain Greiner (2016,2017,2018,2019,2020) |
---|
[23] | 5 | * |
---|
[669] | 6 | * Copyright (c) UPMC Sorbonne Universites |
---|
| 7 | * |
---|
| 8 | * This file is part of ALMOS-MKH. |
---|
| 9 | * |
---|
| 10 | * ALMOS-MKH is free software; you can redistribute it and/or modify it |
---|
[23] | 11 | * under the terms of the GNU General Public License as published by |
---|
| 12 | * the Free Software Foundation; version 2.0 of the License. |
---|
| 13 | * |
---|
[669] | 14 | * ALMOS-MKH is distributed in the hope that it will be useful, but |
---|
[23] | 15 | * WITHOUT ANY WARRANTY; without even the implied warranty of |
---|
| 16 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
---|
| 17 | * General Public License for more details. |
---|
| 18 | * |
---|
| 19 | * You should have received a copy of the GNU General Public License |
---|
[669] | 20 | * along with ALMOS-MKH; if not, write to the Free Software Foundation, |
---|
[23] | 21 | * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA |
---|
| 22 | */ |
---|
| 23 | |
---|
| 24 | |
---|
[669] | 25 | #ifndef _ALARM_H_ |
---|
| 26 | #define _ALARM_H_ |
---|
| 27 | |
---|
| 28 | #include <hal_kernel_types.h> |
---|
[23] | 29 | #include <list.h> |
---|
| 30 | |
---|
[669] | 31 | /**** Forward declarations ****/ |
---|
[23] | 32 | |
---|
[669] | 33 | struct thread_s; |
---|
[23] | 34 | |
---|
[669] | 35 | /****************************************************************************************** |
---|
| 36 | * This structure defines a generic, timer based, kernel alarm. |
---|
| 37 | * |
---|
[683] | 38 | * - An alarm is attached to a given thread, and the alarm descriptor is embedded in the |
---|
[669] | 39 | * thread descriptor. A client thread can use the alarm_start() function to dynamically |
---|
| 40 | * activate the alarm. It can use the alarm_stop() function to desactivate this alarm. |
---|
| 41 | * - This kernel alarm is generic, as the alarm handler (executed when the alarm rings), |
---|
[683] | 42 | * and the handler arguments are defined by two pointers: <func_ptr> and <args_xp>. |
---|
[669] | 43 | * - When an alarm is created by a client thread, it is registered in the list of alarms |
---|
| 44 | * rooted in the core running the client thread. When it is stopped, the alarm is simply |
---|
| 45 | * removed from this list. |
---|
[683] | 46 | * - When creating an alarm with the alarm_start() function, the client thread must define |
---|
| 47 | * an absolute date (in cycles), the func_ptr pointer, and the args_xp extended pointer. |
---|
[669] | 48 | * - The list of alarms is ordered by increasing dates. At each TICK received by a core, |
---|
| 49 | * the date of the first registered alarm is compared to the current date (in the |
---|
| 50 | * core_clock() function). The alarm handler is executed when current_date >= alarm_date. |
---|
[683] | 51 | * - It is the handler responsability to stop and delete a ringing alarm using the |
---|
| 52 | * alarm_stop() function, or update the alarm date using the alarm_update() function. |
---|
| 53 | * - The three alarm_start(), alarm_stop(), and alarm_update() access functions use |
---|
| 54 | * the lock protecting the alarms list to handle concurrent accesses. These functions |
---|
| 55 | * use extended pointers to access the alarm list, and can be called by a thread |
---|
| 56 | * running in any cluster. |
---|
[669] | 57 | * |
---|
[683] | 58 | * This embedded alarm mechanism is used by: |
---|
| 59 | * 1. the socket_accept(), socket_connect(), socket_send(), socket_close() functions, |
---|
| 60 | * to implement the TCP retransmission machanism. |
---|
| 61 | * 2. the sys_thread_sleep() function, to implement the "sleep" mechanism. |
---|
[669] | 62 | ******************************************************************************************/ |
---|
[23] | 63 | |
---|
[669] | 64 | typedef struct alarm_s |
---|
[23] | 65 | { |
---|
[683] | 66 | bool_t linked; /*! active when true (i.e linked to the core list) */ |
---|
[669] | 67 | cycle_t date; /*! absolute date for handler execution */ |
---|
| 68 | void * func_ptr; /*! local pointer on alarm handler function */ |
---|
| 69 | xptr_t args_xp; /*! local pointer on handler arguments */ |
---|
[683] | 70 | list_entry_t list; /*! set of active alarms attached to the same core */ |
---|
[669] | 71 | } |
---|
| 72 | alarm_t; |
---|
[23] | 73 | |
---|
[669] | 74 | /******************************************************************************************* |
---|
| 75 | * This defines the generic prototype for an alarm handler. |
---|
| 76 | ******************************************************************************************/ |
---|
[23] | 77 | |
---|
[669] | 78 | typedef void (alarm_handler_t) ( xptr_t args_xp ); |
---|
[23] | 79 | |
---|
[669] | 80 | /******************************************************************************************* |
---|
[683] | 81 | * This function initialises the alarm state to "inactive". |
---|
| 82 | ******************************************************************************************* |
---|
| 83 | * @ alarm : local pointer on alarm. |
---|
| 84 | ******************************************************************************************/ |
---|
| 85 | void alarm_init( alarm_t * alarm ); |
---|
| 86 | |
---|
| 87 | /******************************************************************************************* |
---|
[669] | 88 | * This function initializes the alarm descriptor embedded in the thread identified by the |
---|
[683] | 89 | * <thread_xp> argument from the <date>, <func_ptr>, <args_ptr> arguments, and registers |
---|
| 90 | * this alarm in the ordered list rooted in the core running this thread. |
---|
| 91 | * It takes the lock protecting the alarms list against concurrent accesses. |
---|
[669] | 92 | ******************************************************************************************* |
---|
[683] | 93 | * @ thread_xp : extended pointer on the target thread. |
---|
[669] | 94 | * @ date : absolute date (in cycles). |
---|
| 95 | * @ func_ptr : local pointer on the handler to execute when the alarm rings. |
---|
| 96 | * @ args_xp : extended pointer on the handler arguments. |
---|
| 97 | ******************************************************************************************/ |
---|
[683] | 98 | void alarm_start( xptr_t thread_xp, |
---|
| 99 | cycle_t date, |
---|
| 100 | void * func_ptr, |
---|
| 101 | xptr_t args_xp ); |
---|
[23] | 102 | |
---|
[669] | 103 | /******************************************************************************************* |
---|
| 104 | * This function updates the date of the alarm attached to the thread identified by the |
---|
| 105 | * <thread> argument. The list of alarms rooted in the core running the client thread |
---|
| 106 | * is modified to respect the absolute dates ordering. |
---|
[683] | 107 | * It takes the lock protecting the alarms list against concurrent accesses. |
---|
[669] | 108 | ******************************************************************************************* |
---|
[683] | 109 | * @ thread_xp : extended pointer on the target thread. |
---|
[669] | 110 | * @ new_date : absolute new date (in cycles). |
---|
| 111 | ******************************************************************************************/ |
---|
[683] | 112 | void alarm_update( xptr_t thread_xp, |
---|
| 113 | cycle_t new_date ); |
---|
[23] | 114 | |
---|
[669] | 115 | /******************************************************************************************* |
---|
| 116 | * This function unlink an alarm identified by the <thread> argument from the list of |
---|
| 117 | * alarms rooted in the core descriptor. |
---|
[683] | 118 | * It takes the lock protecting the alarms list against concurrent accesses. |
---|
[669] | 119 | ******************************************************************************************* |
---|
[683] | 120 | * @ thread_xp : extended pointer on the target thread. |
---|
[669] | 121 | ******************************************************************************************/ |
---|
[683] | 122 | void alarm_stop( xptr_t thread_xp ); |
---|
[23] | 123 | |
---|
| 124 | |
---|
[669] | 125 | #endif /* _ALARM_H_ */ |
---|