source: trunk/libs/libalmos-mkh/almos-mkh.h @ 444

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

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

File size: 17.2 KB
Line 
1#ifndef _LIBALMOSMKH_H_
2#define _LIBALMOSMKH_H_
3
4#include <almos-mkh/almos-mkh.h>
5#include <pthread.h>
6
7/****************** Non standard (ALMOS_MKH specific) system calls **********************/
8
9
10/*****************************************************************************************
11 * This function is used to give the process identified by the <pid> argument the
12 * exclusive ownership of the attached TXT_RX terminal.
13 *****************************************************************************************
14 * @ pid        : process identifier.
15 * @ returns O if success / returns -1 if process not found.
16 ****************************************************************************************/
17int fg( unsigned int pid );
18
19/***************************************************************************************
20 * This function returns the hardware platform parameters.
21 ***************************************************************************************
22 * @ x_size   : [out] number of clusters in a row.
23 * @ y_size   : [out] number of clusters in a column.
24 * @ ncores   : [out] number of cores per cluster.
25 * @ return always 0.
26 **************************************************************************************/
27int get_config( unsigned int * x_size,
28                unsigned int * y_size,
29                unsigned int * ncores );
30
31/***************************************************************************************
32 * This function returns the cluster an local index for the calling core.
33 ***************************************************************************************
34 * @ cxy      : [out] cluster identifier.
35 * @ lid      : [out] core local index in cluster.
36 * @ return always 0.
37 **************************************************************************************/
38int get_core( unsigned int * cxy,
39              unsigned int * lid );
40
41/***************************************************************************************
42 * This function returns the calling core cycles counter,
43 * taking into account a possible overflow on 32 bits architectures.
44 ***************************************************************************************
45 * @ cycle    : [out] current cycle value.
46 * @ return always 0.
47 **************************************************************************************/
48int get_cycle( unsigned long long * cycle );
49
50/***************************************************************************************
51 * This debug function displays on the kernel terminal TXT0
52 * the thread / process / core identifiers, the current cycle, plus a user defined
53 * message as specified by the <string> argument.
54 ***************************************************************************************
55 * @ string    : [in] user defined message.
56 **************************************************************************************/
57void display_string( char * string );
58
59/***************************************************************************************
60 * This debug function displays on the kernel terminal TXT0
61 * the state of the  VMM for the process <pid>, in cluster <cxy>.
62 * It can be called by any thread running in any cluster.
63 ***************************************************************************************
64 * @ pid      : [in] process identifier.
65 * @ return 0 if success / return -1 if illegal argument.
66 **************************************************************************************/
67int display_vmm(unsigned int cxy, unsigned int  pid );
68
69/***************************************************************************************
70 * This debug function displays on the kernel terminal TXT0
71 * the state of the core scheduler identified by the <cxy> and <lid> arguments.
72 * It can be called by any thread running in any cluster.
73 ***************************************************************************************
74 * @ cxy      : [in] target cluster identifier.
75 * @ lid      : [in] target core local index.
76 * @ return 0 if success / return -1 if illegal arguments.
77 **************************************************************************************/
78int display_sched( unsigned int  cxy,
79                   unsigned int  lid );
80
81/***************************************************************************************
82 * This debug function displays on the kernel terminal TXT0
83 * the list of process registered in a given cluster identified by the <cxy> argument.
84 * It can be called by any thread running in any cluster.
85 ***************************************************************************************
86 * @ cxy      : [in] target cluster identifier.
87 * @ return 0 if success / return -1 if illegal argument.
88 **************************************************************************************/
89int display_cluster_processes( unsigned int  cxy );
90
91/***************************************************************************************
92 * This debug function displays on the kernel terminal TXT0
93 * the list of channel devices available in the architecture.
94 * It can be called by any thread running in any cluster.
95 ***************************************************************************************
96 * @ return always 0.
97 **************************************************************************************/
98int display_chdev();
99
100/***************************************************************************************
101 * This debug function displays on the kernel terminal TXT0
102 * the list of channel device or pseudo-files registered in the VFS cache.
103 * It can be called by any thread running in any cluster.
104 ***************************************************************************************
105 * @ return always 0.
106 **************************************************************************************/
107int display_vfs();
108
109/***************************************************************************************
110 * This debug function displays on the kernel terminal TXT0
111 * the list of processes attached to a given TXT channel.
112 * It can be called by any thread running in any cluster.
113 ***************************************************************************************
114 * @ return always 0.
115 **************************************************************************************/
116int display_txt_processes( unsigned int txt_id );
117
118/*****************************************************************************************
119* This debug function is used to activate / desactivate the context switches trace
120* for a core identified by the <cxy> and <lid> arguments.
121* It can be called by any thread running in any cluster.
122*****************************************************************************************
123* @ active     : activate trace if non zero / desactivate if zero.
124* @ cxy        : cluster identifier.
125* @ lid        : core local index.
126* @ returns O if success / returns -1 if illegal arguments.
127****************************************************************************************/
128
129int trace( unsigned int active,
130           unsigned int pid, 
131           unsigned int trdid );
132
133/*****************************************************************************************
134 * This function implement the operations related to User Thread Local Storage.
135 *****************************************************************************************
136 * @ operation  : UTLS operation type as defined in "shared_sycalls.h" file.
137 * @ value      : argument value for the UTLS_SET operation.
138 * @ return value for the UTLS_GET and UTLS_GET_ERRNO / return -1 if failure.
139 ****************************************************************************************/
140int utls( unsigned int operation,
141          unsigned int value );
142
143/*********************************************************************************************
144 * This function returns a positive integer fom the standard "stdin" stream.
145 *********************************************************************************************
146 * returns the integer value if success / returns -1 if failure.
147 ********************************************************************************************/
148int getint();
149
150
151/////// Non-standard memory operations ////////////
152////////////////////////////////////////////////////////////////////////////////
153// General principles:
154// - In user space the HEAP zone spread between the ELF zone and the STACK zone,
155//   as defined in the kernel_config.h file.
156// - The malloc library uses the mmap() syscall to create - on demand -
157//   one vseg in a given cluster. The size of this vseg is defined below
158//   by the MALLOC_LOCAL_STORE_SIZE parameter.
159// - For a standard malloc(), the target cluster is the cluster containing
160//   the core running the client thread.
161// - For a remote_malloc(), the target cluster is explicitely defined
162//   by the argument.
163// - In each cluster, the available storage in virtual space is handled by a
164//   local allocator using the buddy algorithm.
165//
166// TODO : In this first implementation one single - fixed size - vseg
167//        is allocated on demand in each cluster.
168//        We should introduce the possibility to dynamically allocate
169//        several vsegs in each cluster, using several mmap when required.
170////////////////////////////////////////////////////////////////////////////////
171// Free blocks organisation in each cluster :
172// - All free blocks have a size that is a power of 2, larger or equal
173//   to MALLOC_MIN_BLOCK_SIZE (typically 64 bytes).
174// - All free blocks are aligned.
175// - They are pre-classed in an array of linked lists, where all blocks in a
176//   given list have the same size.
177// - The NEXT pointer implementing those linked lists is written
178//   in the first bytes of the block itself, using the unsigned int type.
179// - The pointers on the first free block for each size are stored in an
180//   array of pointers free[32] in the storage(x,y) descriptor.
181////////////////////////////////////////////////////////////////////////////////
182// Allocation policy:
183// - The block size required by the user can be any value, but the allocated
184//   block size can be larger than the requested size:
185// - The allocator computes actual_size, that is the smallest power of 2
186//   value larger or equal to the requested size AND larger or equal to
187//   MALLOC_MIN_BLOCK_SIZE.
188// - It pop the linked list of free blocks corresponding to actual_size,
189//   and returns the block B if the list[actual_size] is not empty.
190// - If the list[actual_size] is empty, it pop the list[actual_size * 2].
191//   If a block B' is found, it breaks this block in 2 B/2 blocks, returns
192//   the first B/2 block and push the other B/2 block into list[actual_size].
193// - If the list[actual_size * 2] is empty, it pop the list[actual_size * 4].
194//   If a block B is found, it break this block in 3 blocks B/4, B/4 and B/2,
195//   returns the first B/4 block, push the other blocks B/4 and B/2 into
196//   the proper lists. etc...
197// - If no block satisfying the request is available it returns a failure
198//   (NULL pointer).
199// - This allocation policy has the nice following property:
200//   If the vseg is aligned (the vseg base is a multiple of the
201//   vseg size), all allocated blocks are aligned on the actual_size.
202////////////////////////////////////////////////////////////////////////////////
203// Free policy:
204// - Each allocated block is registered in an alloc[] array of unsigned char.
205// - This registration is required by the free() operation, because the size
206//   of the allocated block must be obtained from the base address of the block. 
207// - The number of entries in this array is equal to the max number
208//   of allocated block : MALLOC_LOCAL_STORE_SIZE / MALLOC_MIN_BLOCK_SIZE.
209// - For each allocated block, the value registered in the alloc[] array
210//   is log2( size_of_allocated_block ).
211// - The index in this array is computed from the allocated block base address:
212//      index = (block_base - vseg_base) / MALLOC_MIN_BLOCK_SIZE
213// - The alloc[] array is stored at the end of heap segment. This consume
214//   (1 / MALLOC_MIN_BLOCK_SIZE) of the total storage capacity.
215////////////////////////////////////////////////////////////////////////////////
216
217
218#define MALLOC_INITIALIZED         0xBABEF00D   // magic number when initialised
219#define MALLOC_MIN_BLOCK_SIZE      0x40         // 64 bytes
220#define MALLOC_LOCAL_STORE_SIZE    0x800000     // 8 Mbytes     
221#define MALLOC_MAX_CLUSTERS        0x100        // 256 clusters
222
223////////////////////////////////////////////////////////////////////////////////
224// store(x,y) descriptor (one per cluster)
225////////////////////////////////////////////////////////////////////////////////
226
227typedef struct malloc_store_s
228{
229    pthread_mutex_t mutex;           // lock protecting exclusive access
230    unsigned int    initialized;     // initialised when value == MALLOC_INITIALIZED
231    unsigned int    cxy;             // cluster identifier 
232    unsigned int    store_base;      // store base address
233    unsigned int    store_size;      // store size (bytes)
234    unsigned int    alloc_base;      // alloc[] array base address
235    unsigned int    alloc_size;      // alloc[] array size (bytes)
236    unsigned int    free[32];        // array of addresses of first free block
237} 
238malloc_store_t;
239
240/*****************************************************************************************
241 * This function allocates <size> bytes of memory in user space, and returns a pointer
242 * to the allocated buffer. The pysical memory is allocated from store located in
243 * cluster identified by the <cxy> argument.
244 *****************************************************************************************
245 * @ size    : number of requested bytes.
246 * @ cxy     : target cluster identifier.
247 * @ returns a pointer on the allocated buffer if success / returns NULL if failure
248 ****************************************************************************************/
249void * remote_malloc( unsigned int size, 
250                      unsigned int cxy );
251
252/*****************************************************************************************
253 * This function releases the memory buffer identified by the <ptr> argument,
254 * to the store identified by the <cxy> argument.
255 * It displays an error message, but does nothing if the ptr is illegal.
256 *****************************************************************************************
257 * @ ptr   : pointer on the released buffer.
258 * @ cxy   : target cluster identifier.
259 ****************************************************************************************/
260void remote_free( void        * ptr,
261                  unsigned int  cxy );
262
263/*****************************************************************************************
264 * This function releases the memory buffer identified by the <ptr> argument,
265 * to the store located in cluster identified by the <cxy> argument, and allocates
266 * a new buffer containing <size> bytes from this store.
267 * The content of the old buffer is copied to the new buffer, up to <size> bytes.
268 * It displays an error message, but does nothing if the ptr is illegal.
269 *****************************************************************************************
270 * @ ptr     : pointer on the released buffer.
271 * @ size    : new buffer requested size (bytes).
272 * @ cxy     : target cluster identifier.
273 * @ return a pointer on allocated buffer if success / return NULL if failure
274 ****************************************************************************************/
275void * remote_realloc( void        * ptr,
276                       unsigned int  size,
277                       unsigned int  cxy );
278/*****************************************************************************************
279 * This function allocates enough space for <count> objects that are <size> bytes
280 * of memory each from the store located in cluster identied by the <cxy> argument.
281 * The allocated memory is filled with bytes of value zero.
282 *****************************************************************************************
283 * @ count   : number of requested objects.
284 * @ size    : number of bytes per object.
285 * @ cxy     : target cluster identifier.
286 * @ returns a pointer on allocated buffer if success / returns NULL if failure
287 ****************************************************************************************/
288void * remote_calloc( unsigned int count,
289                      unsigned int size,
290                      unsigned int cxy );
291
292/*********************************************************************************************
293 * This blocking function implements an user-level interactive debugger that can be
294 * introduced in any user application to display various kernel distributed structures
295 * related to the calling process. The supported commands are:
296 * - p (cxy)     : display all processes descriptors in a given cluster.
297 * - s (cxy,lid) : display all threads attached to a given core in a given cluster.
298 * - v (cxy)     : display the calling process VMM in a given cluster.
299 * - t (tid)     : display all owner process descriptors attached to a given TXT terminal.
300 * - x           : force the calling process to exit.
301 * - c           : continue calling process execution.
302 *********************************************************************************************
303 * @ return an integer value between 0 and RAND_MAX.
304 ********************************************************************************************/
305void idbg();
306
307#endif /* _LIBALMOSMKH_H_ */
308
Note: See TracBrowser for help on using the repository browser.