Changeset 430 for soft/giet_vm/giet_common/utils.h

Timestamp:

Oct 4, 2014, 3:21:56 PM (10 years ago)

Author:

alain

Message:

Introducing fixed format (X_WIDTH / YWIDTH / P_WIDTH) for processor index.

File:

• soft/giet_vm/giet_common/utils.h (modified) (4 diffs)

soft/giet_vm/giet_common/utils.h

@@ -8 +8 @@
 // They define more or less the GIET-VM Hardware Abstraction Layer,
 // and contains various utility functions, that can be used by both the 
-// boot code and the kernel code.
+// boot code and the kernel code (but not by the user applications).
 ///////////////////////////////////////////////////////////////////////////////////
 
@@ -150 +150 @@
 ///////////////////////////////////////////////////////////////////////////////////
 ///////////////////////////////////////////////////////////////////////////////////
-//     Physical addressing related functions
-///////////////////////////////////////////////////////////////////////////////////
-///////////////////////////////////////////////////////////////////////////////////
-
+//     Physical addressing functions
+///////////////////////////////////////////////////////////////////////////////////
+///////////////////////////////////////////////////////////////////////////////////
+
+////////////////////////////////////////////////////////////////////////////
+// This function makes a physical read access to a 32 bits word in memory, 
+// after a temporary DTLB de-activation and paddr extension.
+////////////////////////////////////////////////////////////////////////////
 extern unsigned int _physical_read(  unsigned long long paddr );
+
+////////////////////////////////////////////////////////////////////////////
+// This function makes a physical write access to a 32 bits word in memory, 
+// after a temporary DTLB de-activation and paddr extension.
+////////////////////////////////////////////////////////////////////////////
 extern void         _physical_write( unsigned long long paddr,
                                      unsigned int       value );
 
+////////////////////////////////////////////////////////////////////////////
+// This function makes a physical read access to a 64 bits word in memory, 
+// after a temporary DTLB de-activation and paddr extension.
+////////////////////////////////////////////////////////////////////////////
 extern unsigned long long _physical_read_ull(  unsigned long long paddr );
+
+////////////////////////////////////////////////////////////////////////////
+// This function makes a physical write access to a 64 bits word in memory, 
+// after a temporary DTLB de-activation and paddr extension.
+////////////////////////////////////////////////////////////////////////////
 extern void               _physical_write_ull( unsigned long long paddr,
                                                unsigned long long value );
 
+///////////////////////////////////////////////////////////////////////////////////
+// This function makes a memcpy from a source buffer to a destination buffer,
+// using physical addresses, after a temporary DTLB de-activation.
+// The source and destination buffers must be word aligned, and size must be
+// multiple of 4 bytes. 
+///////////////////////////////////////////////////////////////////////////////////
 extern void         _physical_memcpy( unsigned long long dst_paddr,
                                       unsigned long long src_paddr,
                                       unsigned int       size );
 
+///////////////////////////////////////////////////////////////////////////////////
+// This function set a data value in all words of a destination buffer,
+// using physical addresses, after a temporary DTLB de-activation.
+// The destination buffer must be word aligned, and size multiple of 4 bytes. 
+///////////////////////////////////////////////////////////////////////////////////
+extern void         _physical_memset( unsigned long long buf_paddr, 
+                                      unsigned int       size, 
+                                      unsigned int       data );
+
+///////////////////////////////////////////////////////////////////////////////////
+// This function is used by several drivers (_xxx_get_register() function).
+// If the MMU is not activated, the virtual address is extended using
+// X_IO and Y_IO to reach the cluster_io.
+///////////////////////////////////////////////////////////////////////////////////
 extern unsigned int _io_extended_read(  unsigned int* vaddr );
+
+///////////////////////////////////////////////////////////////////////////////////
+// This function is used by all drivers (_xxx_set_register() function)
+// If the MMU is not activated, the virtual address is extended using
+// X_IO and Y_IO to reach the cluster_io.
+///////////////////////////////////////////////////////////////////////////////////
 extern void         _io_extended_write( unsigned int* vaddr,
                                         unsigned int  value );
@@ -174 +218 @@
 ///////////////////////////////////////////////////////////////////////////////////
 
+
+///////////////////////////////////////////////////////////////////////////////////
+// Takes a lock with a blocking ll/sc atomic access.
+// - When the cache coherence is granted by the hardware,
+//   the first read is a standard (cacheable) lw, as the local copy
+//   can be polled when the lock is already taken by another task, reducing 
+//   trafic on the interconnect. When the lock is released by the owner task,
+//   the local copy is updated or invalidated by the coherence protocol.
+// - If there is no hardware cache coherence a random delay is introduced
+//   between two successive retry.
+///////////////////////////////////////////////////////////////////////////////////
 extern void         _get_lock(giet_lock_t* lock);
+
+///////////////////////////////////////////////////////////////////////////////////
+// Release a previouly taken lock.
+///////////////////////////////////////////////////////////////////////////////////
 extern void         _release_lock(giet_lock_t* lock);
+
 
 ///////////////////////////////////////////////////////////////////////////////////
@@ -190 +250 @@
 extern void         _getc( char*        byte );       
 
+
 ///////////////////////////////////////////////////////////////////////////////////
 //     Scheduler and task context access functions
 ///////////////////////////////////////////////////////////////////////////////////
 
+
+///////////////////////////////////////////////////////////////////////////////////
+// Returns index of the currently running task from the processor scheduler.
+///////////////////////////////////////////////////////////////////////////////////
 extern unsigned int _get_current_task_id(void);
 
-extern unsigned int _get_task_slot( unsigned int gpid,
+////////////////////////////////////////////////////////////////////////////////////
+// This function returns the content of a context slot 
+// for a task identified by the ltid argument (local task index),
+// and a processor identified by the (x,y,p) arguments.
+////////////////////////////////////////////////////////////////////////////////////
+extern unsigned int _get_task_slot( unsigned int x,
+                                    unsigned int y,
+                                    unsigned int p,
                                     unsigned int ltid,
                                     unsigned int slot );
-extern void         _set_task_slot( unsigned int gpid,
+
+////////////////////////////////////////////////////////////////////////////////////
+// This function updates the content of a context slot 
+// for any task identified by the ltid argument (local task index),
+// and a processor identified by the (x,y,p) arguments.
+////////////////////////////////////////////////////////////////////////////////////
+extern void         _set_task_slot( unsigned int x,
+                                    unsigned int y,
+                                    unsigned int p,
                                     unsigned int ltid,
                                     unsigned int slot,
                                     unsigned int value );
 
+////////////////////////////////////////////////////////////////////////////////////
+// This function returns the content of a context slot for the running task.
+////////////////////////////////////////////////////////////////////////////////////
 extern unsigned int _get_context_slot( unsigned int slot );
+
+////////////////////////////////////////////////////////////////////////////////////
+// This function updates the content of a context slot for the running task.
+////////////////////////////////////////////////////////////////////////////////////
 extern void         _set_context_slot( unsigned int slot,
                                        unsigned int value );