/******************************************************************************
*
* Copyright (C) 2018 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at:
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* 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.
*
*****************************************************************************
* Originally developed and contributed by Ittiam Systems Pvt. Ltd, Bangalore
*/
/*****************************************************************************/
/* */
/* File Name : osal.h */
/* */
/* Description : This file contains all the necessary OSAL Constants, */
/* Enums, Structures and API declarations. */
/* */
/* List of Functions : None */
/* */
/* Issues / Problems : None */
/* */
/* Revision History : */
/* */
/* DD MM YYYY Author(s) Changes (Describe the changes made) */
/* 03 03 2006 Ittiam Draft */
/* */
/*****************************************************************************/
#ifndef OSAL_H
#define OSAL_H
/* C linkage specifiers for C++ declarations. */
#ifdef __cplusplus
extern "C"
{
#endif /* __cplusplus */
/*****************************************************************************/
/* Constants */
/*****************************************************************************/
/* OSAL handle size */
#define OSAL_HANDLE_SIZE 40
/* Number of select entries */
#define OSAL_SELECT_MAX 20
/* OSAL Return Status */
#define OSAL_SUCCESS 0
#define OSAL_ERROR -1
#define OSAL_NOT_SUPPORTED -2
#define OSAL_TIMEOUT -3
/* OSAL thread priority levels. */
/* OSAL_PRIORITY_1 represents MINIMUM, */
/* OSAL_PRIORITY_10 represents MAXIMUM, */
/* OSAL_PRIORITY_DEFAULT represnts DEFAULT SYSTEM PRIROTIY LEVEL */
#define OSAL_PRIORITY_DEFAULT 0
#define OSAL_PRIORITY_1 1
#define OSAL_PRIORITY_2 2
#define OSAL_PRIORITY_3 3
#define OSAL_PRIORITY_4 4
#define OSAL_PRIORITY_5 5
#define OSAL_PRIORITY_6 6
#define OSAL_PRIORITY_7 7
#define OSAL_PRIORITY_8 8
#define OSAL_PRIORITY_9 9
#define OSAL_PRIORITY_10 10
/* OSAL socket option levels */
#define OSAL_SOL_SOCKET 10000
#define OSAL_IPPROTO_IP 10001
/* OSAL socket options */
#define OSAL_BROADCAST 1000
#define OSAL_REUSEADDR 1001
#define OSAL_KEEPALIVE 1002
#define OSAL_LINGER 1003
#define OSAL_OOBINLINE 1004
#define OSAL_SNDBUF 1005
#define OSAL_RCVBUF 1006
#define OSAL_RCVTIMEO 1007
#define OSAL_SNDTIMEO 1008
#define OSAL_ADD_MEMBERSHIP 1009
#define OSAL_DROP_MEMBERSHIP 1010
#define OSAL_TTL 1011
#define OSAL_DSCP 1012
#define OSAL_MULTICAST_TTL 1013
#define OSAL_ADDSRC_MEMBERSHIP 1014
#define OSAL_DROPSRC_MEMBERSHIP 1015
/*****************************************************************************/
/* Enums */
/*****************************************************************************/
/* Protocols supported. */
typedef enum
{
OSAL_TCP, /* Address family = AF_INET, Type = SOCK_STREAM, Protocol = 0 */
OSAL_UDP /* Address family = AF_INET, Type = SOCK_DGRAM, Protocol = 0 */
} OSAL_PROTOCOL_T;
/* File Descriptor types. Used to specify the type of activity to check on */
/* a socket. */
typedef enum
{
OSAL_READ_FD,
OSAL_WRITE_FD,
OSAL_EXCEPT_FD
} OSAL_FD_TYPE_T;
/* Scheduling policies supported */
typedef enum
{
OSAL_SCHED_RR,
OSAL_SCHED_FIFO,
OSAL_SCHED_OTHER
} OSAL_SCHED_POLICY_TYPE_T;
/*****************************************************************************/
/* Structures */
/*****************************************************************************/
/* Structure to initialize OSAL */
typedef struct
{
/* Handle of memory manager being used. NULL is a valid argument.*/
void *mmr_handle;
/* Call back API to be called during allocation */
void *(*osal_alloc)(void *mmr_handle, UWORD32 size);
/* Call back API for freeing */
void (*osal_free)(void *mmr_handle, void *mem);
} osal_cb_funcs_t;
/* The structure (osal_mbox_attr_t) contains the attributes of the thread */
/* which are passed to osal_mbox_create() API. The created Mail box has */
/* attributes specified using the structure variable. */
typedef struct
{
void *thread_handle; /* Thread to be associated with mail box. */
STRWORD8 *name; /* NULL terminated string name for mail box */
UWORD32 msg_size; /* Length of each message. */
UWORD32 mbx_len; /* Maximum number of messages. */
} osal_mbox_attr_t;
/* The structure (osal_sem_attr_t) contains the attributes of the semaphore */
/* which are passed to osal_sem_create() API. The Semaphore attributes like */
/* initial value of semaphore. */
typedef struct
{
WORD32 value;
} osal_sem_attr_t;
/* The Structure (osal_thread_attr_t) contains the attributes of the thread */
/* which are passed to osal_thread_create() API. The created thread has */
/* attributes specified using the structure variable. */
typedef struct
{
/* Function from where thread execution starts */
void *thread_func;
/* Parameters for thread function. */
void *thread_param;
/* Stack size in bytes. For default value, set to '0' */
UWORD32 stack_size;
/* This attribute specifies a pre-allocated block of size 'stack_size' */
/* to be used for the task's private stack. For default value, set to */
/* 'NULL'. */
void *stack_addr;
/* NULL terminated string name for thread. For default value, set to */
/* 'NULL'. */
WORD8 *name;
/* Flag determining whether to use OSAL Thread priority mapping or not. */
/* Value set to 1 - use OSAL thread priority mapping. */
/* Value set to 0 - Direct value set as thread priority */
WORD32 priority_map_flag;
/* Priority range shall be considered + ve values for increasing */
/* priority and negative values for decreasing priority. The range shall */
/* be mapped to specific OS range internally through OSAL. For default */
/* value, set to '0'. */
WORD32 priority;
/* Exit return value on which thread shall exit */
WORD32 exit_code;
/* Scheduling policy of the thread */
OSAL_SCHED_POLICY_TYPE_T sched_policy;
/* Mask to specify on which cores the thread can run */
ULWORD64 core_affinity_mask;
/* Specifies on which group of processors the thread can run */
WORD16 group_num;
} osal_thread_attr_t;
/* The structure (osal_socket_attr_t) contains the attributes of the socket */
/* which are to be specified during socket creation. */
typedef struct
{
OSAL_PROTOCOL_T protocol;
} osal_socket_attr_t;
/* The structure (osal_sockaddr_t) is used to uniquely determine a socket in */
/* the network. The socket can be addressed using IP address and port number.*/
typedef struct
{
WORD8 ip_addr[16];
UWORD16 port;
} osal_sockaddr_t;
/* The structure contains the select engine thread parameters like thread */
/* name thread priority etc. */
typedef struct
{
/* Flag determining whether to use OSAL Thread priority mapping or not. */
/* Value set to 1 - use OSAL thread priority mapping. */
/* Value set to 0 - Direct value set as thread priority */
WORD32 priority_map_flag;
/* Priority range shall be considered + ve values for increasing */
/* priority and negative values for decreasing priority. The range shall */
/* be mapped to specific OS range internally through OSAL. For default */
/* value, set to '0'. */
WORD32 priority;
/* NULL terminated string name for thread. For default value, set to */
/* 'NULL'. */
WORD8 *name;
/* Timeout for thread sleep in micro seconds */
UWORD32 select_timeout;
/* Timeout for SELECT system called by osal library in micro seconds */
UWORD32 select_poll_interval;
} osal_select_engine_attr_t;
/* The structure used to register sockets to select engine. This structure */
/* has to be updated for each socket handle and select register has to be */
/* done. Currently registration is supported one at a time. */
/* Note: Function 'init' is assumed to return the socket handle. */
typedef struct osal_select_entry_t
{
/* Socket handle to be registered. */
void *socket_handle;
/* Activity to select for. */
OSAL_FD_TYPE_T type;
/* Call back called before doing select. The function init is assumed to */
/* return the socket handle. In case of NULL being returning by this */
/* function, The socket will be unregistered */
void *(*init)(void *);
/* Argument to init function */
void *init_param;
/* Call back function on select success */
WORD32 (*call_back)(void *socket_handle, void *call_back_param);
/* Call back function parameters */
void *call_back_param;
/* Call back called when the socket is unregistered. If set to NULL, */
/* this will not be called. The socket that has been registered is the */
/* first argument, the second argument will be terminate_param */
void (*terminate)(void *, void *);
/* Argument to terminate callback */
void *terminate_param;
/* Exit code of the call back function. */
WORD32 exit_code;
/* Identifier. Do not initialize this. */
WORD32 id;
} osal_select_entry_t;
/* File descriptor structure. Used in osal_socket_select() API call. */
/* Currently maximum number of sockets that can be set is fixed to */
/* SELECT_MAX */
/* Note : To initialize osal_fd_set structure variable, call API */
/* osal_socket_fd_zero() for Initialization. If initialization is not */
/* done, behaviour of osal_socket_select() and fd_set API's is */
/* undefined. */
typedef struct
{
void *array[OSAL_SELECT_MAX]; /* Array for holding the socket descriptors*/
WORD32 count; /* Number of socket descriptors in array */
} osal_fd_set_t;
/* Timeout value for osal_socket_select() API. */
typedef struct
{
WORD32 tv_sec; /* Time in seconds. */
WORD32 tv_usec; /* Time in micro seconds. */
} osal_timeval_t;
/* Attributes for setting Linger option for socket */
typedef struct
{
UWORD16 l_onoff;
UWORD16 l_linger;
} osal_sockopt_linger_t;
/* Attributes for Joining or dropping from a multicast group */
typedef struct
{
WORD8 imr_multiaddr[16];
WORD8 imr_interface[16];
WORD8 imr_srcaddr[16];
} osal_ip_mreq_t;
/*****************************************************************************/
/* Extern OSAL Initialization Function Declarations */
/*****************************************************************************/
/* Allocates memory for the OSAL instance handle. It also allocates memory */
/* for storing debug information. */
extern WORD32 osal_init(IN void *osal_handle);
/* Releases all the resources held by the OSAL handle */
extern WORD32 osal_close(IN void *osal_handle);
/* This function registers MMR call backs for OSAL */
extern WORD32 osal_register_callbacks(IN void *osal_handle, IN osal_cb_funcs_t *cb_funcs);
/*****************************************************************************/
/* Extern Mail Box Function Declarations */
/*****************************************************************************/
/* Allocates memory for mail box handle. Creates a mail box which is */
/* associated with the thread and updates the mail box, which returned for */
/* further actions to be performed on the mail box. */
extern void *osal_mbox_create(IN void *osal_handle, IN osal_mbox_attr_t *attr);
/* Closes the mail box and frees the memory allocated for mail box handle. */
extern WORD32 osal_mbox_destroy(IN void *mbox_handle);
/* Posts a message to the mail box */
extern WORD32 osal_mbox_post(IN void *mbox_handle, IN void *buf, IN UWORD32 len);
/* Gets the message form the specified mail box. If there are not messages */
/* in mail box, it waits infinitely till a message arrives. */
extern WORD32 osal_mbox_get(IN void *mbox_handle, OUT void *buf, IN UWORD32 len);
/* Gets the message from the specified mail box within the timeout period. */
/* If no messages are present in specified time, error code is returned. The */
/* error can be got from osal_get_last_error() API */
extern WORD32
osal_mbox_get_timed(IN void *mbox_handle, OUT void *buf, IN UWORD32 len, IN UWORD32 timeout);
/*****************************************************************************/
/* Extern Custom Mail Box Function Declarations */
/*****************************************************************************/
/* Allocates memory for mail box handle. Creates a mail box which is */
/* associated with the thread and updates the mail box, which returned for */
/* further actions to be performed on the mail box. */
extern void *osal_custom_mbox_create(IN void *osal_handle, IN osal_mbox_attr_t *attr);
/* Closes the mail box and frees the memory allocated for mail box handle. */
extern WORD32 osal_custom_mbox_destroy(IN void *mbox_handle);
/* Posts a message to the mail box */
extern WORD32 osal_custom_mbox_post(IN void *cust_mbox_handle, IN void *buf, IN UWORD32 len);
/* Gets the message form the specified mail box. If there are not messages */
/* in mail box, it waits infinitely till a message arrives. */
extern WORD32 osal_custom_mbox_get(IN void *cust_mbox_handle, OUT void *buf, IN UWORD32 len);
/* Gets the message from the specified mail box within the timeout period. */
/* If no messages are present in specified time, error code is returned. The */
/* error can be got from osal_get_last_error() API */
extern WORD32 osal_custom_mbox_get_timed(
IN void *cust_mbox_handle, OUT void *buf, IN UWORD32 len, IN UWORD32 timeout);
/*****************************************************************************/
/* Extern Mutex Function Declarations */
/*****************************************************************************/
/* Creates a mutex and returns the to mutex */
extern void *osal_mutex_create(IN void *osal_handle);
/* Closes the mutex. */
extern WORD32 osal_mutex_destroy(IN void *mutex_handle);
/* Waits infinitely till mutex lock is got. */
extern WORD32 osal_mutex_lock(IN void *mutex_handle);
/* Releases the lock held on the mutex. */
extern WORD32 osal_mutex_unlock(IN void *mutex_handle);
/*****************************************************************************/
/* Extern Semaphore Function Declarations */
/*****************************************************************************/
/* Creates a semaphore and returns the handle to semaphore. */
extern void *osal_sem_create(IN void *osal_handle, IN osal_sem_attr_t *attr);
/* Closes the semaphore. */
extern WORD32 osal_sem_destroy(IN void *sem_handle);
/* Waits infinitely till semaphore is zero. */
extern WORD32 osal_sem_wait(IN void *sem_handle);
/* Increments the value of semaphore by one. */
extern WORD32 osal_sem_post(IN void *sem_handle);
/* Returns the current value of semaphore. */
extern WORD32 osal_sem_count(IN void *sem_handle, OUT WORD32 *count);
/*****************************************************************************/
/* Extern Conditional Variable Function Declarations */
/*****************************************************************************/
/* Creates a conditional variable and returns the handle to it. */
extern void *osal_cond_var_create(IN void *osal_handle);
/* Destroys the conditional variable. */
extern WORD32 osal_cond_var_destroy(IN void *cond_var_handle);
/* Waits infinitely till conditional variable receives signal. */
extern WORD32 osal_cond_var_wait(IN void *cond_var_handle, IN void *mutex_handle);
/* Signals on conditional variable. */
extern WORD32 osal_cond_var_signal(IN void *cond_var_handle);
/*****************************************************************************/
/* Extern Thread Function Declarations */
/*****************************************************************************/
/* Creates a thread with specified parameters */
extern void *osal_thread_create(IN void *osal_handle, IN osal_thread_attr_t *attr);
/* Closes or halts the execution of thread specified by the handle. */
extern WORD32 osal_thread_destroy(IN void *thread_handle);
/* Makes the thread sleep for specified number of milliseconds */
extern WORD32 osal_thread_sleep(IN UWORD32 milli_seconds);
/* Yields the execution of thread. */
extern WORD32 osal_thread_yield(void);
/* Suspends the execution of thread until osal_thread_resume API is called. */
extern WORD32 osal_thread_suspend(IN void *thread_handle);
/* Resumes the execution of thread which was suspended by */
/* osal_thread_suspend API call. */
extern WORD32 osal_thread_resume(IN void *thread_handle);
/* Waits infinitely till the thread, whose handle is passed, completes */
/* execution. */
extern WORD32 osal_thread_wait(IN void *thread_handle);
/* Returns current thread handle */
extern void *osal_get_thread_handle(IN void *osal_handle);
/*****************************************************************************/
/* Extern Network Socket Function Declarations */
/*****************************************************************************/
/* Initializes network resources */
extern WORD32 osal_network_init(void);
/* Un-initializes all the network resources */
extern WORD32 osal_network_close(void);
/* Creates the socket and returns the socket descriptor. */
extern void *osal_socket_create(IN void *osal_handle, IN osal_socket_attr_t *attr);
/* Closes the open socket. */
extern WORD32 osal_socket_destroy(IN void *socket_handle);
/* Binds to the specified port number on the local machine. Socket_create */
/* API has to be called before calling socket_bind. */
extern WORD32 osal_socket_bind(IN void *socket_handle, IN osal_sockaddr_t *addr);
/* Starts listening at the specified port for any incoming connections. */
/* Socket descriptor should be bound before calling socket_listen */
extern WORD32 osal_socket_listen(IN void *socket_handle, IN WORD32 backlog);
/* Accepts incoming connection. If listen queue is empty it blocks till a */
/* successful connection is made. */
extern void *osal_socket_accept(IN void *socket_handle, OUT osal_sockaddr_t *addr);
/* Makes a connection request to the remote address specified. */
extern WORD32 osal_socket_connect(IN void *socket_handle, IN osal_sockaddr_t *addr);
/* Sends the specified number of bytes of data */
extern WORD32 osal_socket_send(
IN void *socket_handle, IN const WORD8 *buf, IN WORD32 len, IN WORD32 flags);
/* Receives data over TCP connection. */
extern WORD32
osal_socket_recv(IN void *socket_handle, OUT WORD8 *buf, IN WORD32 len, IN WORD32 flags);
/* Sends data over a datagram protocol */
extern WORD32 osal_socket_sendto(
IN void *socket_handle,
IN const WORD8 *buf,
IN WORD32 len,
IN WORD32 flags,
IN osal_sockaddr_t *to);
/* Receives packet over a UDP connection */
extern WORD32 osal_socket_recvfrom(
IN void *socket_handle,
OUT WORD8 *buf,
IN WORD32 len,
IN WORD32 flags,
OUT osal_sockaddr_t *from);
/* Polls the specified sockets for specified activity */
extern WORD32 osal_socket_select(
INOUT osal_fd_set_t *readfds,
INOUT osal_fd_set_t *writefds,
INOUT osal_fd_set_t *exceptfds,
INOUT osal_timeval_t *timeout);
/* Gets the socket options */
extern WORD32 osal_socket_getsockopt(
IN void *socket_handle,
IN WORD32 level,
IN WORD32 optname,
OUT WORD8 *optval,
INOUT WORD32 *optlen);
/* Sets the socket options to specified values */
extern WORD32 osal_socket_setsockopt(
IN void *socket_handle,
IN WORD32 level,
IN WORD32 optname,
IN const WORD8 *optval,
IN WORD32 optlen);
/* Adds the specified socket handle to the file descriptor set */
extern WORD32 osal_socket_fd_set(IN void *socket_handle, OUT osal_fd_set_t *set);
/* Checks the file descriptor set for the presence of socket handle. */
extern WORD32 osal_socket_fd_isset(IN void *socket_handle, IN osal_fd_set_t *set);
/* Resets the file descriptor set */
extern void osal_socket_fd_zero(INOUT osal_fd_set_t *set);
/* Removes the specified socket handle from the file descriptor set */
extern WORD32 osal_socket_fd_clr(IN void *socket_handle, OUT osal_fd_set_t *set);
/* To convert short integer from host byte order to network byte order */
extern UWORD16 osal_htons(IN UWORD16 hostshort);
/* To convert long integer from host to network byte order */
extern UWORD32 osal_htonl(IN UWORD32 hostlong);
/* To convert short integer from network to host byte order */
extern UWORD16 osal_ntohs(IN UWORD16 netshort);
/* To convert long integer from network to host byte order */
extern UWORD32 osal_ntohl(IN UWORD32 netlong);
/*****************************************************************************/
/* Extern Select Engine Function Declarations */
/*****************************************************************************/
/* Initializes the select engine. */
extern void *
osal_select_engine_init(IN void *osal_handle, IN osal_select_engine_attr_t *se_attr);
/* Closes the select engine. */
extern WORD32 osal_select_engine_close(IN void *select_engine);
/* Registers the socket handle specified in the entry. */
extern WORD32
osal_select_engine_register(IN void *select_engine, IN osal_select_entry_t *entry);
/* Un-registers the specified socket handle. */
extern WORD32 osal_select_engine_unregister(
IN void *select_engine, IN void *socket_handle, IN OSAL_FD_TYPE_T fd_type);
/*****************************************************************************/
/* Extern Other Function Declarations */
/*****************************************************************************/
/* Returns time in milliseconds */
extern UWORD32 osal_get_time(void);
/* For time in micro-second resolution */
extern WORD32 osal_get_time_usec(UWORD32 *sec, UWORD32 *usec);
/* Returns the last error code. 0 is no error */
extern UWORD32 osal_get_last_error(void);
/* Prints the last error code. 0 is no error */
extern void osal_print_last_error(IN const STRWORD8 *string);
/* Gets the version of library in NULL terminated string form. */
extern WORD8 *osal_get_version(void);
/* Gets the tid of the thread in whose context this call was made */
extern WORD32 osal_get_current_tid(void);
/* C linkage specifiers for C++ declarations. */
#ifdef __cplusplus
}
#endif /* __cplusplus */
#endif /* OSAL_H */