intertask_interface.h 8.08 KB
Newer Older
Cedric Roux's avatar
 
Cedric Roux committed
1
/*******************************************************************************
ghaddab's avatar
ghaddab committed
2
3
    OpenAirInterface 
    Copyright(c) 1999 - 2014 Eurecom
Cedric Roux's avatar
 
Cedric Roux committed
4

ghaddab's avatar
ghaddab committed
5
6
7
8
    OpenAirInterface is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.
Cedric Roux's avatar
 
Cedric Roux committed
9
10


ghaddab's avatar
ghaddab committed
11
12
13
14
    OpenAirInterface is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.
Cedric Roux's avatar
 
Cedric Roux committed
15

ghaddab's avatar
ghaddab committed
16
17
18
19
    You should have received a copy of the GNU General Public License
    along with OpenAirInterface.The full GNU General Public License is 
   included in this distribution in the file called "COPYING". If not, 
   see <http://www.gnu.org/licenses/>.
Cedric Roux's avatar
 
Cedric Roux committed
20
21

  Contact Information
ghaddab's avatar
ghaddab committed
22
23
24
25
  OpenAirInterface Admin: openair_admin@eurecom.fr
  OpenAirInterface Tech : openair_tech@eurecom.fr
  OpenAirInterface Dev  : openair4g-devel@eurecom.fr
  
ghaddab's avatar
ghaddab committed
26
  Address      : Eurecom, Campus SophiaTech, 450 Route des Chappes, CS 50193 - 06904 Biot Sophia Antipolis cedex, FRANCE
Cedric Roux's avatar
 
Cedric Roux committed
27

ghaddab's avatar
ghaddab committed
28
 *******************************************************************************/
Cedric Roux's avatar
 
Cedric Roux committed
29
30
31
32
33
34
35

/** @defgroup _intertask_interface_impl_ Intertask Interface Mechanisms
 * Implementation
 * @ingroup _ref_implementation_
 * @{
 */

36
#include <sys/epoll.h>
37

38
39
40
41
#ifdef RTAI
# include <rtai_sem.h>
#endif

Cedric Roux's avatar
 
Cedric Roux committed
42
43
44
45
46
47
48
#ifndef INTERTASK_INTERFACE_H_
#define INTERTASK_INTERFACE_H_

#include <stdio.h>
#include <stdlib.h>
#include <stdint.h>

49
#include "intertask_interface_conf.h"
Cedric Roux's avatar
 
Cedric Roux committed
50
51
#include "intertask_interface_types.h"

Cedric Roux's avatar
Cedric Roux committed
52
53
54
55
56
57
58
#define ITTI_MSG_ID(mSGpTR)                 ((mSGpTR)->ittiMsgHeader.messageId)
#define ITTI_MSG_ORIGIN_ID(mSGpTR)          ((mSGpTR)->ittiMsgHeader.originTaskId)
#define ITTI_MSG_DESTINATION_ID(mSGpTR)     ((mSGpTR)->ittiMsgHeader.destinationTaskId)
#define ITTI_MSG_INSTANCE(mSGpTR)           ((mSGpTR)->ittiMsgHeader.instance)
#define ITTI_MSG_NAME(mSGpTR)               itti_get_message_name(ITTI_MSG_ID(mSGpTR))
#define ITTI_MSG_ORIGIN_NAME(mSGpTR)        itti_get_task_name(ITTI_MSG_ORIGIN_ID(mSGpTR))
#define ITTI_MSG_DESTINATION_NAME(mSGpTR)   itti_get_task_name(ITTI_MSG_DESTINATION_ID(mSGpTR))
59

Cedric Roux's avatar
 
Cedric Roux committed
60
61
62
63
/* Make the message number platform specific */
typedef unsigned long message_number_t;
#define MESSAGE_NUMBER_SIZE (sizeof(unsigned long))

