Changeset 413 for soft/giet_vm/giet_drivers/ioc_driver.h

Timestamp:

Sep 29, 2014, 12:02:13 PM (10 years ago)

Author:

alain

Message:

Introducing support for the PIC_MASK register in pic_driver.

File:

• soft/giet_vm/giet_drivers/ioc_driver.h (modified) (4 diffs)

soft/giet_vm/giet_drivers/ioc_driver.h

@@ -4 +4 @@
 // Author   : alain greiner
 // Copyright (c) UPMC-LIP6
+///////////////////////////////////////////////////////////////////////////////////
+// The ioc_driver.c and ioc_driver.h files are part ot the GIET-VM kernel.
+//
+// This abstact driver define a generic API, supporting various physical
+// block device controlers, including:
+// - vci_block_device : single channel                     => bdv_driver
+// - vci_ahci         : multi channels                     => hba_driver
+// - sd_card          : single channel                     => sdc_driver
+// - ramdisk (single channel meory mapped virtual disk)    => rdk_driver
+//
+// It can exist only one block-device type in the architecture, that must be
+// defined by one of the following configuration variables in hard_config.h file:
+// USE_IOC_BDV, USE_IOC_SDC, USE_IOC_HBA, USE_IOC_RDK.
+//
+// Any physical block device driver xxx must provide the following API:
+// - _xxx_init()
+// - _xxx_read()
+// - _xxx_write()
+// - _xxx_get_status()
+// - _xxx_get_block_size()
+// The "channel" parameter is no transmited to single channel devices.
+//
+// The _ioc_read() and _ioc_write() functions are always blocking for
+// the calling user program.
+//
+// These functions compute the physical address of the memory buffer before 
+// calling the proper physical device. We know that the user buffer is mapped 
+// to a contiguous physical buffer because, for each vseg, the page tables
+// are statically constructed to use contiguous physical memory.
+//
+// These functions can be called in 3 modes:
+//
+// - In BOOT mode, these functions use the buffer virtual address
+//   as a physical address if the MMU is not activated.
+//   They make a V2P translation if the MMU is activated.
+//   This mode is used to load the map.bin file (before memory activation),
+//   or to load the various .elf files (after MMU activation).
+//
+// - In KERNEL mode, these functions make a V2P translation to
+//   compute the buffer physical address.
+//   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 make a V2P translation to
+//   compute the buffer physical address. 
+//   The user access right to the memory buffer are checked.  
+//   This mode must be used for a "read" or "write" system call.
+//
+// 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,
+// - The total number of physical pages occupied by the user buffer cannot
+//   be larger than 512 pages if the IOMMU is activated,
+// - All physical pages occupied by the user buffer must be contiguous
+//   if the IOMMU is not activated.
+// Exit if these conditions are not verified.
+//
+// The SEG_IOC_BASE virtual base address must be defined in hard_config.h,
+// as it is used by the BDV, HBA and SPI drivers.
+//
+// If the RAMDISK is used, an extra memory segment with virtual base address
+// SEG_RDK_BASE, used by RDK driver, must be defined in hard_config.h.
+///////////////////////////////////////////////////////////////////////////////////
+// Implementation note:
+//
+// 1) In order to share the code, the two _ioc_read() and _ioc_write() functions
+// call the same _ioc_access() function.
+//
+// 2) The IOMMU is not supported yet, but the method is the following:
+// A fixed size 2 Mbytes vseg is allocated to the IOC peripheral, in the I/O 
+// virtual space, and the user buffer is dynamically remapped to one single
+// big page in the IOMMU page table.
+// The user buffer is unmapped by the _ioc_completed() function when 
+// the transfer is completed.
 ///////////////////////////////////////////////////////////////////////////////////
 
@@ -31 +106 @@
 ///////////////////////////////////////////////////////////////////////////////////
 
+///////////////////////////////////////////////////////////////////////////////
+// This function cheks block size, and desactivates the IOC interrupts.
+// Return 0 for success, non zero if error.
+///////////////////////////////////////////////////////////////////////////////
 extern unsigned int _ioc_init( unsigned int channel );
 
+///////////////////////////////////////////////////////////////////////////////
+// Transfer data from a memory buffer to the block device. 
+// - mode     : BOOT_PA / BOOT_VA / KERNEL / USER 
+// - lba      : first block index on the block device
+// - buffer   : base address of the memory buffer (must be word aligned)
+// - count    : number of blocks to be transfered.
+// Returns 0 if success, > 0 if error.
+///////////////////////////////////////////////////////////////////////////////
 extern unsigned int _ioc_write( unsigned int channel,
                                 unsigned int mode,
@@ -39 +126 @@
                                 unsigned int count );
 
+///////////////////////////////////////////////////////////////////////////////
+// Transfer data from the block device to a memory buffer. 
+// - mode     : BOOT_PA / BOOT_VA / KERNEL / USER 
+// - lba      : first block index on the block device
+// - buffer   : base address of the memory buffer (must be word aligned)
+// - count    : number of blocks to be transfered.
+// Returns 0 if success, > 0 if error.
+///////////////////////////////////////////////////////////////////////////////
 extern unsigned int _ioc_read(  unsigned int channel,
                                 unsigned int mode,
@@ -45 +140 @@
                                 unsigned int count );
 
+///////////////////////////////////////////////////////////////////////////////
+// This function returns in the status variable, the transfert status, and
+// acknowledge the IRQ if the IOC controler is not busy.
+// Returns 0 if success, > 0 if error
+///////////////////////////////////////////////////////////////////////////////
 extern unsigned int _ioc_get_status( unsigned int channel );
 
+///////////////////////////////////////////////////////////////////////////////
+// This function returns the block_size for the block device.
+///////////////////////////////////////////////////////////////////////////////
 extern unsigned int _ioc_get_block_size();
-
-///////////////////////////////////////////////////////////////////////////////////