Index: trunk/kernel/kern/chdev.h
===================================================================
--- trunk/kernel/kern/chdev.h	(revision 625)
+++ trunk/kernel/kern/chdev.h	(revision 657)
@@ -1,6 +1,6 @@
 /*
- * chdev.h - channel device (chdev) descriptor definition.
+ * chdev.h - channel device (chdev) descriptor and API definition.
  * 
- * Authors  Alain Greiner    (2016)
+ * Authors  Alain Greiner    (2016,2017,2018,2019,2020)
  *
  * Copyright (c) UPMC Sorbonne Universites
@@ -36,5 +36,5 @@
 #include <dev_txt.h>
 
-/******************************************************************************************
+/****************************************************************************************
  *       Channel Device descriptor definition
  *
@@ -42,5 +42,5 @@
  * independant) Channel Device descriptor (in brief "chdev").
  * ALMOS-MKH supports multi-channels peripherals, and defines one separated chdev 
- * descriptor for each channel (and for each RX/TX direction for the NIC and TXT devices).
+ * descriptor for each channel (and for each RX/TX direction for NIC and TXT devices).
  * Each chdev contains a trans-clusters waiting queue, registering the "client threads",
  * and an associated "server thread", handling these requests.
@@ -50,5 +50,5 @@
  * - the server cluster, containing the chdev and the server thread,
  * - the I/O cluster, containing the physical device.
- *****************************************************************************************/
+ ***************************************************************************************/
 
 /****  Forward declarations  ****/
@@ -58,12 +58,12 @@
 struct  boot_info_s;
 
-/******************************************************************************************
- * These macros extract the functionality and the implementation from the peripheral type.
- *****************************************************************************************/
+/****************************************************************************************
+ * These macros extract functionality and  implementation from the peripheral type.
+ ***************************************************************************************/
  
 #define FUNC_FROM_TYPE( type )    ((uint32_t)(type>>16))
 #define IMPL_FROM_TYPE( type )    ((uint32_t)(type & 0x0000FFFF))
 
-/******************************************************************************************
+/****************************************************************************************
  * This define the generic prototypes for the three functions that must be defined
  * by the drivers implementing a generic device:
@@ -73,5 +73,5 @@
  * The "cmd", "isr", and "aux" driver functions are registered in the generic chdev
  * descriptor at kernel init, and are called to start and complete an I/O operation.  
-*****************************************************************************************/
+***************************************************************************************/
 
 typedef void (dev_ini_t) ( xptr_t dev );      
@@ -80,5 +80,5 @@
 typedef void (dev_aux_t) ( void * args );  
 
-/******************************************************************************************
+/****************************************************************************************
  * This enum defines the supported generic device types.
  * These types are functionnal types: all (architecture specific) implementations 
@@ -89,5 +89,5 @@
  *           distributed LAPIC controler, but it does not exist as a chdev in the kernel,
  *           as it is hidden in the driver associated to the PIC device.
- *****************************************************************************************/
+ ***************************************************************************************/
  
 enum dev_func_type 
@@ -116,8 +116,10 @@
  * For each device type ***, the specific extension is defined in the "dev_***.h" file.
  *
- * NOTE : For most chdevs, the busylock is used to protect the waiting queue changes,
+ * NOTE . For most chdevs, the busylock is used to protect the waiting queue changes,
  *        when a thread register in this queue, or is removed after service.
- *        This busylock is also used to protect direct access to the kernel TXT0 terminal
- *        (without using the server thread).
+ *      . This busylock is also used to protect direct access to the shared
+ *        kernel TXT0 terminal, that does not use the waiting queue.
+ *      . For the NIC chdevs it is also used to protect registration (or removal) of a
+ *        socket in the list of attached sockets rooted in NIC device extension.
  *****************************************************************************************/
 
