Index: trunk/libs/libalmosmkh/almosmkh.h
===================================================================
--- trunk/libs/libalmos-mkh/almos-mkh.h	(revision 444)
+++ trunk/libs/libalmosmkh/almosmkh.h	(revision 445)
@@ -1,18 +1,48 @@
+/*
+ * almosmkh.h - User level ALMOS-MKH specific library definition.
+ * 
+ * Author     Alain Greiner (2016,2017,2018)
+ *
+ * Copyright (c) UPMC Sorbonne Universites
+ *
+ * This file is part of ALMOS-MKH.
+ *
+ * ALMOS-MKH is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; version 2.0 of the License.
+ *
+ * ALMOS-MKH is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with ALMOS-MKH; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
+ */
+
 #ifndef _LIBALMOSMKH_H_
 #define _LIBALMOSMKH_H_
 
-#include <almos-mkh/almos-mkh.h>
+/*************************************************************************************** 
+ * various the user level, ALMOS-MKH specific library. It contains:
+ * - non standard system calls.
+ * - debug functions.
+ * - remote malloc extensions. 
+ **************************************************************************************/
+
 #include <pthread.h>
-
-/****************** Non standard (ALMOS_MKH specific) system calls **********************/
-
-
-/***************************************************************************************** 
+#include <shared_almos.h>
+
+/****************** Non standard (ALMOS_MKH specific) system calls ********************/
+
+
+/*************************************************************************************** 
  * This function is used to give the process identified by the <pid> argument the 
  * exclusive ownership of the attached TXT_RX terminal.
- ***************************************************************************************** 
+ *************************************************************************************** 
  * @ pid        : process identifier.
  * @ returns O if success / returns -1 if process not found.
- ****************************************************************************************/
+ **************************************************************************************/
 int fg( unsigned int pid );
 
@@ -49,4 +79,25 @@
 
 /*************************************************************************************** 
+ * This function implement the operations related to User Thread Local Storage.
+ ***************************************************************************************
+ * @ operation  : UTLS operation type as defined in "shared_sycalls.h" file.
+ * @ value      : argument value for the UTLS_SET operation.
+ * @ return value for the UTLS_GET and UTLS_GET_ERRNO / return -1 if failure.
+ **************************************************************************************/
+int utls( unsigned int operation,
+          unsigned int value );
+
+/***************************************************************************************
+ * This function returns a positive integer fom the standard "stdin" stream.
+ ***************************************************************************************
+ * returns the integer value if success / returns -1 if failure.
+ **************************************************************************************/
+int getint();
+
+
+/***************** Non standard (ALMOS-MKH specific) debug functions ******************/
+
+
+/*************************************************************************************** 
  * This debug function displays on the kernel terminal TXT0
  * the thread / process / core identifiers, the current cycle, plus a user defined
@@ -91,4 +142,14 @@
 /*************************************************************************************** 
  * This debug function displays on the kernel terminal TXT0 
+ * the list of processes attached to a given TXT channel.
+ * It can be called by any thread running in any cluster.
+ ***************************************************************************************
+ * @ txt_id   : [in] TXT terminal indes.
+ * @ return 0 if success / return -1 if illegal argument.
+ **************************************************************************************/
+int display_txt_processes( unsigned int txt_id );
+
+/*************************************************************************************** 
+ * This debug function displays on the kernel terminal TXT0 
  * the list of channel devices available in the architecture.
  * It can be called by any thread running in any cluster.
@@ -108,11 +169,10 @@
 
 /*************************************************************************************** 
- * This debug function displays on the kernel terminal TXT0 
- * the list of processes attached to a given TXT channel.
- * It can be called by any thread running in any cluster.
- ***************************************************************************************
- * @ return always 0.
- **************************************************************************************/
-int display_txt_processes( unsigned int txt_id );
+ * This debug function displays on the kernel terminal TXT0 the current DQDT state.
+ * It can be called by any thread running in any cluster.
+ ***************************************************************************************
+ * @ return always 0.
+ **************************************************************************************/
+int display_dqdt();
 
 /***************************************************************************************** 
@@ -126,29 +186,26 @@
 * @ returns O if success / returns -1 if illegal arguments.
 ****************************************************************************************/
-
 int trace( unsigned int active,
            unsigned int pid, 
            unsigned int trdid );
 
