wiki:common_utils

Version 14 (modified by alain, 10 years ago) (diff)

--

Kernel Utilities

The utils.c and 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.

  1. Kernel Utilities
    1. 1) CP0 registers access functions
      1. unsigned int _get_sched( void )
      2. unsigned int _get_epc( void )
      3. unsigned int _get_cr( void )
      4. unsigned int _get_sr( void )
      5. unsigned int _get_bvar( void )
      6. unsigned int _get_procid( void )
      7. unsigned int _get_protime( void )
      8. void _set_sched( unsigned int value )
      9. void _set_sr( unsigned int value )
      10. void _it_disable( unsigned int* save_sr_ptr )
      11. void _it_restore( unsigned int* save_sr_ptr )
    2. 2) CP2 registers access functions
      1. unsigned int _get_mmu_ptpr( void )
      2. unsigned int _get_mmu_mode( void )
      3. void _set_mmu_ptpr( unsigned int value )
      4. void _set_mmu_mode( unsigned int value )
    3. 3) Physical addressing functions
      1. unsigned int _physical_read( unsigned long long paddr )
      2. void _physical_write( unsigned long long paddr, unsigned int value )
      3. unsigned long long _physical_read_ull( unsigned long long paddr )
      4. void _physical_write_ull( unsigned long long paddr, unsigned long long …
      5. void _physical_memcpy( unsigned long long dst_paddr, unsigned long …
      6. unsigned int _io_extended_read( unsigned int* vaddr )
      7. void _io_extended_write( unsigned int* vaddr, unsigned int value )
    4. 4) Spin-lock access functions
      1. void _get_lock( giet_lock_t lock )
      2. void _release_lock( giet_lock_t lock )
    5. 5) TTY0 access functions
      1. void _puts( char* string )
      2. void _putx( unsigned int value )
      3. void _putl( unsigned long long value )
      4. void _putd( unsigned int value )
      5. void _printf( char* format, ... )
      6. void _getc( char* byte )
    6. 6) Task context access functions
      1. unsigned int _get_current_task_id( void )
      2. unsigned int _get_task_slot( unsigned int gpid, unsigned int ltid, …
      3. void _set_task_slot( unsigned int gpid, unsigned int ltid, unsigned …
      4. unsigned int _get_context_slot( unsigned int slot )
      5. void _set_task_slot( unsigned int slot, unsigned int value )
    7. 7) Mapping access functions
      1. mapping_cluster_t* _get_cluster_base( mapping_header_t* header )
      2. mapping_cluster_t* _get_cluster_base( mapping_header_t* header )
      3. mapping_pseg_t* _get_pseg_base( mapping_header_t* header )
      4. mapping_vspace_t* _get_vspace_base( mapping_header_t* header )
      5. mapping_vseg_t* _get_vseg_base( mapping_header_t* header )
      6. mapping_vobj_t* _get_vobj_base( mapping_header_t* header )
      7. mapping_cluster_t* _get_task_base( mapping_header_t* header )
      8. mapping_cluster_t* _get_proc_base( mapping_header_t* header )
      9. mapping_cluster_t* _get_irq_base( mapping_header_t* header )
      10. mapping_cluster_t* _get_coproc_base( mapping_header_t* header )
      11. mapping_cluster_t* _get_cp_port_base( mapping_header_t* header )
      12. mapping_cluster_t* _get_periph_base( mapping_header_t* header )
    8. X) Miscelaneous functions
      1. void _exit()
      2. void _random_wait( unsigned int value )
      3. void _break( char* string )
      4. unsigned int _strncmp( const char* s1, const char* s2, unsigned int n )
      5. char* _strcpy( char* dest, char* source )
      6. void _dcache_buf_invalidate( void* buffer, unsigned int size )
      7. unsigned int _heap_info( unsigned int* vaddr, unsigned int* size, …

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.