= Kernel Utilities = The [source:soft/giet_vm/giet_common/utils.c utils.c] and [source:soft/giet_vm/giet_common/utils.h util.h] files define kernel functions that are used both by the boot-loader and by the kernel. They are prefixed by ''_'' to remind that they can only be executed by a processor in kernel mode. * They are used by the boot-loader in the ''static'' phase, to build the page tables and initialize the schedulers and the peripherals. * They are also used by the kernel in the ''dynamic'' phase, to handle events such as interrupts, exceptions and syscalls. [[PageOutline]] == __1) CP0 registers access functions__ == === unsigned int _get_sched( void ) === Returns the virtual address of the scheduler, stored in the CP0_SCHED register, for the processor running the calling task. === unsigned int _get_epc( void ) === Returns the value stored in the CP0_EPC register, for the processor running the calling task. === unsigned int _get_cr( void ) === Returns the value stored in the CP0_CR register, for the processor running the calling task. === unsigned int _get_sr( void ) === Returns the value stored in the CP0_SR register, for the processor running the calling task. === unsigned int _get_bvar( void ) === Returns the value stored in the CP0_BVAR register, for the processor running the calling task. === unsigned int _get_procid( void ) === Returns the global processor identifier stored in the CP0_PROCID register for the processor running the calling task. === unsigned int _get_protime( void ) === Returns the cycle count stored in the CP0_TIME register for the processor running the calling task. === void _set_sched( unsigned int value ) === Writes ''value'' in the CP0_SCHED register, for the processor running the calling task. === void _set_sr( unsigned int value ) === Writes ''value'' in the CP0_SR register, for the processor running the calling task. === void _it_disable( unsigned int* save_sr_ptr ) === Disables interrupts for the processor running the calling task and save the CP0_SR value at address ''save_sr_ptr''. === void _it_restore( unsigned int* save_sr_ptr ) === Writes the value pointed by ''save_sr_ptr'' into the CP0_SR register, for the processor running the calling task. == __2) CP2 registers access functions__ == === unsigned int _get_mmu_ptpr( void ) === Returns the value stored in the CP2_PTPR register, for the processor running the calling task. === unsigned int _get_mmu_mode( void ) === Returns the value stored in the CP2_MODE register, for the processor running the calling task. === void _set_mmu_ptpr( unsigned int value ) === Writes ''value'' in the CP2_PTPR register, for the processor running the calling task. === void _set_mmu_mode( unsigned int value ) === Writes ''value'' in the CP2_MODE register, for the processor running the calling task. == __3) Physical addressing functions__ == === unsigned int _physical_read( unsigned long long paddr ) === Returns the 32 bits word stored at physical address ''paddr'', after a temporary DTLB deactivation. It uses the CP2_PADDR_EXT register. === void _physical_write( unsigned long long paddr, unsigned int value ) Writes the 32 bits word ''value'' at physical address ''paddr'', after a temporary DTLB deactivation. It uses the CP2_PADDR_EXT register. === unsigned long long _physical_read_ull( unsigned long long paddr ) === Returns the 64 bits word stored at physical address ''paddr'', after a temporary DTLB deactivation. It uses the CP2_PADDR_EXT register. === void _physical_write_ull( unsigned long long paddr, unsigned long long value ) === Writes the 64 bits word ''value'' at physical address ''paddr'', after a temporary DTLB deactivation. It uses the CP2_PADDR_EXT register. === void _physical_memcpy( unsigned long long dst_paddr, unsigned long long src paddr, unsigned int size ) === This function makes a memcpy from a source buffer to a destination buffer, using physical addresses, after a temporary DTLB de-activation. The ''src_paddr'', ''dst_paddr'' and ''size'' arguments must be multiple of 4 bytes. === unsigned int _io_extended_read( unsigned int* vaddr ) === This function is used by the GIET-VM drivers to read a 32 bits word in a peripheral register. If the MMU is not activated, the virtual address is extended using X_IO and Y_IO (defined in the hard-config.h file) to reach the cluster_io. === void _io_extended_write( unsigned int* vaddr, unsigned int value ) === This function is used by the GIET-VM drivers to write a 32 bits word in a peripheral register. If the MMU is not activated, the virtual address is extended using X_IO and Y_IO (defined in the hard-config.h file) to reach the cluster_io. == __4) Spin-lock access functions__ == The ''giet_lock_t'' structure is defined in the ''utils.h'' file to have one single lock in a 64 bytes cache line. It should be aligned on a cache line boundary. === void _get_lock( giet_lock_t lock ) === Takes a lock with a blocking ll/sc atomic access. If 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 pseudo random delay is introduced between two successive retry. === void _release_lock( giet_lock_t lock ) === Releases (or initializes) a lock. == __5) TTY0 access functions == === void _puts( char* string ) === Displays a ''string'' on kernel TTY0. This function does NOT take the TTY0 lock. === void _putx( unsigned int value ) === Displays a 32 bits word as an hexadecimal string on kernel TTY0. This function does NOT take the TTY0 lock. === void _putl( unsigned long long value ) === Displays a 64 bits word as an hexadecimal string on kernel TTY0. This function does NOT take the TTY0 lock. === void _putd( unsigned int value ) === Displays a 32 bits word as an decimal string on kernel TTY0. This function does NOT take the TTY0 lock. === void _printf( char* format, ... ) === Display a format on kernel TTY0. To provide an atomic display, this function takes the lock protecting exclusive access to TTY0, entering a critical section until the lock is released. Only a limited number of formats are supported: * %d : 32 bits signed decimal * %u : 32 bits unsigned decimal * %x : 32 bits unsigned hexa * %l : 64 bits unsigned hexa * %c : char * %s : string === void _getc( char* byte ) === This blocking function uses a polling strategy on the TTY0 status register to get a single character. == __6) Task context access functions__ == === unsigned int _get_current_task_id( void ) === This function returns the local index of the currently running task from the processor scheduler. === unsigned int _get_task_slot( unsigned int gpid, unsigned int ltid, unsigned int slot ) This function returns the content of a context ''slot'' for a task identified by the the ''gpid'' argument (global processor index), and the ''ltid'' argument (local task index on the processor). === void _set_task_slot( unsigned int gpid, unsigned int ltid, unsigned int slot, unsigned int value ) This function writes ''value'' in the the context ''slot'' of the task identified by the the ''gpid'' argument (global processor index), and the ''ltid'' argument (local task index on the processor). === unsigned int _get_context_slot( unsigned int slot ) This function returns the content of a context ''slot'' for the calling task. === void _set_task_slot( unsigned int slot, unsigned int value ) This function writes ''value'' in the the context ''slot'' of the running task. == __7) Mapping access functions These functions can be used by both the boot-loader and the kernel to extract informations from the mapping_info data structure (defined in the ''mapping_info.h'' file), that has been loaded into system memory by the boot-loader. === mapping_cluster_t* _get_cluster_base( mapping_header_t* header ) === Returns a pointer on the first cluster in the clusters array. === mapping_cluster_t* _get_cluster_base( mapping_header_t* header ) === Returns a pointer on the first cluster in the clusters array. === mapping_pseg_t* _get_pseg_base( mapping_header_t* header ) === Returns a pointer on the first pseg in the psegs array. === mapping_vspace_t* _get_vspace_base( mapping_header_t* header ) === Returns a pointer on the first vspace in the vspaces array. === mapping_vseg_t* _get_vseg_base( mapping_header_t* header ) === Returns a pointer on the first vseg in the vsegs array. === mapping_vobj_t* _get_vobj_base( mapping_header_t* header ) === Returns a pointer on the first vobj in the vobjs array. === mapping_cluster_t* _get_task_base( mapping_header_t* header ) === Returns a pointer on the first task in the tasks array. === mapping_cluster_t* _get_proc_base( mapping_header_t* header ) === Returns a pointer on the first proc in the procs array. === mapping_cluster_t* _get_irq_base( mapping_header_t* header ) === Returns a pointer on the first irq in the irqs array. === mapping_cluster_t* _get_coproc_base( mapping_header_t* header ) === Returns a pointer on the first coproc in the coprocs array. === mapping_cluster_t* _get_cp_port_base( mapping_header_t* header ) === Returns a pointer on the first cpport in the cpports array. === mapping_cluster_t* _get_periph_base( mapping_header_t* header ) === Returns a pointer on the first periph in the periphs array. == __X) Miscelaneous functions__ == === void _exit() === Processor suicide with a dated message on TTY0 in case of kernel panic. === void _random_wait( unsigned int value ) === This function implements a pseudo-random delay. The ''value'' argument define an exponentially increasing mean delay, and should not be larger than 32. === void _break( char* string ) === This blocking function implements an interactive break for kernel debug. === unsigned int _strncmp( const char* s1, const char* s2, unsigned int n ) === Compare two strings ''s1'' and ''s2'', no more than n characters. === char* _strcpy( char* dest, char* source ) === Copy source string to dest string. === void _dcache_buf_invalidate( void* buffer, unsigned int size ) === Invalidate all data cache lines corresponding to a memory buffer identified by a virtual base address and a size. === unsigned int _heap_info( unsigned int* vaddr, unsigned int* size, unsigned int x, unsigned int y ) === This function returns in the ''vaddr'' and '' size'' arguments the information associated to a heap. If (x < X_SIZE) and (y < Y_SIZE), it return the heap associated to any task running in cluster(x,y). Else, it return the heap associated to the calling task. It uses the mapping_info structure to retrieve information, and return 0 if success. Return non zero if not found.