-/***************************************************************************************** 
- * This function implement the operations related to User Thread Local Storage.
- *****************************************************************************************
- * @ operation  : UTLS operation type as defined in "shared_sycalls.h" file.
- * @ value      : argument value for the UTLS_SET operation.
- * @ return value for the UTLS_GET and UTLS_GET_ERRNO / return -1 if failure.
- ****************************************************************************************/
-int utls( unsigned int operation,
-          unsigned int value );
-
-/*********************************************************************************************
- * This function returns a positive integer fom the standard "stdin" stream.
- *********************************************************************************************
- * returns the integer value if success / returns -1 if failure.
- ********************************************************************************************/
-int getint();
-
-
-/////// Non-standard memory operations ////////////
-////////////////////////////////////////////////////////////////////////////////
+/****************************************************************************************
+ * This blocking function implements an user-level interactive debugger that can be
+ * introduced in any user application to display various kernel distributed structures.
+ * The supported commands are:
+ * - p (cxy)     : display all processes descriptors in a given cluster.
+ * - s (cxy,lid) : display all threads attached to a given core in a given cluster.
+ * - v (cxy)     : display the calling process VMM in a given cluster.
+ * - t (tid)     : display all owner process descriptors attached to a TXT terminal.
+ * - x           : force the calling process to exit.
+ * - c           : continue calling process execution.
+ * - h           : list the supported commands
+ ***************************************************************************************/
+void idbg();
+
+
+/****************** Non standard (ALMOS-MKH specific) malloc operations  ***************/
+
+/////////////////////////////////////////////////////////////////////////////////////////
 // General principles:
 // - In user space the HEAP zone spread between the ELF zone and the STACK zone,
@@ -168,5 +225,5 @@
 //        We should introduce the possibility to dynamically allocate
 //        several vsegs in each cluster, using several mmap when required. 
-////////////////////////////////////////////////////////////////////////////////
+/////////////////////////////////////////////////////////////////////////////////////////
 // Free blocks organisation in each cluster :
 // - All free blocks have a size that is a power of 2, larger or equal
@@ -179,5 +236,5 @@
 // - The pointers on the first free block for each size are stored in an
 //   array of pointers free[32] in the storage(x,y) descriptor.
-////////////////////////////////////////////////////////////////////////////////
+/////////////////////////////////////////////////////////////////////////////////////////
 // Allocation policy:
 // - The block size required by the user can be any value, but the allocated
@@ -200,5 +257,5 @@
 //   If the vseg is aligned (the vseg base is a multiple of the
 //   vseg size), all allocated blocks are aligned on the actual_size.
-////////////////////////////////////////////////////////////////////////////////
+/////////////////////////////////////////////////////////////////////////////////////////
 // Free policy:
 // - Each allocated block is registered in an alloc[] array of unsigned char.
@@ -213,5 +270,5 @@
 // - The alloc[] array is stored at the end of heap segment. This consume
 //   (1 / MALLOC_MIN_BLOCK_SIZE) of the total storage capacity.
-////////////////////////////////////////////////////////////////////////////////
+/////////////////////////////////////////////////////////////////////////////////////////
 
 
@@ -221,11 +278,11 @@
 #define MALLOC_MAX_CLUSTERS        0x100        // 256 clusters
 
-////////////////////////////////////////////////////////////////////////////////
-// store(x,y) descriptor (one per cluster)
-////////////////////////////////////////////////////////////////////////////////
+/////////////////////////////////////////////////////////////////////////////////////////
+//               store(x,y) descriptor (one per cluster)
+/////////////////////////////////////////////////////////////////////////////////////////
 
 typedef struct malloc_store_s
 {
-    pthread_mutex_t mutex;           // lock protecting exclusive access
+    pthread_mutex_t mutex;           // lock protecting exclusive access to local heap
     unsigned int    initialized;     // initialised when value == MALLOC_INITIALIZED
     unsigned int    cxy;             // cluster identifier  
@@ -276,4 +333,5 @@
                        unsigned int  size,
                        unsigned int  cxy );
+
 /*****************************************************************************************
  * This function allocates enough space for <count> objects that are <size> bytes
@@ -290,19 +348,4 @@
                       unsigned int cxy );
 
-/*********************************************************************************************
- * This blocking function implements an user-level interactive debugger that can be
- * introduced in any user application to display various kernel distributed structures
- * related to the calling process. The supported commands are:
- * - p (cxy)     : display all processes descriptors in a given cluster.
- * - s (cxy,lid) : display all threads attached to a given core in a given cluster.
- * - v (cxy)     : display the calling process VMM in a given cluster.
- * - t (tid)     : display all owner process descriptors attached to a given TXT terminal.
- * - x           : force the calling process to exit.
- * - c           : continue calling process execution.
- *********************************************************************************************
- * @ return an integer value between 0 and RAND_MAX.
- ********************************************************************************************/
-void idbg();
-
 #endif /* _LIBALMOSMKH_H_ */
 
