Changes between Version 3 and Version 4 of hba_driver

Timestamp:

Mar 25, 2015, 7:14:56 PM (10 years ago)

Author:

alain

Comment:

--

hba_driver

@@ -5 +5 @@
 The [source:soft/giet_vm/giet_drivers/hba_driver.c hba_driver.c] and [source:soft/giet_vm/giet_drivers/hba_driver.h hba_driver.h] files define the HBA driver.
 
-The ''vci_multi_ahci'' component is a multi-channels, block oriented, external mass storage controller respecting the AHCI standard.
+The ''vci_multi_ahci'' component is a multi-channels, block oriented, external mass storage controller respecting the AHCI standard. Each channel define an independant physical disk, but this driver supports only one channel, because the GIET-VM uses only one physical disk.
 
-This driver is called by the generic IOC driver when the USE_IOC_HBA flag is set in the hard_config.h file.
+The '''Command List''' is a software FIFO that can contain up to 32 independant commands, posted by different user tasks. These independant transfers are handled by the HBA device in the same order as they have been written in the command list. There is no global lock protecting the the HBA device, but the command list being a shared structure, the driver uses an atomic_increment() to get a slot in the command list, and increment the write pointer.
+
+This driver implements two operating mode: 
+ * In '''synchronous mode''', the calling task uses a polling strategy on the HBA_PXCI register to detect the command completion (busy waiting). It does not use interrupt. 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 '''descheduling mode''', the calling task is descheduled, and the calling task global index is saved in the ''_hba_gtid[32] array, indexed by the command index. The task must be reactivated  when the command is completed. This mode is used, to handle the user system calls. 
+
+As several user tasks can concurrently register commands in the command list, and there is only one HBA interrupt per channel, this interrupt is not linked to a specific calling task: in descheduling mode, the HBA IRQ is a "global" IRQ that is statically routed to processor P[x_io,y_io,0] in cluster_io.  The associated global HBA_ISR send a WAKUP WTI to all tasks that have a completed command. This HBA_ISR uses a read pointer on the Command List to identify the expected command completion. The incrementation of this read pointer does not require atomic_increment as there is no concurrent access on this pointer. 
 
 The SEG_IOC_BASE address must be defined in the hard_config.h file.
@@ -13 +19 @@
 The addressable registers map is defined [source:soft/giet_vm/giet_drivers/hba_driver.h here]. 
 
+ == __HBA access functions__ ==
 
+ === unsigned int '''_hba_init'' ( ) === 
+This function checks the block size and desactivates interrupts. It initializes
+the HBA hardware registers, and the Command List.
+Return 0 for success, > 0 if error.
 
- === unsigned int '''_hba_init'' ( unsigned int channel ) === 
-This function initializes for a given channel
- *  the HBA hardware registers,
- *  the command list pointer,
- *  the command lists physical addresse,
- *  the command tables physical addresses array,
-
- === unsigned int '''_hba_write'''( unsigned int channel,   unsigned int mode,  unsigned int lba,  unsigned long long paddr,  unsigned int count ) ===    
-This function register a write command in Command List and Command Table for a single physical buffer, and updates the HBA_PXCI register.
- * channel : channel index
- * mode :   BOOT / KERNEL / USER
- * lba :  logic bloc address on device
- * paddr : memory buffer physical base address
- * count : number of blocs
+ === unsigned int '''_hba_access'''( unsigned int use_irq  ,  unsigned int to_mem  ,  unsigned int lba ,  unsigned long long paddr,  unsigned int count ) ===    
+This function register a command in the Command List (and associated Command Table) for a single physical buffer, and updates the HBA_PXCI register.
+ * '''use_irq''': Boolean => request to use the descheduling mode if non zero
+ * '''to_mem''' :  Boolean => to memory transfer if non zero
+ * '''lba''' :  logic bloc address on device
+ * '''paddr''' : memory buffer physical base address
+ * '''count''' : number of blocs
 Returns 0 if success, > 0 if error.
 
- === unsigned int '''_hba_read'''( unsigned int channel,   unsigned int mode,  unsigned int lba,  unsigned long long paddr,  unsigned int count ) ===    
-This function register a read command in Command List and Command Table for a single physical buffer, and updates the HBA_PXCI register.
- * channel : channel index
- * mode :   BOOT / KERNEL / USER
- * lba :  logic bloc address on device
- * paddr : memory buffer physical base address
- * count : number of blocs
-Returns 0 if success, > 0 if error.
+=== void '''_hba_isr'''( unsigned int irq_type , unsigned int irq_id , unsigned int channel ) ===
+This Interrupt Service routine is only used in the descheduling mode. It analyses the HBA_PXCI register, and for all completed commands, it saves the status value in the ''_hba_status[32]'' array, indexed by the command index, and activates the task waiting completion of this command.
+ * '''irq_type''' : HWI / PTI / WTI
+ * '''irq-id'''     : index returned by XCU
+ * '''channel'''  : unused (only one HBA channel is supported).
 
- === unsigned int '''_hba_get_block_size''' () ===
-This function returns the block_size of HBA controller
-
- === unsigned int '''_hba_get_status'''( unsigned int   channel ) ===
-This function returns the content of the HBA_PXIS register for a given channel,  and reset this register to acknoledge IRQ.
-Return 0 if success, > 0 if error
-