===================================================================
GM/Linux README
===================================================================

Files:
	
gm_arch.c: the main code for the Linux driver part of GM
gm_arch.h : linux GM macros and inline functions
gm_arch_types.h : linux GM structures
gm_arch_def.h : macros and inline functions that deals with the difference between the linux flavors (arch and version)
gm_lanai_dump.[ch] : implementation of gm_pseudo_global_clone() which
   creates an in-memory representation of the lanai structures for
   debugging purposes

A few assumption:
=================

sizeof(unsigned long) == sizeof(void*)
sizeof(gm_phys_t) might be strictly > sizeof(void*)
  but  max-phys-address / PAGE_SIZE can be represented with unsigned long
  (typically for x86/PAE)

Implementation comments:
========================


NOTE about virtual adresses:
****************************
We can manipulate 6 different kind of addresses:
1)User virtual addresses
2)Kernel virtual addresses
3)Kernel "canonical" address ("canonical" is not an official term,
  but it is what I propose)
4)Device Addresses used for ioremap and in pdev->pci_resourse_start
5)Physical address for main bus
6)PCI addresses

Explanation:
1) a user address is what is used inside its processes: it is supposed here
 to be equivalent to 4) as regards conversion to physical address (but it
 is in a distinct range)
2) and 3) can directly be referenced in kernel mode, the difference is:
 - a "canonical" address is within the mapping that every Linux kernel makes
 to map the complete physical memory (and on the Alpha to map all IO
 spaces), if this is an adress representing main memory, we can get
 the physical address via __pa(), which is a translation.
 Canon addresses for real memory are guaranteed to be in the range:
 [PAGE_OFFSET;high_memory[ [??? --Glenn]
 - a kernel virtual address has been allocated via vmalloc(), or vremap()
 kernel virtual addresses are fed through the MMU and can be dereferenced
 directly in the driver
4) Depending on arch/linux-version the device addresses found in 
   pdev might be either a bus address, a physical address, a virtual address
   but it can normally be fed directly to ioremap
5) This is an address after MMU translation, it can also be obtained from 3)
   by translation
6) PCI addresses are adress as they are used on the PCI bus.
   The address of main memory asseen on the PCI bus is obtained by
   virt_to_bus().

On the ALPHA physical space is uniformly mapped at IDENT_ADDR, the
current canonical address base is PAGE_OFFSET which is currently
always the same as IDENT_ADDR, although I try not make this assumption
in the driver, I verify that through an assertion, should it be
changed, people will be aware of the fact.

virt_to_bus() and __pa() take a canonical address and give a
physical address.  You cannot feed them a general kernel virtual
address.  You cannot feed them an IO address.

An important function of this module is gm_linux_kvirt_to_phys() which
takes either a kernel or a user addresse (depending on boolean second
argument) and gives the corresponding physical address.

Most Linux functions are organized to manipulate canonical address:
pte_page()
MAP_NR()
high_memory [This is not a function. --Glenn]
mk_pte()

So we manipulate physical addresses everywhere using extensively gm_linux_kvirt_to_phys.

The memory physically begins at __pa((void*)PAGE_OFFSET). This will be 0 in 
all cases I know, so a lot of assertions will convert into 
((unsigned_value) >= 0), but better to leave them in case
we want to use it on some other platforms (maybe in sparc64 PAGE_OFFSET is != 0).

