source: trunk/libs/libalmosmkh/almosmkh.h @ 678

Last change on this file since 678 was 678, checked in by alain, 18 months ago

Introduce the fget_string() function.

File size: 43.0 KB
Line 
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 **************************************************************************************/
50int 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 **************************************************************************************/
61int is_fg( unsigned int pid,
62           unsigned int * owner );
63
64/***************************************************************************************
65 * This syscall returns the hardware platform parameters in the hard_config_t pointed
66 * by the <config> argument. This structure is defined in the shared_almos.h file.
67 * The available configuration parameters are :
68 * - cores       : x_size / y_size / ncores
69 * - peripherals : nb_txt_channels / nb_nic_channels / nb_ioc_channels / nb_fbf_channels
70 ***************************************************************************************
71 * @ config   : [out] pointer on hard_config_t structure in user space.
72 * @ return 0 if success / return -1 if illegal argument.
73 **************************************************************************************/
74int get_config( struct hard_config_s * config );
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 **************************************************************************************/
84int 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 **************************************************************************************/
94int 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 **************************************************************************************/
109int 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 **************************************************************************************/
121int 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 **************************************************************************************/
130int 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 **************************************************************************************/
139int utls( unsigned int operation,
140          unsigned int value );
141
142/***************************************************************************************
143 * This syscall returns an 32 bits integer from the TXT terminal.
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 **************************************************************************************/
150void get_uint32( unsigned int * buffer );
151
152
153/***************************************************************************************
154 * These syscalls return a NUL terminated character string from the TXT terminal.
155 * The characters are copied in buffer pointed by the <string> argument.
156 * If the number of characters exceeds <maxlen>, all read characters are discarded,
157 * and removed from the <string> buffer, and a new string capture start.
158 * - Only printable characters c such as (0x20 <= c) and (c < 0x7f) are echoed
159 *   and copied in the target buffer.
160 * - The LF (0x0A) character signaling the end of string is replaced by an extra
161 *   NUL (0x00) character in the target buffer.
162 * - the DEL (0x7F), BS (0x08) control characters are taken into account, and can be
163 *   used to correct both the buffer content and the echoed string.
164 ***************************************************************************************
165 * @ string   : pointer on the user space string buffer.
166 * @ maxlen   : max number of bytes in string buffer, including the terminating NUL.
167 * @ returns string length (including NUL) if success / returns 0 if failure.
168 **************************************************************************************/
169int get_string( char * string,
170                int    maxlen );
171
172
173/***************** Non standard (ALMOS-MKH specific) debug functions ******************/
174
175/***************************************************************************************
176 * This syscall copies in the user structure defined by the <info> argument the values
177 * registered in the calling thread "thread_info_t" kernel structure.
178 ******************************************************************************************
179 * @ info    : [out] pointer on thread_info_t structure in user space.
180 * @ return 0 if success / return -1 if illegal argument.
181 *****************************************************************************************/
182int get_thread_info( thread_info_t * info );
183
184/***************************************************************************************
185 * This debug syscall displays on the kernel terminal TXT0
186 * the thread / process / core identifiers, the current cycle, plus a user defined
187 * message as specified by the <string> argument.
188 ***************************************************************************************
189 * @ string    : [in] user defined message.
190 **************************************************************************************/
191void display_string( char * string );
192
193/***************************************************************************************
194 * This debug function displays on the kernel terminal TXT0
195 * the state of the  VMM for the process <pid> in cluster <cxy>.
196 * It can be called by any thread running in any cluster.
197 ***************************************************************************************
198 * @ cxy      : [in] target cluster identifier.
199 * @ pid      : [in] process identifier.
200 * @ mapping  : [in] detailed mapping if non zero.
201 * @ return 0 if success / return -1 if illegal argument.
202 **************************************************************************************/
203int display_vmm( unsigned int cxy,
204                 unsigned int pid,
205                 unsigned int mapping );
206
207/***************************************************************************************
208 * This debug syscall displays on the kernel terminal TXT0
209 * the state of the core scheduler identified by the <cxy> and <lid> arguments.
210 * It can be called by any thread running in any cluster.
211 ***************************************************************************************
212 * @ cxy      : [in] target cluster identifier.
213 * @ lid      : [in] target core local index.
214 * @ return 0 if success / return -1 if illegal arguments.
215 **************************************************************************************/
216int display_sched( unsigned int  cxy,
217                   unsigned int  lid );
218
219/***************************************************************************************
220 * This debug syscall displays on the kernel terminal TXT0
221 * the list of process registered in a given cluster identified by the <cxy> argument.
222 * Only the owned processes are displayed when the <owned> argument is non zero.
223 * It can be called by any thread running in any cluster.
224 ***************************************************************************************
225 * @ cxy      : [in] target cluster identifier.
226 * @ owned    : [in] only owned processes if non zero.
227 * @ return 0 if success / return -1 if illegal argument.
228 **************************************************************************************/
229int display_cluster_processes( unsigned int  cxy,
230                               unsigned int  owned );
231
232/***************************************************************************************
233 * This debug syscall displays on the kernel terminal TXT0
234 * the list of processes attached to a given TXT channel.
235 * It can be called by any thread running in any cluster.
236 ***************************************************************************************
237 * @ txt_id   : [in] TXT terminal indes.
238 * @ return 0 if success / return -1 if illegal argument.
239 **************************************************************************************/
240int display_txt_processes( unsigned int txt_id );
241
242/***************************************************************************************
243 * This debug syscall displays on the kernel terminal TXT0
244 * the set of busylocks hold by a thread identified by the <pid> and <trdid> arguments.
245 * It can be called by any thread running in any cluster.
246 ***************************************************************************************
247 * @ pid      : [in] process identifier.
248 * @ trdid    : [in] thread identifier.
249 * @ return 0 if success / return -1 if illegal arguments.
250 **************************************************************************************/
251int display_busylocks( unsigned int pid,
252                       unsigned int trdid );
253
254/***************************************************************************************
255 * This debug syscall displays on the kernel terminal TXT0
256 * the list of channel devices available in the architecture.
257 * It can be called by any thread running in any cluster.
258 ***************************************************************************************
259 * @ return always 0.
260 **************************************************************************************/
261int display_chdev( void );
262
263/***************************************************************************************
264 * This debug syscall displays on the kernel terminal TXT0
265 * the list of channel device or pseudo-files registered in the VFS cache.
266 * It can be called by any thread running in any cluster.
267 ***************************************************************************************
268 * @ return always 0.
269 **************************************************************************************/
270int display_vfs( void );
271
272/***************************************************************************************
273 * This debug syscall displays on the kernel terminal TXT0 the current DQDT state.
274 * It can be called by any thread running in any cluster.
275 ***************************************************************************************
276 * @ return always 0.
277 **************************************************************************************/
278int display_dqdt( void );
279
280/***************************************************************************************
281 * This debug syscall displays on the kernel terminal TXT0 the content of a given
282 * page of a given VFS mapper.
283 * It can be called by any thread running in any cluster.
284 ***************************************************************************************
285 * @ path      : pathname identifying the file/directory in VFS.
286 * @ page_id   : page index in file.
287 * @ nbytes    : number of bytes to display.
288 * @ return 0 if success / return -1 if file or page not found.
289 **************************************************************************************/
290int display_mapper( char        * path,
291                    unsigned int  page_id,
292                    unsigned int  nbytes);
293
294/***************************************************************************************
295 * This debug syscall displays on the kernel terminal TXT0
296 * the state of the barrier used by the process identified by the <pid> argument.
297 * It can be called by any thread running in any cluster.
298 ***************************************************************************************
299 * @ pid      : [in] process identifier.
300 * @ return 0 if success / return -1 if illegal arguments.
301 **************************************************************************************/
302int display_barrier( unsigned int pid );
303
304/***************************************************************************************
305 * This debug syscall displays on the kernel terminal TXT0 the content of <nb_slots>
306 * of the FAT mapper, starting from <min_slot>.
307 * If <nb_slots> is zero, it displays the state of the FATFS context in cluster
308 * defined by the <min_slot> argument interpreted as a cluster identifier.
309 * It can be called by any thread running in any cluster.
310 ***************************************************************************************
311 * @ min_slot   : first slot in page
312 * @ nb_slots   : number of slots to display.
313 * @ return 0 if success / return -1 if page not found.
314 **************************************************************************************/
315int display_fat( unsigned int min_slot,
316                 unsigned int nb_slots );
317
318/***************************************************************************************
319 * This debug syscall displays on the kernel terminal the current state of
320 * a socket identified by the <pid> and <fdid> arguments.
321 * It can be called by any thread running in any cluster.
322 ***************************************************************************************
323 * @ pid        : target process identifier.
324 * @ fdid       : file descriptor identifying the target socket.
325 * @ return 0 if success / return -1 if socket not found.
326 **************************************************************************************/
327int display_socket( unsigned int pid,
328                    unsigned int fdid );
329
330/***************************************************************************************
331 * This debug syscall displays on the kernel terminal the set of open file descriptors
332 * registered in the fd_array of a process identified by the <pid> argument.
333 * It can be called by any thread running in any cluster.
334 ***************************************************************************************
335 * @ pid        : target process identifier.
336 setoreturn 0 if success / return -1 if undefined pid.
337 **************************************************************************************/
338int display_fd_array( unsigned int pid );
339
340/***************************************************************************************
341 * This debug syscall displays on the kernel terminal the set of registered windows
342 * in the FBF device. It can be called by any thread running in any cluster.
343 ***************************************************************************************
344 * @ pid    : target process identifier / all processes when pid == 0
345 * return 0 if success / return -1 if undefined pid.
346 **************************************************************************************/
347int display_fbf_windows( unsigned int pid );
348
349/***************************************************************************************
350* This debug syscall is used to activate / desactivate the context switches trace
351* for a core identified by the <cxy> and <lid> arguments.
352* It can be called by any thread running in any cluster.
353****************************************************************************************
354* @ active     : activate trace if non zero / desactivate if zero.
355* @ cxy        : cluster identifier.
356* @ lid        : core local index.
357* @ returns O if success / returns -1 if illegal arguments.
358***************************************************************************************/
359int trace( unsigned int active,
360           unsigned int cxy, 
361           unsigned int lid );
362
363/***************************************************************************************
364 * This syscall implements an user-level interactive debugger that can be
365 * introduced in any user application to display various kernel distributed structures.
366 **************************************************************************************/
367void idbg( void );
368
369
370/****************** Non standard (ALMOS-MKH specific) malloc operations  **************/
371
372////////////////////////////////////////////////////////////////////////////////////////
373// General principles:
374// - In user space the HEAP zone spread between the ELF zone and the STACK zone,
375//   as defined in the kernel_config.h file.
376// - The malloc library uses the mmap() syscall to create - on demand -
377//   one vseg in a given cluster. The size of this vseg is defined below
378//   by the MALLOC_LOCAL_STORE_SIZE parameter.
379// - For a standard malloc(), the target cluster is the cluster containing
380//   the core running the client thread.
381// - For a remote_malloc(), the target cluster is explicitely defined
382//   by the argument.
383// - In each cluster, the available storage in virtual space is handled by a
384//   local allocator using the buddy algorithm.
385//
386// TODO : In this first implementation one single - fixed size - vseg
387//        is allocated on demand in each cluster.
388//        We should introduce the possibility to dynamically allocate
389//        several vsegs in each cluster (using several mmap) when required.
390////////////////////////////////////////////////////////////////////////////////////////
391// Free blocks organisation in each cluster :
392// - All free blocks have a size that is a power of 2, larger or equal
393//   to MALLOC_MIN_BLOCK_SIZE (typically 64 bytes).
394// - All free blocks are aligned.
395// - They are pre-classed in an array of linked lists, where all blocks in a
396//   given list have the same size.
397// - The NEXT pointer implementing those linked lists is written
398//   in the first bytes of the block itself, using the unsigned int type.
399// - The pointers on the first free block for each size are stored in an
400//   array of pointers free[32] in the storage(x,y) descriptor.
401////////////////////////////////////////////////////////////////////////////////////////
402// Allocation policy:
403// - The block size required by the user can be any value, but the allocated
404//   block size can be larger than the requested size:
405// - The allocator computes actual_size, that is the smallest power of 2
406//   value larger or equal to the requested size AND larger or equal to
407//   MALLOC_MIN_BLOCK_SIZE.
408// - It pop the linked list of free blocks corresponding to actual_size,
409//   and returns the block B if the list[actual_size] is not empty.
410// - If the list[actual_size] is empty, it pop the list[actual_size * 2].
411//   If a block B' is found, it breaks this block in 2 B/2 blocks, returns
412//   the first B/2 block and push the other B/2 block into list[actual_size].
413// - If the list[actual_size * 2] is empty, it pop the list[actual_size * 4].
414//   If a block B is found, it break this block in 3 blocks B/4, B/4 and B/2,
415//   returns the first B/4 block, push the other blocks B/4 and B/2 into
416//   the proper lists. etc...
417// - If no block satisfying the request is available it returns a failure
418//   (NULL pointer).
419// - This allocation policy has the nice following property:
420//   If the vseg is aligned (the vseg base is a multiple of the
421//   vseg size), all allocated blocks are aligned on the actual_size.
422////////////////////////////////////////////////////////////////////////////////////////
423// Free policy:
424// - Each allocated block is registered in an alloc[] array of unsigned char.
425// - This registration is required by the free() operation, because the size
426//   of the allocated block must be obtained from the base address of the block. 
427// - The number of entries in this array is equal to the max number
428//   of allocated block : MALLOC_LOCAL_STORE_SIZE / MALLOC_MIN_BLOCK_SIZE.
429// - For each allocated block, the value registered in the alloc[] array
430//   is log2( size_of_allocated_block ).
431// - The index in this array is computed from the allocated block base address:
432//      index = (block_base - vseg_base) / MALLOC_MIN_BLOCK_SIZE
433// - The alloc[] array is stored at the end of heap segment. This consume
434//   (1 / MALLOC_MIN_BLOCK_SIZE) of the total storage capacity.
435/////////////////////////////////////////////////////////////////////////////////////////
436
437
438#define MALLOC_INITIALIZED         0xBABEF00D   // magic number when initialised
439#define MALLOC_MIN_BLOCK_SIZE      0x40         // 64 bytes
440#define MALLOC_LOCAL_STORE_SIZE    0x2000000    // 32 Mbytes     
441#define MALLOC_MAX_CLUSTERS        0x100        // 256 clusters
442
443/////////////////////////////////////////////////////////////////////////////////////////
444//               store(x,y) descriptor (one per cluster)
445/////////////////////////////////////////////////////////////////////////////////////////
446
447typedef struct malloc_store_s
448{
449    pthread_mutex_t mutex;           // lock protecting exclusive access to local heap
450    unsigned int    initialized;     // initialised when value == MALLOC_INITIALIZED
451    unsigned int    cxy;             // cluster identifier 
452    unsigned int    store_base;      // store base address
453    unsigned int    store_size;      // store size (bytes)
454    unsigned int    alloc_base;      // alloc[] array base address
455    unsigned int    alloc_size;      // alloc[] array size (bytes)
456    unsigned int    free[32];        // array of addresses of first free block
457} 
458malloc_store_t;
459
460/*****************************************************************************************
461 * This function allocates <size> bytes of memory in user space, and returns a pointer
462 * to the allocated buffer. The pysical memory is allocated from store located in
463 * cluster identified by the <cxy> argument.
464 *****************************************************************************************
465 * @ size    : number of requested bytes.
466 * @ cxy     : target cluster identifier.
467 * @ returns a pointer on the allocated buffer if success / returns NULL if failure
468 ****************************************************************************************/
469void * remote_malloc( unsigned int size, 
470                      unsigned int cxy );
471
472/*****************************************************************************************
473 * This function releases the memory buffer identified by the <ptr> argument,
474 * to the store identified by the <cxy> argument.
475 * It  does nothing, but displays an error message, if the ptr is illegal.
476 *****************************************************************************************
477 * @ ptr   : pointer on the released buffer.
478 * @ cxy   : target cluster identifier.
479 ****************************************************************************************/
480void remote_free( void        * ptr,
481                  unsigned int  cxy );
482
483/*****************************************************************************************
484 * This function releases the memory buffer identified by the <ptr> argument,
485 * to the store located in cluster identified by the <cxy> argument, and allocates
486 * a new buffer containing <size> bytes from this store.
487 * The content of the old buffer is copied to the new buffer, up to <size> bytes.
488 * It displays an error message, but does nothing if the ptr is illegal.
489 *****************************************************************************************
490 * @ ptr     : pointer on the released buffer.
491 * @ size    : new buffer requested size (bytes).
492 * @ cxy     : target cluster identifier.
493 * @ return a pointer on allocated buffer if success / return NULL if failure
494 ****************************************************************************************/
495void * remote_realloc( void        * ptr,
496                       unsigned int  size,
497                       unsigned int  cxy );
498
499/*****************************************************************************************
500 * This function allocates enough space for <count> objects that are <size> bytes
501 * of memory each from the store located in cluster identied by the <cxy> argument.
502 * The allocated memory is filled with bytes of value zero.
503 *****************************************************************************************
504 * @ count   : number of requested objects.
505 * @ size    : number of bytes per object.
506 * @ cxy     : target cluster identifier.
507 * @ returns a pointer on allocated buffer if success / returns NULL if failure
508 ****************************************************************************************/
509void * remote_calloc( unsigned int count,
510                      unsigned int size,
511                      unsigned int cxy );
512
513/********* Non standard (ALMOS-MKH specific) pthread_parallel_create() syscall  *********/
514
515//////////////////////////////////////////////////////////////////////////////////////////
516// This syscall can be used to parallelize the creation, and the termination
517// of a parallel multi-threaded application.
518// It removes in the main thread the sequencial loop that creates the N working threads
519// (N pthread_create() ), and removes also the sequencial loop that waits completion
520// of these N working threads (N pthread_join() ).
521// It creates one <work> thread (in detached mode) per core in the target architecture.
522// Each <work> thread is identified by a continuous [tid] index.
523// For a regular architecture, defined by the [x_size , y_size , ncores] parameters,
524// the number of working threads can be the simply computed as (x_size * y_size * ncores),
525// and the coordinates[x,y,lid] of the core running the thread[tid] cand be directly
526// derived from the [tid] value with the following relations:
527//     . cid = (x * y_size) + y
528//     . tid = (cid * ncores ) + lid
529//     . lid = tid % ncores
530//     . cid = tid / ncores
531//     . y   = cid % y_size
532//     . x   = cid / y_size
533// The pthread_parallel_create() function returns only when all <work> threads completed
534// (successfully or not).
535//
536// WARNING : The function executed by the working thread is application specific,
537// but the structure defining the arguments passed to this function is imposed.
538// The "pthread_parallel_work_args_t" structure is defined below, and contains
539// two fields: the tid value, and a pointer on a pthread_barrier_t.
540// This barrier must be used by each working thread to signal completion before exit.
541// The global variables implementing these stuctures for each working thread
542// are allocated and initialised by the pthread_parallel_create() function.
543//
544// Implementation note: the pthread_parallel_create()a function creates a distributed
545// quad-tree (DQT) of <build> threads covering all cores required to execute the parallel
546// application. This quad tree is entirely defined by the root_level parameter.
547// Depending on the hardware topology, this DQT can be truncated, (i.e. some
548// parent nodes can have less than 4 chidren), if (x_size != y_size), or if one size
549// is not a power of 2. Each <build> thread is identified by two indexes [cid][level].
550// Each <build> thread makes the following tasks:
551// 1) It calls the pthread_create() function to create up to 4 children threads, that
552//    are <work> threads when (level == 0), or <build> threads, when (level > 0).
553// 2) It allocates and initializes the barrier, used to block the parent thread until
554//    children completion.
555// 3) It calls the pthread_barrier_wait( self ) to wait until all children threads
556//    completed (successfully or not).
557// 4) It calls the pthread_barrier_wait( parent ) to unblock the parent thread.
558//////////////////////////////////////////////////////////////////////////////////////////
559
560/*****************************************************************************************
561 *    structure defining the arguments for the <build> thread function
562 ****************************************************************************************/
563typedef struct pthread_parallel_build_args_s           
564{
565    unsigned char        cid;                    // this <build> thread cluster index
566    unsigned char        level;                  // this <build> thread level in quad-tree
567    unsigned char        parent_cid;             // parent <build> thread cluster index
568    pthread_barrier_t  * parent_barrier;         // pointer on parent <build> thread barrier
569    unsigned char        root_level;             // quad-tree root level
570    void               * work_func;              // pointer on working thread function
571    unsigned int         x_size;                 // platform global parameter
572    unsigned int         y_size;                 // platform global parameter
573    unsigned int         ncores;                 // platform global parameter
574    unsigned int         error;                  // return value : 0 if success
575}
576pthread_parallel_build_args_t;
577
578/*****************************************************************************************
579 *    structure defining the arguments for the <work> thread function
580 ****************************************************************************************/
581typedef struct pthread_parallel_work_args_s           
582{
583    unsigned int         tid;                    // thread identifier
584    pthread_barrier_t  * barrier;                // to signal completion
585}
586pthread_parallel_work_args_t;           
587
588/*****************************************************************************************
589 * This blocking function creates N working threads identified by the [tid] continuous
590 * index, that execute the code defined by the <work_func> argument, and returns only
591 * when all working threads completed.
592 * The number N of created threads is entirely defined by the <root_level> argument,
593 * that defines an abstract quad-tree, with a square base : root_level in [0,1,2,3,4],
594 * side in [1,2,4,8,16], nclusters in [1,4,16,64,256]. This base is called  macro_cluster.
595 * A working thread is created on all cores contained in this abstract macro-cluster.
596 * The actual number of physical clusters containing cores can be smaller than the number
597 * of clusters covered by the abstract quad tree.
598 * All threads execute the same <work_func> function, on different arguments, that are
599 * specified as an array of structures pthread_parallel_work_args_t, allocated and
600 * initialised by this function.
601 *****************************************************************************************
602 * @ root_level            : [in]  DQT root level in [0,1,2,3,4].
603 * @ work_func             : [in]  pointer on start function.
604 * @ return 0 if success / return -1 if failure.
605 ****************************************************************************************/
606int pthread_parallel_create( unsigned int         root_level,
607                             void               * work_func );
608
609
610
611/********* Non standard (ALMOS-MKH specific) Frame Buffer access syscalls   *************/
612
613//////////////////////////////////////////////////////////////////////////////////////////
614// The following system calls can be used to access the SoCLib Frame Buffer, that
615// is a very simple graphic controller, that is seen by the software as a single
616// buffer of <height> lines of <width> pixels.
617//////////////////////////////////////////////////////////////////////////////////////////
618
619/*****************************************************************************************
620 * This syscall returns in the <width>, <height> and <type> arguments
621 * the implementation specific frame buffer features.
622 *****************************************************************************************
623 * @ width   : [out] number of pixels per line.
624 * @ height  : [out] number of lines.
625 * @ type    : [out] pixel encoding type.
626 * @ returns 0 if success / returns -1 if not found.
627 ****************************************************************************************/
628int fbf_get_config( int * width,
629                    int * height,
630                    int * type );
631
632/*****************************************************************************************
633 * This syscall creates a new window defined by the <l_zero>, <p_zero>, <nlines>,
634 * and <npixels> arguments for the calling process, and register the client process PID,
635 * the allocated <wid>, and the window size and coordinates in the list of windows rooted
636 * in the FBF device descriptor. It returns in the output argument <buffer> the pointer
637 * on the buffer associated to the window, mapped in user space.
638 * Warning : Both pixel [p_zero,l_zero] and pixel [p_zero+npixels-1,l_zero+nlines-1]
639 * must be contained in the frame buffer.
640 *****************************************************************************************
641 * @ l_zero  : [in]  first line index in FBF coordinates system.
642 * @ p_zero  : [in]  first pixel index in FBF coordinates system.
643 * @ nlines  : [in]  number of lines in the window.
644 * @ npixels : [in]  number of pixels per line in the window.
645 * @ buffer  : [out] pointer on buffer associated to window, mapped in user space.
646 * @ returns <kern_wid> if success / returns -1 if illegal size or coordinates.
647 ****************************************************************************************/
648int fbf_create_window( int     l_zero,
649                       int     p_zero,
650                       int     nlines,
651                       int     npixels,
652                       void ** buffer );
653
654/*****************************************************************************************
655 * This syscall activates/desactivates the window identified by the <wid> argument,
656 * according to the <active> argument.  The calling process must be the window owner.
657 *****************************************************************************************
658 * @ wid        : window identifier.
659 * @ active     : activate window if non zero / desactivate window if zero.
660 * @ returns 0 if success / returns -1 if illegal wid argument.
661 ****************************************************************************************/
662int fbf_active_window( int   wid,
663                       int   active );
664
665/*****************************************************************************************
666 * This syscall deletes an existing window, identified by the <wid> argument.
667 * The calling process must be the window owner.
668 *****************************************************************************************
669 * @ wid     : window identifier.
670 * @ returns 0 if success / returns -1 if illegal wid argument.
671 ****************************************************************************************/
672int fbf_delete_window( int  wid );
673
674/*****************************************************************************************
675 * This syscall refreshes in FBF all lines of a window identified by the <wid> argument,
676 * when the line index is in the interval [line_first,line_last[.
677 * It scans all registered windows to take into account the windows overlap.
678 * The calling process must be the window owner, and the line_fist / line_last indexes
679 * must be compatible with the window height.
680 *****************************************************************************************
681 * @ wid        : window identifier.
682 * @ line_first : first line index in window.
683 * @ line_last  : last line index in window (excluded).
684 * @ returns 0 if success / returns -1 if illegal arguments.
685 ****************************************************************************************/
686int fbf_refresh_window( int   wid,
687                        int   line_first,
688                        int   line_last );
689
690/*****************************************************************************************
691 * This syscall gives the highest priority to the window identified by the <wid>
692 * argument, and refresh the FBF to take into account the new windows overlap priorities.
693 * The calling process must be the window owner.
694 *****************************************************************************************
695 * @ wid        : window identifier.
696 * @ returns 0 if success / returns -1 if wid illegal argument.
697 ****************************************************************************************/
698int fbf_front_window( int   wid );
699
700/*****************************************************************************************
701 * This syscall changes the size of a window identified by the <wid> argument as defined
702 * by the <width> and height> arguments. The calling process must be the window owner.
703 * Both pixel [p_zero,l_zero] and pixel [p_zero+width-1,l_zero+height-1] must be
704 * contained in the frame buffer.
705 *****************************************************************************************
706 * @ wid     : window identifier.
707 * @ width   : number of pixels in line (one byte per pixel).
708 * @ height  : number of lines in window.
709 * @ returns 0 if success / returns -1 if illegal arguments.
710 ****************************************************************************************/
711int fbf_resize_window( int   wid,
712                       int   width,
713                       int   height );
714
715/*****************************************************************************************
716 * This syscall changes the <l_zero> & <p_zero> coordinates of a window identified
717 * by the <wid> argument. The calling process must be the window owner.
718 * Both pixel [p_zero,l_zero] and pixel [p_zero+width-1,l_zero+height-1]
719 * must be contained in the frame buffer.
720 *****************************************************************************************
721 * @ wid     : window identifier.
722 * @ l_zero  : new first line index in FBF.
723 * @ p_zero  : new first pixel index in FBF.
724 * @ returns 0 if success / returns -1 if illegal arguments.
725 ****************************************************************************************/
726int fbf_move_window( int  wid,
727                     int  l_zero,
728                     int  p_zero );
729
730
731
732
733/*****************************************************************************************
734 * This syscall is deprecated (january 2020 AG)
735 * This blocking function moves <length> pixels from the user buffer defined by <buffer>
736 * argument to the frame buffer, starting at <offset> in FBF.
737 *****************************************************************************************
738 * @ buffer  : pointer on buffer in user space.
739 * @ length  : number of pixels (one byte per pixel).
740 * @ offset  : first pixel index in window.
741 * @ returns 0 if success / returns -1 if illegal arguments.
742 ****************************************************************************************/
743int fbf_write( void * buffer,
744               int    length,
745               int    offset );
746
747/*****************************************************************************************
748 * This syscall is deprecated (january 2020 AG)
749 * This blocking function moves <length> pixels from the frame buffer, starting at
750 * <offset> in FBF, to the user buffer defined by <buffer>  argument.
751 *****************************************************************************************
752 * @ buffer  : pointer on buffer in user space.
753 * @ length  : number of pixels (one byte per pixel).
754 * @ offset  : first pixel index in window.
755 * @ returns 0 if success / returns -1 if illegal arguments.
756 ****************************************************************************************/
757int fbf_read( void * buffer,
758              int    length,
759              int    offset );
760
761
762#endif /* _LIBALMOSMKH_H_ */
763
Note: See TracBrowser for help on using the repository browser.