1 /*******************************************************************************
2 * The confidential and proprietary information contained in this file may      *
3 * only be used by a person authorised under and to the extent permitted        *
4 * by a subsisting licensing agreement from ARM Limited or its affiliates.      *
5 *   (C) COPYRIGHT [2001-2017] ARM Limited or its affiliates.                   *
6 *       ALL RIGHTS RESERVED                                                    *
7 * This entire notice must be reproduced on all copies of this file             *
8 * and copies of this file may only be made by a person if such person is       *
9 * permitted to do so under the terms of a subsisting license agreement         *
10 * from ARM Limited or its affiliates.                                          *
11 *******************************************************************************/
12 
13 #ifndef TEST_PAL_THREAD_H_
14 #define TEST_PAL_THREAD_H_
15 
16 #include <stdint.h>
17 
18 #ifdef __cplusplus
19 extern "C" {
20 #endif
21 
22 typedef void *ThreadHandle;
23 
24 /******************************************************************************/
25 /*
26  * @brief This function returns the minimal stack size in bytes.
27  *
28  * @param[in]
29 
30  * @param[out]
31  *
32  * @return - Minimal stack size in bytes.
33  */
34 size_t Test_PalGetMinimalStackSize(void);
35 
36 /******************************************************************************/
37 /*
38  * @brief This function returns the highest thread priority.
39  *
40  * @param[in]
41 
42  * @param[out]
43  *
44  * @return - Highest thread priority.
45  */
46 uint32_t Test_PalGetHighestPriority(void);
47 
48 /******************************************************************************/
49 /*
50  * @brief This function returns the lowest thread priority.
51  *
52  * @param[in]
53 
54  * @param[out]
55  *
56  * @return - Lowest thread priority.
57  */
58 uint32_t Test_PalGetLowestPriority(void);
59 
60 /******************************************************************************/
61 /*
62  * @brief This function returns the default thread priority.
63  *
64  * @param[in]
65 
66  * @param[out]
67  *
68  * @return - Default thread priority.
69  */
70 uint32_t Test_PalGetDefaultPriority(void);
71 
72 /******************************************************************************/
73 /*
74  * @brief This function creates a thread. The user should call
75  * Test_PalThreadJoin() in order to wait until the thread ends and then to
76  * Test_PalThreadDestroy() in order to free resources.
77  * In case of a thread without an end, the user shouldn't call
78  * Test_PalThreadJoin() which will not return. Instead, the user should call
79  * Test_PalThreadDestroy() which will cancel the thread and free
80  * its resources.
81  *
82  * @param[in]
83  * stackSize - Thread stack size in bytes. The allocated stack size will be the
84  * biggest between stackSize and the minimal stack size.
85  * threadFunc - Thread function. The function shall return a pointer to the
86  * returned value or NULL. In case TZM is supported, this function must have the
87  * same security attribute as TestAL's (either secure or non-secure).
88  * priority - Thread priority. Highest and lowest priorities can be received
89  * by calling Test_PalGetLowestPriority() and Test_PalGetHighestPriority()
90  * accordingly.
91  * args - Function input arguments.
92  * threadName - Thread name. Not in use for Linux.
93  * nameLen - Thread name length. Not in use for Linux.
94  * dmaAble - Determines whether the stack should be DMA-able (true)
95  * or not (false).
96  *
97  * @param[out]
98  *
99  * @return - threadHandle address for success, NULL for failure.
100  */
101 ThreadHandle Test_PalThreadCreate(size_t stackSize,
102                   void *(*threadFunc)(void *),
103                   int priority, void *args,
104                   const char *threadName,
105                   uint8_t nameLen, uint8_t dmaAble);
106 
107 /******************************************************************************/
108 /*
109  * @brief This function waits for a thread to terminate (BLOCKING).
110  * If that thread has already terminated it returns immediately.
111  *
112  * @param[in]
113  * threadHandle - Thread structure. Not in use for FreeRTOS.
114  * threadRet - A pointer to pointer to the returned value of the target thread.
115  * Note that threadRet is not changed, yet *threadRet is changed and
116  * can be NULL. Hence, the user shall not try accessing **threadRet without
117  * checking that *threadRet in not NULL.
118  *
119  * @param[out]
120  *
121  * @return rc - 0 for success, 1 for failure.
122  */
123 uint32_t Test_PalThreadJoin(ThreadHandle threadHandle, void **threadRet);
124 
125 /******************************************************************************/
126 /*
127  * @brief This function destroys a thread (if it's still running) and frees
128  * its resources.
129  * In order to free thread resources only after thread's end this function
130  * should be called after Test_PalThreadJoin.
131  * In order to cancel the thread immediately and free its resources, this
132  * function should be called alone (i.e. without Test_PalThreadJoin).
133  * It must eventually be called in any case.
134  * Note that this function doesn't deallocate the memory that the
135  * thread itself allocates. This needs to be done by the thread itself.
136  *
137  * @param[in]
138  * threadHandle - Thread structure.
139  *
140  * @param[out]
141  *
142  * @return rc - 0 for success, 1 for failure.
143  */
144 uint32_t Test_PalThreadDestroy(ThreadHandle threadHandle);
145 
146 #ifdef __cplusplus
147 }
148 #endif
149 
150 #endif /* TEST_PAL_THREAD_H_ */
151