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

Last change on this file since 446 was 445, checked in by alain, 6 years ago

Restructure the mini_libc.

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