1 | /* |
---|
2 | * almosmkh.h - User level ALMOS-MKH specific library definition. |
---|
3 | * |
---|
4 | * Author Alain Greiner (2016,2017,2018,2019,2020) |
---|
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 _LIBALMOSMKH_H_ |
---|
25 | #define _LIBALMOSMKH_H_ |
---|
26 | |
---|
27 | /*************************************************************************************** |
---|
28 | * This file defines an user level, ALMOS-MKH specific library, containing: |
---|
29 | * - non standard system calls. |
---|
30 | * - debug functions. |
---|
31 | * - remote malloc extensions. |
---|
32 | * - a parallel_pthread_create function. |
---|
33 | * - Frame Buffer access syscalls. |
---|
34 | **************************************************************************************/ |
---|
35 | |
---|
36 | #include <pthread.h> |
---|
37 | #include <shared_almos.h> |
---|
38 | |
---|
39 | |
---|
40 | /****************** Non standard (ALMOS_MKH specific) system calls ********************/ |
---|
41 | |
---|
42 | |
---|
43 | /*************************************************************************************** |
---|
44 | * This syscall gives the process identified by the <pid> argument the exclusive |
---|
45 | * ownership of its TXT terminal. |
---|
46 | *************************************************************************************** |
---|
47 | * @ pid : process identifier. |
---|
48 | * @ returns O if success / returns -1 if process not found. |
---|
49 | **************************************************************************************/ |
---|
50 | int fg( unsigned int pid ); |
---|
51 | |
---|
52 | /*************************************************************************************** |
---|
53 | * This syscall stores in the buffer identified by the <owner> argument a non zero |
---|
54 | * value when the process identified by the <pid> argument is currently the exclusive |
---|
55 | * owner of its TXT terminal. |
---|
56 | *************************************************************************************** |
---|
57 | * @ pid : [in] process identifier. |
---|
58 | * @ owner : [out] pointer on buffer to store the |
---|
59 | * @ returns O if success / returns -1 if process not found. |
---|
60 | **************************************************************************************/ |
---|
61 | int is_fg( unsigned int pid, |
---|
62 | unsigned int * owner ); |
---|
63 | |
---|
64 | /*************************************************************************************** |
---|
65 | * This syscall returns the hardware platform parameters. |
---|
66 | *************************************************************************************** |
---|
67 | * @ x_size : [out] number of clusters in a row. |
---|
68 | * @ y_size : [out] number of clusters in a column. |
---|
69 | * @ ncores : [out] number of cores per cluster. |
---|
70 | * @ return always 0. |
---|
71 | **************************************************************************************/ |
---|
72 | int get_config( unsigned int * x_size, |
---|
73 | unsigned int * y_size, |
---|
74 | unsigned int * ncores ); |
---|
75 | |
---|
76 | /*************************************************************************************** |
---|
77 | * This syscall returns the cluster identifier and the local index |
---|
78 | * for the calling core. |
---|
79 | *************************************************************************************** |
---|
80 | * @ cxy : [out] cluster identifier. |
---|
81 | * @ lid : [out] core local index in cluster. |
---|
82 | * @ return always 0. |
---|
83 | **************************************************************************************/ |
---|
84 | int get_core_id( unsigned int * cxy, |
---|
85 | unsigned int * lid ); |
---|
86 | |
---|
87 | /*************************************************************************************** |
---|
88 | * This syscall returns the number of cores in a given cluster. |
---|
89 | *************************************************************************************** |
---|
90 | * @ cxy : [in] target cluster identifier. |
---|
91 | * @ ncores : [out] number of cores in target cluster. |
---|
92 | * @ return always 0. |
---|
93 | **************************************************************************************/ |
---|
94 | int get_nb_cores( unsigned int cxy, |
---|
95 | unsigned int * ncores ); |
---|
96 | |
---|
97 | /*************************************************************************************** |
---|
98 | * This syscall uses the DQDT to search, in a macro-cluster specified by the |
---|
99 | * <cxy_base> and <level> arguments arguments, the core with the lowest load. |
---|
100 | * it writes in the <cxy> and <lid> buffers the selected core cluster identifier |
---|
101 | * and the local core index. |
---|
102 | *************************************************************************************** |
---|
103 | * @ cxy_base : [in] any cluster identifier in macro-cluster.in clusters array. |
---|
104 | * @ level : [in] macro-cluster level in [1,2,3,4,5]. |
---|
105 | * @ cxy : [out] selected core cluster identifier. |
---|
106 | * @ lid : [out] selected core local index. |
---|
107 | * @ return 0 if success / 1 if no core in macro-cluster / -1 if illegal arguments. |
---|
108 | **************************************************************************************/ |
---|
109 | int get_best_core( unsigned int cxy_base, |
---|
110 | unsigned int level, |
---|
111 | unsigned int * cxy, |
---|
112 | unsigned int * lid ); |
---|
113 | |
---|
114 | /*************************************************************************************** |
---|
115 | * This function returns the value contained in the calling core cycles counter, |
---|
116 | * taking into account a possible overflow on 32 bits architectures. |
---|
117 | *************************************************************************************** |
---|
118 | * @ cycle : [out] current cycle value. |
---|
119 | * @ return always 0. |
---|
120 | **************************************************************************************/ |
---|
121 | int get_cycle( unsigned long long * cycle ); |
---|
122 | |
---|
123 | /*************************************************************************************** |
---|
124 | * This syscall allows the calling thread to specify the target cluster for |
---|
125 | * a subsequent fork(). It must be called for each fork(). |
---|
126 | *************************************************************************************** |
---|
127 | * @ cxy : [in] target cluster identifier. |
---|
128 | * @ return 0 if success / returns -1 if illegal cxy argument. |
---|
129 | **************************************************************************************/ |
---|
130 | int place_fork( unsigned int cxy ); |
---|
131 | |
---|
132 | /*************************************************************************************** |
---|
133 | * This syscall implements the operations related to User Thread Local Storage. |
---|
134 | *************************************************************************************** |
---|
135 | * @ operation : UTLS operation type as defined in "shared_sycalls.h" file. |
---|
136 | * @ value : argument value for the UTLS_SET operation. |
---|
137 | * @ return value for the UTLS_GET and UTLS_GET_ERRNO / return -1 if failure. |
---|
138 | **************************************************************************************/ |
---|
139 | int utls( unsigned int operation, |
---|
140 | unsigned int value ); |
---|
141 | |
---|
142 | /*************************************************************************************** |
---|
143 | * This syscall returns an 32 bits integer from the standard "stdin" stream. |
---|
144 | * The value is copied in buffer pointed by the <buf> argument |
---|
145 | * Both decimal numbers and hexadecimal numbers (prefixed by 0x) are supported. |
---|
146 | *************************************************************************************** |
---|
147 | * @ buffer : pointer on buffer. |
---|
148 | * @ returns 0 if success / returns -1 if failure. |
---|
149 | **************************************************************************************/ |
---|
150 | int get_uint32( unsigned int * buffer ); |
---|
151 | |
---|
152 | /*************************************************************************************** |
---|
153 | * This syscall returns a character string from the standard "stdin" stream. |
---|
154 | * The string is copied in buffer pointed by the <string> argument. |
---|
155 | * The string length (including the NUL terminating character) cannot be larger |
---|
156 | * than the size defined by the <size> argument. |
---|
157 | *************************************************************************************** |
---|
158 | * @ string : pointer on the string buffer. |
---|
159 | * @ maxlen : max number of bytes in string buffer. |
---|
160 | * @ returns 0 if success / returns -1 if failure. |
---|
161 | **************************************************************************************/ |
---|
162 | int get_string( char * string, |
---|
163 | int maxlen ); |
---|
164 | |
---|
165 | |
---|
166 | /***************** Non standard (ALMOS-MKH specific) debug functions ******************/ |
---|
167 | |
---|
168 | /*************************************************************************************** |
---|
169 | * This syscall copies in the user structure defined by the <info> argument the values |
---|
170 | * registered in the calling thread "thread_info_t" kernel structure. |
---|
171 | ****************************************************************************************** |
---|
172 | * @ info : [out] pointer on thread_info_t structure in user space. |
---|
173 | * @ return 0 if success / return -1 if illegal argument. |
---|
174 | *****************************************************************************************/ |
---|
175 | int get_thread_info( thread_info_t * info ); |
---|
176 | |
---|
177 | /*************************************************************************************** |
---|
178 | * This debug syscall displays on the kernel terminal TXT0 |
---|
179 | * the thread / process / core identifiers, the current cycle, plus a user defined |
---|
180 | * message as specified by the <string> argument. |
---|
181 | *************************************************************************************** |
---|
182 | * @ string : [in] user defined message. |
---|
183 | **************************************************************************************/ |
---|
184 | void display_string( char * string ); |
---|
185 | |
---|
186 | /*************************************************************************************** |
---|
187 | * This debug function displays on the kernel terminal TXT0 |
---|
188 | * the state of the VMM for the process <pid> in cluster <cxy>. |
---|
189 | * It can be called by any thread running in any cluster. |
---|
190 | *************************************************************************************** |
---|
191 | * @ cxy : [in] target cluster identifier. |
---|
192 | * @ pid : [in] process identifier. |
---|
193 | * @ mapping : [in] detailed mapping if non zero. |
---|
194 | * @ return 0 if success / return -1 if illegal argument. |
---|
195 | **************************************************************************************/ |
---|
196 | int display_vmm( unsigned int cxy, |
---|
197 | unsigned int pid, |
---|
198 | unsigned int mapping ); |
---|
199 | |
---|
200 | /*************************************************************************************** |
---|
201 | * This debug syscall displays on the kernel terminal TXT0 |
---|
202 | * the state of the core scheduler identified by the <cxy> and <lid> arguments. |
---|
203 | * It can be called by any thread running in any cluster. |
---|
204 | *************************************************************************************** |
---|
205 | * @ cxy : [in] target cluster identifier. |
---|
206 | * @ lid : [in] target core local index. |
---|
207 | * @ return 0 if success / return -1 if illegal arguments. |
---|
208 | **************************************************************************************/ |
---|
209 | int display_sched( unsigned int cxy, |
---|
210 | unsigned int lid ); |
---|
211 | |
---|
212 | /*************************************************************************************** |
---|
213 | * This debug syscall displays on the kernel terminal TXT0 |
---|
214 | * the list of process registered in a given cluster identified by the <cxy> argument. |
---|
215 | * Only the owned processes are displayed when the <owned> argument is non zero. |
---|
216 | * It can be called by any thread running in any cluster. |
---|
217 | *************************************************************************************** |
---|
218 | * @ cxy : [in] target cluster identifier. |
---|
219 | * @ owned : [in] only owned processes if non zero. |
---|
220 | * @ return 0 if success / return -1 if illegal argument. |
---|
221 | **************************************************************************************/ |
---|
222 | int display_cluster_processes( unsigned int cxy, |
---|
223 | unsigned int owned ); |
---|
224 | |
---|
225 | /*************************************************************************************** |
---|
226 | * This debug syscall displays on the kernel terminal TXT0 |
---|
227 | * the list of processes attached to a given TXT channel. |
---|
228 | * It can be called by any thread running in any cluster. |
---|
229 | *************************************************************************************** |
---|
230 | * @ txt_id : [in] TXT terminal indes. |
---|
231 | * @ return 0 if success / return -1 if illegal argument. |
---|
232 | **************************************************************************************/ |
---|
233 | int display_txt_processes( unsigned int txt_id ); |
---|
234 | |
---|
235 | /*************************************************************************************** |
---|
236 | * This debug syscall displays on the kernel terminal TXT0 |
---|
237 | * the set of busylocks hold by a thread identified by the <pid> and <trdid> arguments. |
---|
238 | * It can be called by any thread running in any cluster. |
---|
239 | *************************************************************************************** |
---|
240 | * @ pid : [in] process identifier. |
---|
241 | * @ trdid : [in] thread identifier. |
---|
242 | * @ return 0 if success / return -1 if illegal arguments. |
---|
243 | **************************************************************************************/ |
---|
244 | int display_busylocks( unsigned int pid, |
---|
245 | unsigned int trdid ); |
---|
246 | |
---|
247 | /*************************************************************************************** |
---|
248 | * This debug syscall displays on the kernel terminal TXT0 |
---|
249 | * the list of channel devices available in the architecture. |
---|
250 | * It can be called by any thread running in any cluster. |
---|
251 | *************************************************************************************** |
---|
252 | * @ return always 0. |
---|
253 | **************************************************************************************/ |
---|
254 | int display_chdev( void ); |
---|
255 | |
---|
256 | /*************************************************************************************** |
---|
257 | * This debug syscall displays on the kernel terminal TXT0 |
---|
258 | * the list of channel device or pseudo-files registered in the VFS cache. |
---|
259 | * It can be called by any thread running in any cluster. |
---|
260 | *************************************************************************************** |
---|
261 | * @ return always 0. |
---|
262 | **************************************************************************************/ |
---|
263 | int display_vfs( void ); |
---|
264 | |
---|
265 | /*************************************************************************************** |
---|
266 | * This debug syscall displays on the kernel terminal TXT0 the current DQDT state. |
---|
267 | * It can be called by any thread running in any cluster. |
---|
268 | *************************************************************************************** |
---|
269 | * @ return always 0. |
---|
270 | **************************************************************************************/ |
---|
271 | int display_dqdt( void ); |
---|
272 | |
---|
273 | /*************************************************************************************** |
---|
274 | * This debug syscall displays on the kernel terminal TXT0 the content of a given |
---|
275 | * page of a given VFS mapper. |
---|
276 | * It can be called by any thread running in any cluster. |
---|
277 | *************************************************************************************** |
---|
278 | * @ path : pathname identifying the file/directory in VFS. |
---|
279 | * @ page_id : page index in file. |
---|
280 | * @ nbytes : number of bytes to display. |
---|
281 | * @ return 0 if success / return -1 if file or page not found. |
---|
282 | **************************************************************************************/ |
---|
283 | int display_mapper( char * path, |
---|
284 | unsigned int page_id, |
---|
285 | unsigned int nbytes); |
---|
286 | |
---|
287 | /*************************************************************************************** |
---|
288 | * This debug syscall displays on the kernel terminal TXT0 |
---|
289 | * the state of the barrier used by the process identified by the <pid> argument. |
---|
290 | * It can be called by any thread running in any cluster. |
---|
291 | *************************************************************************************** |
---|
292 | * @ pid : [in] process identifier. |
---|
293 | * @ return 0 if success / return -1 if illegal arguments. |
---|
294 | **************************************************************************************/ |
---|
295 | int display_barrier( unsigned int pid ); |
---|
296 | |
---|
297 | /*************************************************************************************** |
---|
298 | * This debug syscall displays on the kernel terminal TXT0 the content of <nb_slots> |
---|
299 | * of the FAT mapper, starting from <min_slot>. |
---|
300 | * If <nb_slots> is zero, it displays the state of the FATFS context in cluster |
---|
301 | * defined by the <min_slot> argument interpreted as a cluster identifier. |
---|
302 | * It can be called by any thread running in any cluster. |
---|
303 | *************************************************************************************** |
---|
304 | * @ min_slot : first slot in page |
---|
305 | * @ nb_slots : number of slots to display. |
---|
306 | * @ return 0 if success / return -1 if page not found. |
---|
307 | **************************************************************************************/ |
---|
308 | int display_fat( unsigned int min_slot, |
---|
309 | unsigned int nb_slots ); |
---|
310 | |
---|
311 | /***************************************************************************************** |
---|
312 | * This debug syscall is used to activate / desactivate the context switches trace |
---|
313 | * for a core identified by the <cxy> and <lid> arguments. |
---|
314 | * It can be called by any thread running in any cluster. |
---|
315 | ***************************************************************************************** |
---|
316 | * @ active : activate trace if non zero / desactivate if zero. |
---|
317 | * @ cxy : cluster identifier. |
---|
318 | * @ lid : core local index. |
---|
319 | * @ returns O if success / returns -1 if illegal arguments. |
---|
320 | ****************************************************************************************/ |
---|
321 | int trace( unsigned int active, |
---|
322 | unsigned int cxy, |
---|
323 | unsigned int lid ); |
---|
324 | |
---|
325 | /**************************************************************************************** |
---|
326 | * This syscall implements an user-level interactive debugger that can be |
---|
327 | * introduced in any user application to display various kernel distributed structures. |
---|
328 | ***************************************************************************************/ |
---|
329 | void idbg( void ); |
---|
330 | |
---|
331 | |
---|
332 | /****************** Non standard (ALMOS-MKH specific) malloc operations ***************/ |
---|
333 | |
---|
334 | ///////////////////////////////////////////////////////////////////////////////////////// |
---|
335 | // General principles: |
---|
336 | // - In user space the HEAP zone spread between the ELF zone and the STACK zone, |
---|
337 | // as defined in the kernel_config.h file. |
---|
338 | // - The malloc library uses the mmap() syscall to create - on demand - |
---|
339 | // one vseg in a given cluster. The size of this vseg is defined below |
---|
340 | // by the MALLOC_LOCAL_STORE_SIZE parameter. |
---|
341 | // - For a standard malloc(), the target cluster is the cluster containing |
---|
342 | // the core running the client thread. |
---|
343 | // - For a remote_malloc(), the target cluster is explicitely defined |
---|
344 | // by the argument. |
---|
345 | // - In each cluster, the available storage in virtual space is handled by a |
---|
346 | // local allocator using the buddy algorithm. |
---|
347 | // |
---|
348 | // TODO : In this first implementation one single - fixed size - vseg |
---|
349 | // is allocated on demand in each cluster. |
---|
350 | // We should introduce the possibility to dynamically allocate |
---|
351 | // several vsegs in each cluster, using several mmap when required. |
---|
352 | ///////////////////////////////////////////////////////////////////////////////////////// |
---|
353 | // Free blocks organisation in each cluster : |
---|
354 | // - All free blocks have a size that is a power of 2, larger or equal |
---|
355 | // to MALLOC_MIN_BLOCK_SIZE (typically 64 bytes). |
---|
356 | // - All free blocks are aligned. |
---|
357 | // - They are pre-classed in an array of linked lists, where all blocks in a |
---|
358 | // given list have the same size. |
---|
359 | // - The NEXT pointer implementing those linked lists is written |
---|
360 | // in the first bytes of the block itself, using the unsigned int type. |
---|
361 | // - The pointers on the first free block for each size are stored in an |
---|
362 | // array of pointers free[32] in the storage(x,y) descriptor. |
---|
363 | ///////////////////////////////////////////////////////////////////////////////////////// |
---|
364 | // Allocation policy: |
---|
365 | // - The block size required by the user can be any value, but the allocated |
---|
366 | // block size can be larger than the requested size: |
---|
367 | // - The allocator computes actual_size, that is the smallest power of 2 |
---|
368 | // value larger or equal to the requested size AND larger or equal to |
---|
369 | // MALLOC_MIN_BLOCK_SIZE. |
---|
370 | // - It pop the linked list of free blocks corresponding to actual_size, |
---|
371 | // and returns the block B if the list[actual_size] is not empty. |
---|
372 | // - If the list[actual_size] is empty, it pop the list[actual_size * 2]. |
---|
373 | // If a block B' is found, it breaks this block in 2 B/2 blocks, returns |
---|
374 | // the first B/2 block and push the other B/2 block into list[actual_size]. |
---|
375 | // - If the list[actual_size * 2] is empty, it pop the list[actual_size * 4]. |
---|
376 | // If a block B is found, it break this block in 3 blocks B/4, B/4 and B/2, |
---|
377 | // returns the first B/4 block, push the other blocks B/4 and B/2 into |
---|
378 | // the proper lists. etc... |
---|
379 | // - If no block satisfying the request is available it returns a failure |
---|
380 | // (NULL pointer). |
---|
381 | // - This allocation policy has the nice following property: |
---|
382 | // If the vseg is aligned (the vseg base is a multiple of the |
---|
383 | // vseg size), all allocated blocks are aligned on the actual_size. |
---|
384 | ///////////////////////////////////////////////////////////////////////////////////////// |
---|
385 | // Free policy: |
---|
386 | // - Each allocated block is registered in an alloc[] array of unsigned char. |
---|
387 | // - This registration is required by the free() operation, because the size |
---|
388 | // of the allocated block must be obtained from the base address of the block. |
---|
389 | // - The number of entries in this array is equal to the max number |
---|
390 | // of allocated block : MALLOC_LOCAL_STORE_SIZE / MALLOC_MIN_BLOCK_SIZE. |
---|
391 | // - For each allocated block, the value registered in the alloc[] array |
---|
392 | // is log2( size_of_allocated_block ). |
---|
393 | // - The index in this array is computed from the allocated block base address: |
---|
394 | // index = (block_base - vseg_base) / MALLOC_MIN_BLOCK_SIZE |
---|
395 | // - The alloc[] array is stored at the end of heap segment. This consume |
---|
396 | // (1 / MALLOC_MIN_BLOCK_SIZE) of the total storage capacity. |
---|
397 | ///////////////////////////////////////////////////////////////////////////////////////// |
---|
398 | |
---|
399 | |
---|
400 | #define MALLOC_INITIALIZED 0xBABEF00D // magic number when initialised |
---|
401 | #define MALLOC_MIN_BLOCK_SIZE 0x40 // 64 bytes |
---|
402 | #define MALLOC_LOCAL_STORE_SIZE 0x2000000 // 32 Mbytes |
---|
403 | #define MALLOC_MAX_CLUSTERS 0x100 // 256 clusters |
---|
404 | |
---|
405 | ///////////////////////////////////////////////////////////////////////////////////////// |
---|
406 | // store(x,y) descriptor (one per cluster) |
---|
407 | ///////////////////////////////////////////////////////////////////////////////////////// |
---|
408 | |
---|
409 | typedef struct malloc_store_s |
---|
410 | { |
---|
411 | pthread_mutex_t mutex; // lock protecting exclusive access to local heap |
---|
412 | unsigned int initialized; // initialised when value == MALLOC_INITIALIZED |
---|
413 | unsigned int cxy; // cluster identifier |
---|
414 | unsigned int store_base; // store base address |
---|
415 | unsigned int store_size; // store size (bytes) |
---|
416 | unsigned int alloc_base; // alloc[] array base address |
---|
417 | unsigned int alloc_size; // alloc[] array size (bytes) |
---|
418 | unsigned int free[32]; // array of addresses of first free block |
---|
419 | } |
---|
420 | malloc_store_t; |
---|
421 | |
---|
422 | /***************************************************************************************** |
---|
423 | * This function allocates <size> bytes of memory in user space, and returns a pointer |
---|
424 | * to the allocated buffer. The pysical memory is allocated from store located in |
---|
425 | * cluster identified by the <cxy> argument. |
---|
426 | ***************************************************************************************** |
---|
427 | * @ size : number of requested bytes. |
---|
428 | * @ cxy : target cluster identifier. |
---|
429 | * @ returns a pointer on the allocated buffer if success / returns NULL if failure |
---|
430 | ****************************************************************************************/ |
---|
431 | void * remote_malloc( unsigned int size, |
---|
432 | unsigned int cxy ); |
---|
433 | |
---|
434 | /***************************************************************************************** |
---|
435 | * This function releases the memory buffer identified by the <ptr> argument, |
---|
436 | * to the store identified by the <cxy> argument. |
---|
437 | * It does nothing, but displays an error message, if the ptr is illegal. |
---|
438 | ***************************************************************************************** |
---|
439 | * @ ptr : pointer on the released buffer. |
---|
440 | * @ cxy : target cluster identifier. |
---|
441 | ****************************************************************************************/ |
---|
442 | void remote_free( void * ptr, |
---|
443 | unsigned int cxy ); |
---|
444 | |
---|
445 | /***************************************************************************************** |
---|
446 | * This function releases the memory buffer identified by the <ptr> argument, |
---|
447 | * to the store located in cluster identified by the <cxy> argument, and allocates |
---|
448 | * a new buffer containing <size> bytes from this store. |
---|
449 | * The content of the old buffer is copied to the new buffer, up to <size> bytes. |
---|
450 | * It displays an error message, but does nothing if the ptr is illegal. |
---|
451 | ***************************************************************************************** |
---|
452 | * @ ptr : pointer on the released buffer. |
---|
453 | * @ size : new buffer requested size (bytes). |
---|
454 | * @ cxy : target cluster identifier. |
---|
455 | * @ return a pointer on allocated buffer if success / return NULL if failure |
---|
456 | ****************************************************************************************/ |
---|
457 | void * remote_realloc( void * ptr, |
---|
458 | unsigned int size, |
---|
459 | unsigned int cxy ); |
---|
460 | |
---|
461 | /***************************************************************************************** |
---|
462 | * This function allocates enough space for <count> objects that are <size> bytes |
---|
463 | * of memory each from the store located in cluster identied by the <cxy> argument. |
---|
464 | * The allocated memory is filled with bytes of value zero. |
---|
465 | ***************************************************************************************** |
---|
466 | * @ count : number of requested objects. |
---|
467 | * @ size : number of bytes per object. |
---|
468 | * @ cxy : target cluster identifier. |
---|
469 | * @ returns a pointer on allocated buffer if success / returns NULL if failure |
---|
470 | ****************************************************************************************/ |
---|
471 | void * remote_calloc( unsigned int count, |
---|
472 | unsigned int size, |
---|
473 | unsigned int cxy ); |
---|
474 | |
---|
475 | /********* Non standard (ALMOS-MKH specific) pthread_parallel_create() syscall *********/ |
---|
476 | |
---|
477 | ////////////////////////////////////////////////////////////////////////////////////////// |
---|
478 | // This syscall can be used to parallelize the creation, and the termination |
---|
479 | // of a parallel multi-threaded application. |
---|
480 | // It removes in the main thread the sequencial loop that creates the N working threads |
---|
481 | // (N pthread_create() ), and removes also the sequencial loop that waits completion |
---|
482 | // of these N working threads (N pthread_join() ). |
---|
483 | // It creates one <work> thread (in detached mode) per core in the target architecture. |
---|
484 | // Each <work> thread is identified by a continuous [tid] index. |
---|
485 | // For a regular architecture, defined by the [x_size , y_size , ncores] parameters, |
---|
486 | // the number of working threads can be the simply computed as (x_size * y_size * ncores), |
---|
487 | // and the coordinates[x,y,lid] of the core running the thread[tid] cand be directly |
---|
488 | // derived from the [tid] value with the following relations: |
---|
489 | // . cid = (x * y_size) + y |
---|
490 | // . tid = (cid * ncores ) + lid |
---|
491 | // . lid = tid % ncores |
---|
492 | // . cid = tid / ncores |
---|
493 | // . y = cid % y_size |
---|
494 | // . x = cid / y_size |
---|
495 | // The pthread_parallel_create() function returns only when all <work> threads completed |
---|
496 | // (successfully or not). |
---|
497 | // |
---|
498 | // WARNING : The function executed by the working thread is application specific, |
---|
499 | // but the structure defining the arguments passed to this function is imposed. |
---|
500 | // The "pthread_parallel_work_args_t" structure is defined below, and contains |
---|
501 | // two fields: the tid value, and a pointer on a pthread_barrier_t. |
---|
502 | // This barrier must be used by each working thread to signal completion before exit. |
---|
503 | // The global variables implementing these stuctures for each working thread |
---|
504 | // are allocated and initialised by the pthread_parallel_create() function. |
---|
505 | // |
---|
506 | // Implementation note: the pthread_parallel_create()a function creates a distributed |
---|
507 | // quad-tree (DQT) of <build> threads covering all cores required to execute the parallel |
---|
508 | // application. This quad tree is entirely defined by the root_level parameter. |
---|
509 | // Depending on the hardware topology, this DQT can be truncated, (i.e. some |
---|
510 | // parent nodes can have less than 4 chidren), if (x_size != y_size), or if one size |
---|
511 | // is not a power of 2. Each <build> thread is identified by two indexes [cid][level]. |
---|
512 | // Each <build> thread makes the following tasks: |
---|
513 | // 1) It calls the pthread_create() function to create up to 4 children threads, that |
---|
514 | // are <work> threads when (level == 0), or <build> threads, when (level > 0). |
---|
515 | // 2) It allocates and initializes the barrier, used to block the parent thread until |
---|
516 | // children completion. |
---|
517 | // 3) It calls the pthread_barrier_wait( self ) to wait until all children threads |
---|
518 | // completed (successfully or not). |
---|
519 | // 4) It calls the pthread_barrier_wait( parent ) to unblock the parent thread. |
---|
520 | ////////////////////////////////////////////////////////////////////////////////////////// |
---|
521 | |
---|
522 | /***************************************************************************************** |
---|
523 | * structure defining the arguments for the <build> thread function |
---|
524 | ****************************************************************************************/ |
---|
525 | typedef struct pthread_parallel_build_args_s |
---|
526 | { |
---|
527 | unsigned char cid; // this <build> thread cluster index |
---|
528 | unsigned char level; // this <build> thread level in quad-tree |
---|
529 | unsigned char parent_cid; // parent <build> thread cluster index |
---|
530 | pthread_barrier_t * parent_barrier; // pointer on parent <build> thread barrier |
---|
531 | unsigned char root_level; // quad-tree root level |
---|
532 | void * work_func; // pointer on working thread function |
---|
533 | unsigned int x_size; // platform global parameter |
---|
534 | unsigned int y_size; // platform global parameter |
---|
535 | unsigned int ncores; // platform global parameter |
---|
536 | unsigned int error; // return value : 0 if success |
---|
537 | } |
---|
538 | pthread_parallel_build_args_t; |
---|
539 | |
---|
540 | /***************************************************************************************** |
---|
541 | * structure defining the arguments for the <work> thread function |
---|
542 | ****************************************************************************************/ |
---|
543 | typedef struct pthread_parallel_work_args_s |
---|
544 | { |
---|
545 | unsigned int tid; // thread identifier |
---|
546 | pthread_barrier_t * barrier; // to signal completion |
---|
547 | } |
---|
548 | pthread_parallel_work_args_t; |
---|
549 | |
---|
550 | /***************************************************************************************** |
---|
551 | * This blocking function creates N working threads identified by the [tid] continuous |
---|
552 | * index, that execute the code defined by the <work_func> argument, and returns only |
---|
553 | * when all working threads completed. |
---|
554 | * The number N of created threads is entirely defined by the <root_level> argument, |
---|
555 | * that defines an abstract quad-tree, with a square base : root_level in [0,1,2,3,4], |
---|
556 | * side in [1,2,4,8,16], nclusters in [1,4,16,64,256]. This base is called macro_cluster. |
---|
557 | * A working thread is created on all cores contained in this abstract macro-cluster. |
---|
558 | * The actual number of physical clusters containing cores can be smaller than the number |
---|
559 | * of clusters covered by the abstract quad tree. |
---|
560 | * All threads execute the same <work_func> function, on different arguments, that are |
---|
561 | * specified as an array of structures pthread_parallel_work_args_t, allocated and |
---|
562 | * initialised by this function. |
---|
563 | ***************************************************************************************** |
---|
564 | * @ root_level : [in] DQT root level in [0,1,2,3,4]. |
---|
565 | * @ work_func : [in] pointer on start function. |
---|
566 | * @ return 0 if success / return -1 if failure. |
---|
567 | ****************************************************************************************/ |
---|
568 | int pthread_parallel_create( unsigned int root_level, |
---|
569 | void * work_func ); |
---|
570 | |
---|
571 | |
---|
572 | |
---|
573 | /********* Non standard (ALMOS-MKH specific) Frame Buffer access syscalls *************/ |
---|
574 | |
---|
575 | ////////////////////////////////////////////////////////////////////////////////////////// |
---|
576 | // The following system calls can be used to access the SoCLib Frame Buffer, that |
---|
577 | // is a very simple graphic controller, that is seen by the software as a single |
---|
578 | // buffer of <height> lines of <width> pixels. |
---|
579 | ////////////////////////////////////////////////////////////////////////////////////////// |
---|
580 | |
---|
581 | /***************************************************************************************** |
---|
582 | * This function returns in the <width>, <height> and <type> arguments |
---|
583 | * the implementation specific frame buffer features. |
---|
584 | ***************************************************************************************** |
---|
585 | * @ width : [out] number of pixels per line. |
---|
586 | * @ height : [out] number of lines. |
---|
587 | * @ type : [out] pixel encoding type. |
---|
588 | * @ returns 0 if success / returns -1 if not found. |
---|
589 | ****************************************************************************************/ |
---|
590 | int fbf_get_config( unsigned int * width, |
---|
591 | unsigned int * height, |
---|
592 | unsigned int * type ); |
---|
593 | |
---|
594 | /***************************************************************************************** |
---|
595 | * This function creates a new window defined by the <l_zero>, <p_zero>, <nlines>, |
---|
596 | * and <npixels> arguments for the calling process, and register the process PID, the |
---|
597 | * allocated <wid>, and the window size and coordinates in the FBF device descriptor. |
---|
598 | * It returns in the output argument <buffer> the pointer on the buffer associated to |
---|
599 | * the window, mapped in user space. |
---|
600 | * Warning : Both pixel [p_zero,l_zero] and pixel [p_zero+npixels-1,l_zero+nlines-1] |
---|
601 | * must be contained in the frame buffer. |
---|
602 | ***************************************************************************************** |
---|
603 | * @ l_zero : [in] first line index in FBF coordinates system. |
---|
604 | * @ p_zero : [in] first pixel index in FBF coordinates system. |
---|
605 | * @ nlines : [in] number of lines in the window. |
---|
606 | * @ npixels : [in] number of pixels per line in the window. |
---|
607 | * @ buffer : [out] pointer on |
---|
608 | * @ returns <wid> if success / returns -1 if illegal size or coordinates. |
---|
609 | ****************************************************************************************/ |
---|
610 | int fbf_create_window( unsigned int l_zero, |
---|
611 | unsigned int p_zero, |
---|
612 | unsigned int nlines, |
---|
613 | unsigned int npixels, |
---|
614 | void ** buffer ); |
---|
615 | |
---|
616 | /***************************************************************************************** |
---|
617 | * This function deletes an existing window, identified by the <wid> argument. |
---|
618 | * The calling process must be the window owner. |
---|
619 | ***************************************************************************************** |
---|
620 | * @ wid : window identifier. |
---|
621 | * @ returns 0 if success / returns -1 if not found or process not owner. |
---|
622 | ****************************************************************************************/ |
---|
623 | int fbf_delete_window( unsigned int wid ); |
---|
624 | |
---|
625 | /***************************************************************************************** |
---|
626 | * This function refreshes in FBF all lines of a window identified by the <wid> argument, |
---|
627 | * when the line index is in the interval [line_first,line_last[. |
---|
628 | * It scans all registered windows to take into account the windows overlap. |
---|
629 | ***************************************************************************************** |
---|
630 | * @ wid : window identifier. |
---|
631 | * @ line_first : first line index. |
---|
632 | * @ line_last : last line index (excluded). |
---|
633 | * @ returns 0 if success / returns -1 if illegal argument. |
---|
634 | ****************************************************************************************/ |
---|
635 | int fbf_refresh_window( unsigned int wid, |
---|
636 | unsigned int line_first, |
---|
637 | unsigned int line_last ); |
---|
638 | |
---|
639 | /***************************************************************************************** |
---|
640 | * This function changes the size of a window identified by the <wid> argument as defined |
---|
641 | * by the <width> and height> arguments. The calling process must be the window owner. |
---|
642 | * WARNING : Both pixel [p_zero,l_zero] and pixel [p_zero+width-1,l_zero+height-1] |
---|
643 | * must be contained in the frame buffer. |
---|
644 | ***************************************************************************************** |
---|
645 | * @ wid : window identifier. |
---|
646 | * @ width : number of pixels in line (one byte per pixel). |
---|
647 | * @ height : number of lines in window. |
---|
648 | * @ returns 0 if success / returns -1 if illegal arguments. |
---|
649 | ****************************************************************************************/ |
---|
650 | int fbf_resize_window( unsigned int wid, |
---|
651 | unsigned int width, |
---|
652 | unsigned int height ); |
---|
653 | |
---|
654 | /***************************************************************************************** |
---|
655 | * This function changes the <l_zero> & <p_zero> coordinates of a window identified |
---|
656 | * by the <wid> argument. The calling process must be the window owner. |
---|
657 | * WARNING : Both pixel [p_zero,l_zero] and pixel [p_zero+width-1,l_zero+height-1] |
---|
658 | * must be contained in the frame buffer. |
---|
659 | ***************************************************************************************** |
---|
660 | * @ wid : window identifier. |
---|
661 | * @ l_zero : new first line index in FBF. |
---|
662 | * @ p_zero : new first pixel index in FBF. |
---|
663 | * @ returns 0 if success / returns -1 if illegal arguments. |
---|
664 | ****************************************************************************************/ |
---|
665 | int fbf_move_window( unsigned int wid, |
---|
666 | unsigned int l_zero, |
---|
667 | unsigned int p_zero ); |
---|
668 | |
---|
669 | /***************************************************************************************** |
---|
670 | * This syscall is deprecated (january 2020 AG) |
---|
671 | * This blocking function moves <length> pixels from the user buffer defined by <buffer> |
---|
672 | * argument to the frame buffer, starting at <offset> in FBF. |
---|
673 | ***************************************************************************************** |
---|
674 | * @ buffer : pointer on buffer in user space. |
---|
675 | * @ length : number of pixels (one byte per pixel). |
---|
676 | * @ offset : first pixel index in window. |
---|
677 | * @ returns 0 if success / returns -1 if illegal arguments. |
---|
678 | ****************************************************************************************/ |
---|
679 | int fbf_write( void * buffer, |
---|
680 | unsigned int length, |
---|
681 | unsigned int offset ); |
---|
682 | |
---|
683 | /***************************************************************************************** |
---|
684 | * This syscall is deprecated (january 2020 AG) |
---|
685 | * This blocking function moves <length> pixels from the frame buffer, starting at |
---|
686 | * <offset> in FBF, to the user buffer defined by <buffer> argument. |
---|
687 | ***************************************************************************************** |
---|
688 | * @ buffer : pointer on buffer in user space. |
---|
689 | * @ length : number of pixels (one byte per pixel). |
---|
690 | * @ offset : first pixel index in window. |
---|
691 | * @ returns 0 if success / returns -1 if illegal arguments. |
---|
692 | ****************************************************************************************/ |
---|
693 | int fbf_read( void * buffer, |
---|
694 | unsigned int length, |
---|
695 | unsigned int offset ); |
---|
696 | |
---|
697 | |
---|
698 | #endif /* _LIBALMOSMKH_H_ */ |
---|
699 | |
---|