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

Last change on this file since 657 was 657, checked in by alain, 22 months ago

Introduce remote_buf.c/.h & socket.c/.h files.
Update dev_nic.c/.h files.

File size: 39.2 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.
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 **************************************************************************************/
72int 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 **************************************************************************************/
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 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 **************************************************************************************/
150int 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 **************************************************************************************/
162int 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 *****************************************************************************************/
175int 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 **************************************************************************************/
184void 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 **************************************************************************************/
196int 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 **************************************************************************************/
209int 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 **************************************************************************************/
222int 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 **************************************************************************************/
233int 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 **************************************************************************************/
244int 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 **************************************************************************************/
254int 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 **************************************************************************************/
263int 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 **************************************************************************************/
271int 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 **************************************************************************************/
283int 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 **************************************************************************************/
295int 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 **************************************************************************************/
308int 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****************************************************************************************/
321int 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 ***************************************************************************************/
329void 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
409typedef 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} 
420malloc_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 ****************************************************************************************/
431void * 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 ****************************************************************************************/
442void 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 ****************************************************************************************/
457void * 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 ****************************************************************************************/
471void * 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 ****************************************************************************************/
525typedef 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}
538pthread_parallel_build_args_t;
539
540/*****************************************************************************************
541 *    structure defining the arguments for the <work> thread function
542 ****************************************************************************************/
543typedef struct pthread_parallel_work_args_s           
544{
545    unsigned int         tid;                    // thread identifier
546    pthread_barrier_t  * barrier;                // to signal completion
547}
548pthread_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 ****************************************************************************************/
568int 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 ****************************************************************************************/
590int 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 ****************************************************************************************/
610int 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 ****************************************************************************************/
623int 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 ****************************************************************************************/
635int 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 ****************************************************************************************/
650int 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 ****************************************************************************************/
665int 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 ****************************************************************************************/
679int 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 ****************************************************************************************/
693int fbf_read( void         * buffer,
694              unsigned int   length,
695              unsigned int   offset );
696
697
698#endif /* _LIBALMOSMKH_H_ */
699
Note: See TracBrowser for help on using the repository browser.