Cordio Stack and Cordio Profiles  r2p3-02rel0
wsf_os.h
Go to the documentation of this file.
1 /*************************************************************************************************/
2 /*!
3  * \file wsf_os.h
4  *
5  * \brief Software foundation OS API.
6  *
7  * Copyright (c) 2009-2018 Arm Ltd. All Rights Reserved.
8  * Arm Ltd. confidential and proprietary.
9  *
10  * IMPORTANT. Your use of this file is governed by a Software License Agreement
11  * ("Agreement") that must be accepted in order to download or otherwise receive a
12  * copy of this file. You may not use or copy this file for any purpose other than
13  * as described in the Agreement. If you do not agree to all of the terms of the
14  * Agreement do not use this file and delete all copies in your possession or control;
15  * if you do not have a copy of the Agreement, you must contact Arm Ltd. prior
16  * to any use, copying or further distribution of this software.
17  */
18 /*************************************************************************************************/
19 #ifndef WSF_OS_H
20 #define WSF_OS_H
21 
22 #include "wsf_queue.h"
23 
24 #ifdef __cplusplus
25 extern "C" {
26 #endif
27 
28 /*! \addtogroup WSF_OS_API
29  * \{ */
30 
31 /**************************************************************************************************
32  Configuration
33 **************************************************************************************************/
34 
35 /*! \brief OS Diagnostics */
36 #ifndef WSF_OS_DIAG
37 #define WSF_OS_DIAG FALSE
38 #endif
39 
40 /**************************************************************************************************
41  Macros
42 **************************************************************************************************/
43 
44 /*! \brief Derive task from handler ID */
45 #define WSF_TASK_FROM_ID(handlerID) (((handlerID) >> 4) & 0x0F)
46 
47 /*! \brief Derive handler from handler ID */
48 #define WSF_HANDLER_FROM_ID(handlerID) ((handlerID) & 0x0F)
49 
50 /*! \brief Invalid Task Identifier */
51 #define WSF_INVALID_TASK_ID 0xFF
52 
53 /*! \brief Get Diagnostic Task Identifier */
54 #if WSF_OS_DIAG == TRUE
55 #define WSF_OS_GET_ACTIVE_HANDLER_ID() WsfActiveHandler
56 #else
57 #define WSF_OS_GET_ACTIVE_HANDLER_ID() WSF_INVALID_TASK_ID
58 #endif /* WSF_OS_DIAG */
59 
60 /** @name WSF Task Events
61  *
62  */
63 /**@{*/
64 #define WSF_MSG_QUEUE_EVENT 0x01 /*!< \brief Message queued for event handler */
65 #define WSF_TIMER_EVENT 0x02 /*!< \brief Timer expired for event handler */
66 #define WSF_HANDLER_EVENT 0x04 /*!< \brief Event set for event handler */
67 /**@}*/
68 
69 /**************************************************************************************************
70  Data Types
71 **************************************************************************************************/
72 
73 /*! \brief Event handler ID data type */
75 
76 /*! \brief Event handler event mask data type */
78 
79 /*! \brief Task ID data type */
80 typedef wsfHandlerId_t wsfTaskId_t;
81 
82 /*! \brief Task event mask data type */
84 
85 /**************************************************************************************************
86  External Variables
87 **************************************************************************************************/
88 
89 /*! \brief Diagnostic Task Identifier */
90 extern wsfHandlerId_t WsfActiveHandler;
91 
92 /**************************************************************************************************
93  Data Types
94 **************************************************************************************************/
95 
96 /*! \brief Common message structure passed to event handler */
97 typedef struct
98 {
99  uint16_t param; /*!< \brief General purpose parameter passed to event handler */
100  uint8_t event; /*!< \brief General purpose event value passed to event handler */
101  uint8_t status; /*!< \brief General purpose status value passed to event handler */
102 } wsfMsgHdr_t;
103 
104 /**************************************************************************************************
105  Callback Function Types
106 **************************************************************************************************/
107 
108 /*************************************************************************************************/
109 /*!
110  * \brief Event handler callback function.
111  *
112  * \param event Mask of events set for the event handler.
113  * \param pMsg Pointer to message for the event handler.
114  *
115  * \return None.
116  */
117 /*************************************************************************************************/
118 typedef void (*wsfEventHandler_t)(wsfEventMask_t event, wsfMsgHdr_t *pMsg);
119 
120 /**************************************************************************************************
121  Function Declarations
122 **************************************************************************************************/
123 
124 /*************************************************************************************************/
125 /*!
126  * \brief Set an event for an event handler.
127  *
128  * \param handlerId Handler ID.
129  * \param event Event or events to set.
130  *
131  * \return None.
132  */
133 /*************************************************************************************************/
134 void WsfSetEvent(wsfHandlerId_t handlerId, wsfEventMask_t event);
135 
136 /*************************************************************************************************/
137 /*!
138  * \brief Lock task scheduling.
139  *
140  * \return None.
141  */
142 /*************************************************************************************************/
143 void WsfTaskLock(void);
144 
145 /*************************************************************************************************/
146 /*!
147  * \brief Unlock task scheduling.
148  *
149  * \return None.
150  */
151 /*************************************************************************************************/
152 void WsfTaskUnlock(void);
153 
154 /*************************************************************************************************/
155 /*!
156  * \brief Set the task used by the given handler as ready to run.
157  *
158  * \param handlerId Event handler ID.
159  * \param event Task event mask.
160  *
161  * \return None.
162  */
163 /*************************************************************************************************/
164 void WsfTaskSetReady(wsfHandlerId_t handlerId, wsfTaskEvent_t event);
165 
166 /*************************************************************************************************/
167 /*!
168  * \brief Return the task message queue used by the given handler.
169  *
170  * \param handlerId Event handler ID.
171  *
172  * \return Task message queue.
173  */
174 /*************************************************************************************************/
175 wsfQueue_t *WsfTaskMsgQueue(wsfHandlerId_t handlerId);
176 
177 /*************************************************************************************************/
178 /*!
179  * \brief Set the next WSF handler function in the WSF OS handler array. This function
180  * should only be called as part of the OS initialization procedure.
181  *
182  * \param handler WSF handler function.
183  *
184  * \return WSF handler ID for this handler.
185  */
186 /*************************************************************************************************/
187 wsfHandlerId_t WsfOsSetNextHandler(wsfEventHandler_t handler);
188 
189 /*************************************************************************************************/
190 /*!
191  * \brief Check if WSF is ready to sleep.
192  *
193  * \return Return TRUE if there are no pending WSF task events set, FALSE otherwise.
194  */
195 /*************************************************************************************************/
197 
198 /*************************************************************************************************/
199 /*!
200  * \brief Event dispatched. Designed to be called repeatedly from infinite loop.
201  *
202  * \return None.
203  */
204 /*************************************************************************************************/
205 void wsfOsDispatcher(void);
206 
207 /*************************************************************************************************/
208 /*!
209  * \brief Shutdown OS.
210  *
211  * \return None.
212  */
213 /*************************************************************************************************/
214 void WsfOsShutdown(void);
215 
216 /*! \} */ /* WSF_OS_API */
217 
218 #ifdef __cplusplus
219 };
220 #endif
221 
222 #endif /* WSF_OS_H */
uint8_t wsfEventMask_t
Event handler event mask data type.
Definition: wsf_os.h:77
void WsfSetEvent(wsfHandlerId_t handlerId, wsfEventMask_t event)
Set an event for an event handler.
uint8_t wsfTaskEvent_t
Task event mask data type.
Definition: wsf_os.h:83
uint8_t bool_t
Boolean data type.
Definition: wsf_types.h:78
uint8_t event
General purpose event value passed to event handler.
Definition: wsf_os.h:100
void WsfTaskUnlock(void)
Unlock task scheduling.
bool_t wsfOsReadyToSleep(void)
Check if WSF is ready to sleep.
wsfQueue_t * WsfTaskMsgQueue(wsfHandlerId_t handlerId)
Return the task message queue used by the given handler.
uint16_t param
General purpose parameter passed to event handler.
Definition: wsf_os.h:99
void WsfOsShutdown(void)
Shutdown OS.
void(* wsfEventHandler_t)(wsfEventMask_t event, wsfMsgHdr_t *pMsg)
Event handler callback function.
Definition: wsf_os.h:118
void WsfTaskSetReady(wsfHandlerId_t handlerId, wsfTaskEvent_t event)
Set the task used by the given handler as ready to run.
uint8_t wsfHandlerId_t
Event handler ID data type.
Definition: wsf_os.h:74
Queue structure.
Definition: wsf_queue.h:41
uint8_t status
General purpose status value passed to event handler.
Definition: wsf_os.h:101
void wsfOsDispatcher(void)
Event dispatched. Designed to be called repeatedly from infinite loop.
void WsfTaskLock(void)
Lock task scheduling.
unsigned short uint16_t
Unsigned 16-bit value.
Definition: wsf_types.h:67
wsfHandlerId_t WsfOsSetNextHandler(wsfEventHandler_t handler)
Set the next WSF handler function in the WSF OS handler array. This function should only be called as...
General purpose queue service.
wsfHandlerId_t wsfTaskId_t
Task ID data type.
Definition: wsf_os.h:80
wsfHandlerId_t WsfActiveHandler
Diagnostic Task Identifier.
Common message structure passed to event handler.
Definition: wsf_os.h:97
unsigned char uint8_t
Unsigned 8-bit value.
Definition: wsf_types.h:63