intertask_interface.h 7.7 KB
Newer Older
1 2 3 4 5
/*
 * Licensed to the OpenAirInterface (OAI) Software Alliance under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The OpenAirInterface Software Alliance licenses this file to You under
6
 * the OAI Public License, Version 1.1  (the "License"); you may not use this file
7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
 * except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.openairinterface.org/?page_id=698
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *-------------------------------------------------------------------------------
 * For more information about the OpenAirInterface (OAI) Software Alliance:
 *      contact@openairinterface.org
 */

Cedric Roux's avatar
 
Cedric Roux committed
22 23 24 25 26 27
/** @defgroup _intertask_interface_impl_ Intertask Interface Mechanisms
 * Implementation
 * @ingroup _ref_implementation_
 * @{
 */

28
#include <sys/epoll.h>
29

Cedric Roux's avatar
 
Cedric Roux committed
30 31 32 33 34 35 36
#ifndef INTERTASK_INTERFACE_H_
#define INTERTASK_INTERFACE_H_

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

37
#include "intertask_interface_conf.h"
Cedric Roux's avatar
 
Cedric Roux committed
38 39
#include "intertask_interface_types.h"

Cedric Roux's avatar
Cedric Roux committed
40 41 42 43 44 45 46
#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))
47

Cedric Roux's avatar
 
Cedric Roux committed
48 49 50 51
/* Make the message number platform specific */
typedef unsigned long message_number_t;
#define MESSAGE_NUMBER_SIZE (sizeof(unsigned long))

52
typedef enum message_priorities_e {
53 54 55 56 57 58 59
  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,
60
} message_priorities_t;
Cedric Roux's avatar
 
Cedric Roux committed
61 62

typedef struct message_info_s {
63 64 65 66 67 68
  task_id_t id;
  message_priorities_t priority;
  /* Message payload size */
  MessageHeaderSize size;
  /* Printable name */
  const char * const name;
Cedric Roux's avatar
 
Cedric Roux committed
69 70
} message_info_t;

71
typedef enum task_priorities_e {
72 73 74 75 76 77 78
  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,
79
} task_priorities_t;
Cedric Roux's avatar
 
Cedric Roux committed
80

81
typedef struct task_info_s {
82 83 84 85 86 87
  thread_id_t thread;
  task_id_t   parent_task;
  task_priorities_t priority;
  unsigned int queue_size;
  /* Printable name */
  const char * const name;
88 89
} task_info_t;

90 91 92 93 94 95 96
/** \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
97 98 99 100
/** \brief Send a broadcast message to every task
 \param message_p Pointer to the message to send
 @returns < 0 on failure, 0 otherwise
 **/
101
int itti_send_broadcast_message(MessageDef *message_p);
Cedric Roux's avatar
 
Cedric Roux committed
102 103 104 105 106 107 108

/** \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
 **/
109
int itti_send_msg_to_task(task_id_t task_id, instance_t instance, MessageDef *message);
Cedric Roux's avatar
 
Cedric Roux committed
110

111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130
/** \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
131 132 133 134 135
/** \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
 **/
136
void itti_receive_msg(task_id_t task_id, MessageDef **received_msg);
Cedric Roux's avatar
 
Cedric Roux committed
137

138
/** \brief Try to retrieves a message in the queue associated to task_id.
Cedric Roux's avatar
 
Cedric Roux committed
139 140 141
 \param task_id Task ID of the receiving task
 \param received_msg Pointer to the allocated message
 **/
142
void itti_poll_msg(task_id_t task_id, MessageDef **received_msg);
Cedric Roux's avatar
 
Cedric Roux committed
143 144 145 146 147 148 149

/** \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
 **/
150
int itti_create_task(task_id_t task_id,
Cedric Roux's avatar
Cedric Roux committed
151 152
                     void *(*start_routine) (void *),
                     void *args_p);
Cedric Roux's avatar
 
Cedric Roux committed
153

154 155 156 157 158
/** \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);

159 160 161 162 163
/** \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
164 165 166
/** \brief Mark the task as in ready state
 * \param task_id task to mark as ready
 **/
167 168
void itti_mark_task_ready(task_id_t task_id);

169 170 171 172
/** \brief Exit the current task.
 **/
void itti_exit_task(void);

173 174 175 176
/** \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
177 178 179 180

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

Cedric Roux's avatar
Cedric Roux committed
183 184 185
/** \brief Return the printable string associated with a task id
 * \param thread_id Id of the task
 **/
186
const char *itti_get_task_name(task_id_t task_id);
Cedric Roux's avatar
Cedric Roux committed
187

Cedric Roux's avatar
 
Cedric Roux committed
188
/** \brief Alloc and memset(0) a new itti message.
189 190 191
 * \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
192
 **/
193
MessageDef *itti_alloc_new_message(
194 195
  task_id_t         origin_task_id,
  MessagesIds       message_id);
Cedric Roux's avatar
Cedric Roux committed
196 197 198 199 200 201 202

/** \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
 **/
203
MessageDef *itti_alloc_new_message_sized(
204 205 206
  task_id_t         origin_task_id,
  MessagesIds       message_id,
  MessageHeaderSize size);
Cedric Roux's avatar
 
Cedric Roux committed
207

208 209 210 211 212 213 214 215 216
/** \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
217

218
void *itti_malloc(task_id_t origin_task_id, task_id_t destination_task_id, ssize_t size);
219

220
int itti_free(task_id_t task_id, void *ptr);
221

Cedric Roux's avatar
 
Cedric Roux committed
222 223
#endif /* INTERTASK_INTERFACE_H_ */
/* @} */