64
typedef enum message_priorities_e {
Cedric Roux's avatar
 
Cedric Roux committed
65
66
67
68
69
70
71
    MESSAGE_PRIORITY_MAX       = 100,
    MESSAGE_PRIORITY_MAX_LEAST = 85,
    MESSAGE_PRIORITY_MED_PLUS  = 70,
    MESSAGE_PRIORITY_MED       = 55,
    MESSAGE_PRIORITY_MED_LEAST = 40,
    MESSAGE_PRIORITY_MIN_PLUS  = 25,
    MESSAGE_PRIORITY_MIN       = 10,
72
} message_priorities_t;
Cedric Roux's avatar
 
Cedric Roux committed
73
74
75

typedef struct message_info_s {
    task_id_t id;
76
    message_priorities_t priority;
Cedric Roux's avatar
 
Cedric Roux committed
77
78
79
    /* Message payload size */
    MessageHeaderSize size;
    /* Printable name */
80
    const char * const name;
Cedric Roux's avatar
 
Cedric Roux committed
81
82
} message_info_t;

83
typedef enum task_priorities_e {
Cedric Roux's avatar
 
Cedric Roux committed
84
85
86
87
88
89
90
    TASK_PRIORITY_MAX       = 100,
    TASK_PRIORITY_MAX_LEAST = 85,
    TASK_PRIORITY_MED_PLUS  = 70,
    TASK_PRIORITY_MED       = 55,
    TASK_PRIORITY_MED_LEAST = 40,
    TASK_PRIORITY_MIN_PLUS  = 25,
    TASK_PRIORITY_MIN       = 10,
91
} task_priorities_t;
Cedric Roux's avatar
 
Cedric Roux committed
92

93
94
typedef struct task_info_s {
    thread_id_t thread;
95
    task_id_t   parent_task;
96
97
    task_priorities_t priority;
    unsigned int queue_size;
98
99
100
101
    /* Printable name */
    const char * const name;
} task_info_t;

102
103
104
105
106
107
108
/** \brief Update the itti LTE time reference for messages
 \param current reference frame
 \param current reference slot
 @returns < 0 on failure, 0 otherwise
 **/
void itti_update_lte_time(uint32_t frame, uint8_t slot);

Cedric Roux's avatar
 
Cedric Roux committed
109
110
111
112
/** \brief Send a broadcast message to every task
 \param message_p Pointer to the message to send
 @returns < 0 on failure, 0 otherwise
 **/
113
int itti_send_broadcast_message(MessageDef *message_p);
Cedric Roux's avatar
 
Cedric Roux committed
114
115
116
117
118
119
120

/** \brief Send a message to a task (could be itself)
 \param task_id Task ID
 \param instance Instance of the task used for virtualization
 \param message Pointer to the message to send
 @returns -1 on failure, 0 otherwise
 **/
121
int itti_send_msg_to_task(task_id_t task_id, instance_t instance, MessageDef *message);
Cedric Roux's avatar
 
Cedric Roux committed
122

123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
/** \brief Add a new fd to monitor.
 * NOTE: it is up to the user to read data associated with the fd
 *  \param task_id Task ID of the receiving task
 *  \param fd The file descriptor to monitor
 **/
void itti_subscribe_event_fd(task_id_t task_id, int fd);

/** \brief Remove a fd from the list of fd to monitor
 *  \param task_id Task ID of the task
 *  \param fd The file descriptor to remove
 **/
void itti_unsubscribe_event_fd(task_id_t task_id, int fd);

/** \brief Return the list of events excluding the fd associated with itti
 *  \param task_id Task ID of the task
 *  \param events events list
 *  @returns number of events to handle
 **/
int itti_get_events(task_id_t task_id, struct epoll_event **events);

Cedric Roux's avatar
 
Cedric Roux committed
143
144
145
146
147
/** \brief Retrieves a message in the queue associated to task_id.
 * If the queue is empty, the thread is blocked till a new message arrives.
 \param task_id Task ID of the receiving task
 \param received_msg Pointer to the allocated message
 **/
148
void itti_receive_msg(task_id_t task_id, MessageDef **received_msg);
Cedric Roux's avatar
 
Cedric Roux committed
149

150
/** \brief Try to retrieves a message in the queue associated to task_id.
Cedric Roux's avatar
 
Cedric Roux committed
151
152
153
 \param task_id Task ID of the receiving task
 \param received_msg Pointer to the allocated message
 **/
