= GIET-VM / BDV Driver = 

[[PageOutline]]

The [source:soft/giet_vm/giet_drivers/bdv_driver.c bdv_driver.c] and [source:soft/giet_vm/giet_drivers/bdv_driver.h bdv_driver.h] files define the BDV driver. 

This component is a single channel, block oriented, external mass storage peripheral, available in the SoCLib components library. 

This driver is called by the generic IOC driver when the USE_IOC_BDV flag is set in the hard_config.h file.

The SEG_IOC_BASE address must be defined in the hard_config.h file.

The _bdv_read() and _bdv_write() functions are always blocking. They can be called in 3 modes:
 * In '''BOOT''' mode, these functions use a polling policy on the BDV STATUS register to detect transfer completion, as interrupts are not activated. This mode is used by the boot code to load the map.bin file into memory (before MMU activation), or to load the .elf files (after MMU activation). 
 * In '''KERNEL''' mode, these functions use a descheduling strategy: The ISR executed when transfer completes should restart the calling task. There is no checking of user access right to the memory buffer. This mode must be used, for an ''open'' system call.
 * In '''USER''' mode, these functions use a descheduling strategy: The ISR executed when transfer completes should restart the calling task. The user access right to the memory buffer must be checked. This mode must be used for a ''read'' or ''write'' system call.

The BDV component is single channel, but can be used by several programs running in parallel, as the _bdv_lock variable guaranties exclusive access to the device.  The _bdv_read() and _bdv_write() functions use atomic LL/SC to get the lock.

Finally, the memory buffer must fulfill the following conditions:
 * The buffer must be word aligned, 
 * The buffer must be mapped in user space for an user access, 
 * The buffer must be writable in case of (to_mem) access,
 * All physical pages occupied by the user buffer must be contiguous.
An error code is returned if these conditions are not verified.

The addressable registers map, the operation codes, and the status values are defined [source:soft/giet_vm/giet_drivers/bdv_driver.h here].


 
 === unsigned int '''_bdv_init'''() ===
This function cheks block size == 512, and desactivates the interrupts.
Return 0 for success, > 0 if error

 === unsigned int '''_bdv_read'''(  unsigned int mode,  unsigned int lba, unsigned long long buffer,  unsigned int count ) ===
This function transfer data from the block device to a memory buffer. 
 * mode     : BOOT / KERNEL / USER
 * lba       : first block index on the block device
 * buffer   : physical base address of the memory buffer (word aligned)
 * count    : number of blocks to be transfered.
Returns 0 if success, > 0 if error.

 === unsigned int '''_bdv_write'''( unsigned int mode,  unsigned int lba,  unsigned long long buffer,  unsigned int count ) ===
This function transfer data from a memory buffer to the block device. 
 * mode     : BOOT / KERNEL / USER
 * lba       : first block index on the block device
 * buffer   : physical base address of the memory buffer (word aligned)
 * count    : number of blocks to be transfered.
Returns 0 if success, > 0 if error.

 === unsigned int '''_bdv_get_status'''() ===
This function returns device status. Status values are defined in  the [source:soft/giet_vm/giet_drivers/bdv_driver.h bdv_driver.h] file.

 ===  unsigned int '''_bdv_get_block_size'''() ===
This function returns the block size (bytes).

 === void '''_bdv_isr'''( unsigned irq_type,  unsigned irq_id,  unsigned channel ) ===
This Interrupt Service Routine save the status, acknowledge the IRQ, and activates the task waiting on IO transfer. It can be an HWI or a SWI.
 * irq_type : HWI / PTI / WTI
 * irq-id     : index returned by ICU/XCU
 * channel  : unused (block-device peripheral is single channel).