@@ -125,5 +127,5 @@
 {
 	uint32_t             func;        /*! peripheral functionnal type                    */
-	uint32_t             impl;        /*! peripheral inplementation subtype              */
+	uint32_t             impl;        /*! peripheral implementation type                 */
     uint32_t             channel;     /*! channel index                                  */
     bool_t               is_rx;       /*! relevant for NIC and TXT peripherals           */
@@ -185,24 +187,24 @@
 chdev_directory_t;
 
-/******************************************************************************************
+/****************************************************************************************
  * This function display relevant values for a chdev descriptor.
- ******************************************************************************************
+ ****************************************************************************************
  * @ chdev   : pointer on chdev.
- *****************************************************************************************/
+ ***************************************************************************************/
 void chdev_print( chdev_t * chdev );
 
-/******************************************************************************************
+/****************************************************************************************
  * This function returns a printable string for a device functionnal types.
- ******************************************************************************************
+ ****************************************************************************************
  * @ func_type  : functionnal type.
  * @ return pointer on string.
- *****************************************************************************************/
+ ***************************************************************************************/
 char * chdev_func_str( uint32_t func_type );
 
-/******************************************************************************************
+/****************************************************************************************
  * This  function allocates memory and initializes a chdev descriptor in local cluster,
  * from arguments values.  It should be called by a local thread. 
  * The device specific fields are initialised later.
- ******************************************************************************************
+ ****************************************************************************************
  * @ func      : functionnal type.
  * @ impl      : implementation type.
@@ -211,5 +213,5 @@
  * @ base      : extended pointer on peripheral segment base.
  * @ return a local pointer on created chdev / return NULL if failure.
- *****************************************************************************************/
+ ***************************************************************************************/
 chdev_t * chdev_create( uint32_t    func,
                         uint32_t    impl,
@@ -218,50 +220,75 @@
                         xptr_t      base );
 
-/******************************************************************************************
- * This function registers the calling thread in the waiting queue of a remote 
- * chdev descriptor, activates (i.e. unblock) the server thread associated to chdev,
- * and blocks itself on the THREAD_BLOCKED_IO condition.
- ******************************************************************************************
+/****************************************************************************************
+ * This generid function is executed by an user thread requesting an IOC or TXT chdev
+ * service. It registers the calling thread in the waiting queue of a the remote
+ * chdev descriptor identified by the <chdev_xp> argument.
+ * It activates (i.e. unblocks) the server thread associated to chdev, blocks itself,
+ * and deschedule.  It is supposed to be re-activated by the server thread. 
+ * It can be called by a thread running in any cluster.
+ * It cannot be used for a NIC or FBF chdev, because it is only convenient for one shot
+ * I/O operations, as the server thread removes the client thread from the waiting
+ * queue when it starts to execute the command.
+ ****************************************************************************************
+ * Implementation Note:
+ * The following actions are executed in a critical section, thanks to the
+ * busylock_acquire / busylock_release mechanism :
+ * 1) it takes the lock protecting the waiting queue.
+ * 2) it registers client thread in the server queue. 
+ * 3) it unblocks the server thread from the THREAD_BLOCKED_CLIENT condition.
+ * 4) it blocks the client thread on the THREAD_BLOCKED_IO condition.
+ * 5) it send an IPI to the core running the server thread to force scheduling.
+ * 6) it releases the lock protecting waiting queue.
+ * 7) it deschedules.
+ ****************************************************************************************
  * @ chdev_xp  : extended pointer on remote chdev descriptor.
- *****************************************************************************************/
+ ***************************************************************************************/
 void chdev_register_command( xptr_t chdev_xp );
 
-/******************************************************************************************
- * This function is executed by the server thread associated to a chdev descriptor.
- * It executes an infinite loop to handle sequencially all commands registered by the
- * client threads in the device waiting queue, until the queue is empty.
- * The driver CMD function being blocking, these functions return only when the command
+/****************************************************************************************
+ * This generic function is executed by the server thread associated to an IOC or TXT
+ * chdev identified by the <chdev> argument, to execute all commands registered in the
+ * waiting queue attached to this chev. 
+ * When the clients queue is empty, the server thread blocks on the THREAD_BLOCKED_CLIENT
+ * condition and deschedules. It is supposed to be re-activated by a client thread 
+ * registering a new command.
+ * It cannot be used for a NIC or FBF chdev, because it is only convenient for one shot
+ * I/O operations, as the server thread removes the client thread from the waiting
+ * queue when it starts to execute the command.
+ ****************************************************************************************
+ * Implementation Note:
+ * All driver CMD functions are supposed to be blocking, and return only when the command
  * is completed. These functions can use either a busy waiting policy, or a descheduling
- * policy, blocking on the THREAD_BLOCKED_IO_ISR condition, and reactivated by the ISR.
- * When the waiting queue is empty, the server thread blocks on the THREAD_BLOCKED_IO_CMD
- * condition and deschedule. It is re-activated by a client thread registering a command.
- ******************************************************************************************
+ * policy, blocking on the THREAD_BLOCKED_ISR condition. In the descheduling scenario,
+ * the server thread is supposed to be reactivated by the ISR attached to the hardware
+ * interrupts signaling command completion.
+ ****************************************************************************************
  * @ chdev   : local pointer on device descriptor.
- *****************************************************************************************/
+ ***************************************************************************************/
 void chdev_server_func( chdev_t * chdev );
 
-/******************************************************************************************
+/****************************************************************************************
  * This function returns an extended pointer on the chdev associated to a pseudo file
  * descriptor (type INODE_TYPE_DEV) identified by the <file_xp> argument.
  * It can be called by a thread running in any cluster.
  * It enters kernel panic if the inode has not the expected type.
- ******************************************************************************************
+ ****************************************************************************************
  * @ file_xp   : extended pointer on the pseudo file descriptor.
  * @ return an extended pointer on chdev.
- *****************************************************************************************/
+ ***************************************************************************************/
 xptr_t chdev_from_file( xptr_t file_xp );
 
-/******************************************************************************************
+/****************************************************************************************
  * This function displays the local copy of the external chdevs directory.
  * (global variable replicated in all clusters)
- *****************************************************************************************/
+ ***************************************************************************************/
 void chdev_dir_display( void );
 
-/******************************************************************************************
+/****************************************************************************************
  * This function displays the list of threads registered in the queue associated
  * to the chdev identified by the <chdev_xp>. 
- ******************************************************************************************
+ ****************************************************************************************
  * # root_xp  : extended pointer
- *****************************************************************************************/
+ ***************************************************************************************/
 void chdev_queue_display( xptr_t chdev_xp );
 