154
void itti_poll_msg(task_id_t task_id, MessageDef **received_msg);
Cedric Roux's avatar
 
Cedric Roux committed
155
156
157
158
159
160
161

/** \brief Start thread associated to the task
 * \param task_id task to start
 * \param start_routine entry point for the task
 * \param args_p Optional argument to pass to the start routine
 * @returns -1 on failure, 0 otherwise
 **/
162
int itti_create_task(task_id_t task_id,
Cedric Roux's avatar
Cedric Roux committed
163
164
                     void *(*start_routine) (void *),
                     void *args_p);
Cedric Roux's avatar
 
Cedric Roux committed
165

knopp's avatar
   
knopp committed
166
//#ifdef RTAI
167
168
169
170
/** \brief Mark the task as a real time task
 * \param task_id task to mark as real time
 **/
void itti_set_task_real_time(task_id_t task_id);
knopp's avatar
   
knopp committed
171
//#endif
172

173
174
175
176
177
/** \brief Indicates to ITTI if newly created tasks should wait for all tasks to be ready
 * \param wait_tasks non 0 to make new created tasks to wait, 0 to let created tasks to run
 **/
void itti_wait_ready(int wait_tasks);

Cedric Roux's avatar
 
Cedric Roux committed
178
179
180
/** \brief Mark the task as in ready state
 * \param task_id task to mark as ready
 **/
181
182
void itti_mark_task_ready(task_id_t task_id);

183
184
185
186
/** \brief Exit the current task.
 **/
void itti_exit_task(void);

187
188
189
190
/** \brief Indicate that the task is completed and initiate termination of all tasks.
 * \param task_id task that is completed
 **/
void itti_terminate_tasks(task_id_t task_id);
Cedric Roux's avatar
 
Cedric Roux committed
191
192
193
194

/** \brief Return the printable string associated with the message
 * \param message_id Id of the message
 **/
195
const char *itti_get_message_name(MessagesIds message_id);
Cedric Roux's avatar
 
Cedric Roux committed
196

Cedric Roux's avatar
Cedric Roux committed
197
198
199
/** \brief Return the printable string associated with a task id
 * \param thread_id Id of the task
 **/
200
const char *itti_get_task_name(task_id_t task_id);
Cedric Roux's avatar
Cedric Roux committed
201

Cedric Roux's avatar
 
Cedric Roux committed
202
/** \brief Alloc and memset(0) a new itti message.
203
204
205
 * \param origin_task_id Task ID of the sending task
 * \param message_id Message ID
 * @returns NULL in case of failure or newly allocated mesage ref
Cedric Roux's avatar
 
Cedric Roux committed
206
 **/
207
inline MessageDef *itti_alloc_new_message(
Cedric Roux's avatar
Cedric Roux committed
208
209
210
211
212
213
214
215
216
217
218
219
220
    task_id_t         origin_task_id,
    MessagesIds       message_id);

/** \brief Alloc and memset(0) a new itti message.
 * \param origin_task_id Task ID of the sending task
 * \param message_id Message ID
 * \param size size of the payload to send
 * @returns NULL in case of failure or newly allocated mesage ref
 **/
inline MessageDef *itti_alloc_new_message_sized(
    task_id_t         origin_task_id,
    MessagesIds       message_id,
    MessageHeaderSize size);
Cedric Roux's avatar
 
Cedric Roux committed
221

222
223
224
225
226
227
228
229
230
/** \brief handle signals and wait for all threads to join when the process complete.
 * This function should be called from the main thread after having created all ITTI tasks.
 **/
void itti_wait_tasks_end(void);

/** \brief Send a termination message to all tasks.
 * \param task_id task that is broadcasting the message.
 **/
void itti_send_terminate_message(task_id_t task_id);
Cedric Roux's avatar
 
Cedric Roux committed
231

232
void *itti_malloc(task_id_t origin_task_id, task_id_t destination_task_id, ssize_t size);
233

234
int itti_free(task_id_t task_id, void *ptr);
235

Cedric Roux's avatar
 
Cedric Roux committed
236
237
#endif /* INTERTASK_INTERFACE_H_ */
/* @} */