source: trunk/libs/mini-libpthread/pthread.h @ 444

Last change on this file since 444 was 444, checked in by satin@…, 4 years ago

add newlib,libalmos-mkh, restructure shared_syscalls.h and mini-libc

File size: 14.1 KB
Line 
1/*
2 * pthread.h - User side pthread related library definition.
3 *
4 * Author     Alain Greiner (2016,2017)
5 *
6 * Copyright (c) UPMC Sorbonne Universites
7 *
8 * This file is part of ALMOS-MKH.
9 *
10 * ALMOS-MKH is free software; you can redistribute it and/or modify it
11 * under the terms of the GNU General Public License as published by
12 * the Free Software Foundation; version 2.0 of the License.
13 *
14 * ALMOS-MKH is distributed in the hope that it will be useful, but
15 * WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
17 * General Public License for more details.
18 *
19 * You should have received a copy of the GNU General Public License
20 * along with ALMOS-MKH; if not, write to the Free Software Foundation,
21 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
22 */
23
24#ifndef _PTHREAD_H_
25#define _PTHREAD_H_
26
27#include <almos-mkh/pthread.h>
28
29
30//////////////////////////////////////////////////////////////////////////////////////////////
31//             POSIX Threads related functions
32//////////////////////////////////////////////////////////////////////////////////////////////
33
34/*********************************************************************************************
35 * This function creates a new user thread. The <user_attr> argument is a pointer
36 * on a structure containing the thread attributes, defined in thread.h file.
37 *********************************************************************************************
38 * @ trdid       : [out] buffer for created thread identifier in process.
39 * @ user_attr   : [in]  pointer on thread attributes structure.
40 * @ start_func  : [in]  pointer on start function.
41 * @ start_args  : [in]  pointer on start function arguments.
42 * @ return 0 if success / return -1 if failure.
43 ********************************************************************************************/
44int pthread_create( pthread_t            * trdid,
45                    const pthread_attr_t * attr,
46                    void                 * start_func,
47                    void                 * start_args );
48
49/*********************************************************************************************
50 * This blocking function causes the calling thread to wait for the termination of a target
51 * thread identified by the <trdid> argument. The <exit_value> defines the buffer to store
52 * the pointer returned by the terminating thread.
53 *********************************************************************************************
54 * @ trdid       : target thread identifier in process.
55 * @ start_args  : [in]  pointer on start function arguments.
56 * @ return 0 if success / return -1 if failure.
57 ********************************************************************************************/
58int pthread_join( pthread_t    trdid,
59                  void      ** exit_value );
60
61/*********************************************************************************************
62 * This function is used to indicate that storage for the target thread, identified by the
63 * <trdid> argument can be reclaimed when the thread terminates.
64 * If target thread has not terminated, pthread_detach() will not cause it to terminate.
65 *********************************************************************************************
66 * @ trdid       : target thread identifier in process.
67 * @ return 0 if success / return -1 if failure.
68 ********************************************************************************************/
69int pthread_detach( pthread_t   trdid );
70
71/*********************************************************************************************
72 * This function terminates the execution of the calling thread, and makes the exit_value
73 * pointer available to any successful pthread_join() with the terminating thread.
74 *********************************************************************************************
75 * @ exit_vallue  : [in] pointer to be returned to parent thread if thead is attached.
76 * @ return 0 if success / return -1 if failure.
77 ********************************************************************************************/
78int pthread_exit( void * exit_value );
79
80
81
82// TODO n'existe pas dans pthread
83/*********************************************************************************************
84 * This function calls the scheduler for the core running the calling thread.
85 *********************************************************************************************
86 * @ return always 0.
87 ********************************************************************************************/
88int pthread_yield();
89
90//////////////////////////////////////////////////////////////////////////////////////////////
91//                 POSIX Barriers related functions
92//
93// These functions are implemented in user space. Only the pthread_barrier_init() function
94// uses syscalls to build the distributed quad-tree infrastructure.
95//////////////////////////////////////////////////////////////////////////////////////////////
96
97/*********************************************************************************************
98 * These structures defines a hierarchical, POSIX compliant, barrier.
99 * - If the barrier attribute in the pthread_barrier_init() is NULL, it is implemented
100 *   as a simple, sense reversing barrier, localised in the calling thread cluster.
101 * - If the barrier attribute is defined, it is implemented as a hierarchical, physically
102 *   distributed quad-tree, covering all clusters specified, with the following constraints:
103 *   . The involved clusters form a mesh [x_size * y_size]
104 *   . The lower left involved cluster is cluster(0,0) 
105 *   . The number of threads in a cluster is the same in all clusters.
106 *
107 * Implementation note:
108 * - The quad three is implemented as a three dimensions array of node[x][y][l]
109 *   . [x][y] are the cluster coordinates / max values are (QDT_XMAX-1), (QDT_YMAX-1)
110 *   . [l] is the node level / 0 for terminal nodes / (QDT_LMAX-1) for the root node
111 ********************************************************************************************/
112
113#define  QDT_XMAX    16                /*! max number of clusters in a row                  */
114#define  QDT_YMAX    16                /*! max number of clusters in a column               */
115#define  QDT_LMAX    5                 /*! max depth of the quad tree                       */
116#define  QDT_YWIDTH  4                 /*! Y field in cxy, for cxy <=> (x,y) translation    */
117#define  QDT_YMASK   0xF               /*! Y field in cxy, for cxy <=> (x,y) translation    */
118
119typedef struct sqt_node_s
120{
121    volatile unsigned int sense;       /*! barrier state (toggle)                           */
122    volatile unsigned int count;       /*! number of not arrived tasks                      */
123    unsigned int          arity;       /*! number of locally expected tasks                 */
124    unsigned int          level;       /*! hierarchical level (0 is bottom)                 */
125    struct sqt_node_s   * parent;      /*! pointer on parent node (NULL for root)           */
126    struct sqt_node_s   * child[4];    /*! pointer on children node (NULL for bottom)       */
127}
128sqt_node_t;
129
130typedef struct pthread_barrier_s
131{
132    sqt_node_t          * node[QDT_XMAX][QDT_YMAX][QDT_LMAX];
133}
134pthread_barrier_t;
135
136typedef struct pthread_barrierattr_s
137{
138    unsigned int          x_size;      /*! number of clusters in a row (0 to x_size-1)      */
139    unsigned int          y_size;      /*! number of clusters in a column (0 to y_size-1)   */
140    unsigned int          nthreads;    /*! number of expected threads in a cluster          */
141}
142pthread_barrierattr_t;
143
144/*********************************************************************************************
145 * This function allocates resources required to use the barrier referenced by the <barrier>
146 * argument, and initializes the barrier from attributes referenced by the <attr> argument.
147 * If <attr> is NULL, the default barrier attributes shall be used.
148 * The results are undefined if pthread_barrier_init() is called when any thread is blocked
149 * on the barrier, or is used without first being initialized, or if pthread_barrier_init()
150 * is called specifying an already initialized barrier.
151 *********************************************************************************************
152 * @ barrier     : [in]  pointer on barrier in user space.
153 * @ attr        : [in]  pointer on attributes structure.
154 * @ count       : [in]  number of expected threads.
155 * @ return 0 if success / return EINVAL if illegal attributes.
156 ********************************************************************************************/
157int pthread_barrier_init( pthread_barrier_t           * barrier,
158                          const pthread_barrierattr_t * attr,
159                          unsigned int                  count ); 
160
161/*********************************************************************************************
162 * This function synchronizes participating threads at the barrier referenced by <barrier>.
163 * The calling is blocked until the required number of threads have called the function
164 * pthread_barrier_wait() specifying the barrier.
165 * When the required number of threads have called pthread_barrier_wait(), the constant
166 * PTHREAD_BARRIER_SERIAL_THREAD is returned to one unspecified thread and zero is returned
167 * to each of the remaining threads.
168 *********************************************************************************************
169 * @ barrier     : [in]  pointer on barrier in user space.
170 * @ return 0 if success / return EINVAL if the barrier was not properly initialized.
171 ********************************************************************************************/
172int pthread_barrier_wait( pthread_barrier_t * barrier );
173
174/*********************************************************************************************
175 * This function destroy the barrier referenced by <barrier> and release all resources used
176 * by the barrier. The effect of subsequent use of the barrier is undefined until the barrier
177 * is reinitialized by another call to pthread_barrier_init().
178 * An implementation may use this function to set barrier to an invalid value.
179 * The results are undefined if pthread_barrier_destroy() is called when a thread is blocked
180 * on the barrier, or if this function is called with an uninitialized barrier.
181 *********************************************************************************************
182 * @ barrier     : [in]  pointer on barrier in user space.
183 ********************************************************************************************/
184int pthread_barrier_destroy( pthread_barrier_t * barrier );
185   
186
187//////////////////////////////////////////////////////////////////////////////////////////////
188//                      POSIX Mutexes
189//
190// These functions are implemented in user space, and do not use syscalls.
191// This implementation uses a ticket based policy to enforce fairness.
192//////////////////////////////////////////////////////////////////////////////////////////////
193
194typedef struct pthread_mutex_s
195{
196    volatile unsigned int current;   /*! current index                                      */
197    volatile unsigned int free;      /*! next free ticket index                             */
198}
199pthread_mutex_t;
200
201typedef struct pthread_mutexattr_s
202{
203    int          bloup;              /*! unused                                             */
204}
205pthread_mutexattr_t;
206
207/*********************************************************************************************
208 * This function initialise the mutex identified by the <mutex> argument.
209 * The <attr> argument is not supported yet, and must be NULL.
210 *********************************************************************************************
211 * @ mutex     : pointer on mutex in user space.
212 * @ attr      : pointer on attributes structure / must be NULL.
213 * @ return 0 if success / return -1 if failure.
214 ********************************************************************************************/
215int pthread_mutex_init( pthread_mutex_t           * mutex,
216                        const pthread_mutexattr_t * attr );
217
218/*********************************************************************************************
219 * This function destroy the mutex identified by the <mutex> argument.
220 *********************************************************************************************
221 * @ mutex     : pointer on mutex in user space.
222 * @ return 0 if success / return -1 if failure.
223 ********************************************************************************************/
224int pthread_mutex_destroy( pthread_mutex_t * mutex );
225
226/*********************************************************************************************
227 * This bloking function locks the mutex identified by the <mutex> argument,
228 * and blocks until it becomes available.
229 *********************************************************************************************
230 * @ mutex     : pointer on mutex in user space.
231 * @ return 0 if success / return -1 if failure.
232 ********************************************************************************************/
233int pthread_mutex_lock( pthread_mutex_t * mutex );
234
235/*********************************************************************************************
236 * This function tries to lock the mutex identified by the <mutex> argument,
237 * but don't block if the mutex is locked by another thread, including the current thread.
238 *********************************************************************************************
239 * @ mutex     : pointer on mutex in user space.
240 * @ return 0 if success / return -1 if mutex already taken.
241 ********************************************************************************************/
242int pthread_mutex_trylock( pthread_mutex_t * mutex );
243
244/*********************************************************************************************
245 * This function unlocks the mutex identified by the <mutex> argument.
246 *********************************************************************************************
247 * @ mutex     : pointer on mutex in user space.
248 * @ return 0 if success / return -1 if failure.
249 ********************************************************************************************/
250int pthread_mutex_unlock( pthread_mutex_t * mutex );
251
252
253#endif  // _PTHREAD_H_
Note: See TracBrowser for help on using the repository browser.