docs: ia64: convert to ReST

	         MEMORY ATTRIBUTE ALIASING ON IA-64

==================================

Memory Attribute Aliasing on IA-64

==================================

Bjorn Helgaas <bjorn.helgaas@hp.com>

			   Bjorn Helgaas

		       <bjorn.helgaas@hp.com>

May 4, 2006

MEMORY ATTRIBUTES

Memory Attributes

=================

    Itanium supports several attributes for virtual memory references.

    The attribute is part of the virtual translation, i.e., it is

    contained in the TLB entry.  The ones of most interest to the Linux

    kernel are:

	==		======================

        WB		Write-back (cacheable)

	UC		Uncacheable

	WC		Write-coalescing

	==		======================

    System memory typically uses the WB attribute.  The UC attribute is

    used for memory-mapped I/O devices.  The WC attribute is uncacheable

    support either WB or UC access to main memory, while others support

    only WB access.

MEMORY MAP

Memory Map

==========

    Platform firmware describes the physical memory map and the

    supported attributes for each region.  At boot-time, the kernel uses

    The efi_memmap table is preserved unmodified because the original

    boot-time information is required for kexec.

KERNEL IDENTITY MAPPINGS

Kernel Identify Mappings

========================

    Linux/ia64 identity mappings are done with large pages, currently

    either 16MB or 64MB, referred to as "granules."  Cacheable mappings

    are only partially populated, or populated with a combination of UC

    and WB regions.

USER MAPPINGS

User Mappings

=============

    User mappings are typically done with 16K or 64K pages.  The smaller

    page size allows more flexibility because only 16K or 64K has to be

    homogeneous with respect to memory attributes.

POTENTIAL ATTRIBUTE ALIASING CASES

Potential Attribute Aliasing Cases

==================================

    There are several ways the kernel creates new mappings:

mmap of /dev/mem

----------------

	This uses remap_pfn_range(), which creates user mappings.  These

	mappings may be either WB or UC.  If the region being mapped

	machines, this should use an uncacheable mapping as a fallback.

mmap of /sys/class/pci_bus/.../legacy_mem

-----------------------------------------

	This is very similar to mmap of /dev/mem, except that legacy_mem

	only allows mmap of the one megabyte "legacy MMIO" area for a

	The /dev/mem mmap constraints apply.

mmap of /proc/bus/pci/.../??.?

------------------------------

	This is an MMIO mmap of PCI functions, which additionally may or

	may not be requested as using the WC attribute.

	kernel mapping.

read/write of /dev/mem

----------------------

	This uses copy_from_user(), which implicitly uses a kernel

	identity mapping.  This is obviously safe for things in

	any control over the access size, so this would be dangerous.

ioremap()

---------

	This returns a mapping for use inside the kernel.

	Failing all of the above, we have to fall back to a UC mapping.

PAST PROBLEM CASES

Past Problem Cases

==================

mmap of various MMIO regions from /dev/mem by "X" on Intel platforms

--------------------------------------------------------------------

      The EFI memory map may not report these MMIO regions.

      on whether the region is in kern_memmap or the EFI memory map.

mmap of 0x0-0x9FFFF /dev/mem by "hwinfo" on HP sx1000 with VGA enabled

----------------------------------------------------------------------

      The EFI memory map reports the following attributes:

        =============== ======= ==================

        0x00000-0x9FFFF WB only

        0xA0000-0xBFFFF UC only (VGA frame buffer)

        0xC0000-0xFFFFF WB only

        =============== ======= ==================

      This mmap is done with user pages, not kernel identity mappings,

      so it is safe to use WB mappings.

      the driver explicitly touches them.

mmap of 0x0-0xFFFFF legacy_mem by "X"

-------------------------------------

      If the EFI memory map reports that the entire range supports the

      same attributes, we can allow the mmap (and we will prefer WB if

      mmap and force the user to map just the specific region of interest.

mmap of 0xA0000-0xBFFFF legacy_mem by "X" on HP sx1000 with VGA disabled

------------------------------------------------------------------------

      The EFI memory map reports the following attributes::

      The EFI memory map reports the following attributes:

        0x00000-0xFFFFF WB only (no VGA MMIO hole)

      This is a special case of the previous case, and the mmap should

      fail for the same reason as above.

read of /sys/devices/.../rom

----------------------------

      For VGA devices, this may cause an ioremap() of 0xC0000.  This

      used to be done with a UC mapping, because the VGA frame buffer

      We should use WB page table mappings to avoid covering the VGA

      frame buffer.

NOTES

Notes

=====

    [1] SDM rev 2.2, vol 2, sec 4.4.1.

    [2] SDM rev 2.2, vol 2, sec 4.4.6.

==========================

EFI Real Time Clock driver

-------------------------------

==========================

S. Eranian <eranian@hpl.hp.com>

March 2000

I/ Introduction

1. Introduction

===============

This document describes the efirtc.c driver has provided for

the IA-64 platform.

driver. We describe those calls as well the design of the driver in the

following sections.

II/ Design Decisions

2. Design Decisions

===================

The original ideas was to provide a very simple driver to get access to,

at first, the time of day service. This is required in order to access, in a

in include/linux/mc146818rtc.h.

III/ Time of day service

3. Time of day service

======================

The part of the driver gives access to the time of day service of EFI.

Two ioctl()s, compatible with the legacy RTC calls:

	Read the CMOS clock: ioctl(d, RTC_RD_TIME, &rtc);

	Read the CMOS clock::

		ioctl(d, RTC_RD_TIME, &rtc);

	Write the CMOS clock::

	Write the CMOS clock: ioctl(d, RTC_SET_TIME, &rtc);

		ioctl(d, RTC_SET_TIME, &rtc);

The rtc is a pointer to a data structure defined in rtc.h which is close

to a struct tm:

to a struct tm::

  struct rtc_time {

          int tm_sec;

Those two ioctl()s can be exercised with the hwclock command:

For reading:

For reading::

	# /sbin/hwclock --show

	Mon Mar  6 15:32:32 2000  -0.910248 seconds

For setting:

For setting::

	# /sbin/hwclock --systohc

Root privileges are required to be able to set the time of day.

IV/ Wakeup Alarm service

4. Wakeup Alarm service

=======================

EFI provides an API by which one can program when a machine should wakeup,

i.e. reboot. This is very different from the alarm provided by the legacy

We have added 2 new ioctl()s that are specific to the EFI driver:

	Read the current state of the alarm

	Read the current state of the alarm::

		ioctl(d, RTC_WKLAM_RD, &wkt)

	Set the alarm or change its status

	Set the alarm or change its status::

		ioctl(d, RTC_WKALM_SET, &wkt)

The wkt structure encapsulates a struct rtc_time + 2 extra fields to get

status information:

status information::

  struct rtc_wkalrm {

Root privileges are required to be able to set the alarm.

V/ References.

5. References

=============

Checkout the following Web site for more information on EFI:

========================================

IPF Machine Check (MC) error inject tool

========================================

the pal_mc_error_inject PAL procedure. The following err.conf has been tested

on latest Montecito PAL.

err.conf:

err.conf::

  #This is configuration file for err_inject_tool.

  #The format of the each line is:

The sample application source code:

err_injection_tool.c:

err_injection_tool.c::

  /*

   * This program is free software; you can redistribute it and/or modify

	return 0;

  }

-*-Mode: outline-*-

===================================

Light-weight System Calls for IA-64

		-----------------------------------

===================================

		        Started: 13-Jan-2003

		    Last update: 27-Sep-2003

	              David Mosberger-Tang

care (see below).

* How to tell fsys-mode

How to tell fsys-mode

=====================

Linux operates in fsys-mode when (a) the privilege level is 0 (most

privileged) and (b) the stacks have NOT been switched to kernel memory

yet.  For convenience, the header file <asm-ia64/ptrace.h> provides

three macros:

three macros::

	user_mode(regs)

	user_stack(task,regs)

user_stack() returns TRUE if the state pointed to by "regs" was

executing on the user-level stack(s).  Finally, fsys_mode() returns

TRUE if the CPU state pointed to by "regs" was executing in fsys-mode.

The fsys_mode() macro is equivalent to the expression:

The fsys_mode() macro is equivalent to the expression::

	!user_mode(regs) && user_stack(task,regs)

* How to write an fsyscall handler

How to write an fsyscall handler

================================

The file arch/ia64/kernel/fsys.S contains a table of fsyscall-handlers

(fsyscall_table).  This table contains one entry for each system call.

The entry and exit-state of an fsyscall handler is as follows:

** Machine state on entry to fsyscall handler:

 - r10	  = 0

 - r11	  = saved ar.pfs (a user-level value)

 - r15	  = system call number

 - r16	  = "current" task pointer (in normal kernel-mode, this is in r13)

 - r32-r39 = system call arguments

 - b6	  = return address (a user-level value)

 - ar.pfs = previous frame-state (a user-level value)

 - PSR.be = cleared to zero (i.e., little-endian byte order is in effect)

Machine state on entry to fsyscall handler

------------------------------------------

  ========= ===============================================================

  r10	    0

  r11	    saved ar.pfs (a user-level value)

  r15	    system call number

  r16	    "current" task pointer (in normal kernel-mode, this is in r13)

  r32-r39   system call arguments

  b6	    return address (a user-level value)

  ar.pfs    previous frame-state (a user-level value)

  PSR.be    cleared to zero (i.e., little-endian byte order is in effect)

  -         all other registers may contain values passed in from user-mode

  ========= ===============================================================

** Required machine state on exit to fsyscall handler:

Required machine state on exit to fsyscall handler

--------------------------------------------------

 - r11	  = saved ar.pfs (as passed into the fsyscall handler)

 - r15	  = system call number (as passed into the fsyscall handler)

 - r32-r39 = system call arguments (as passed into the fsyscall handler)

 - b6	  = return address (as passed into the fsyscall handler)

 - ar.pfs = previous frame-state (as passed into the fsyscall handler)

  ========= ===========================================================

  r11	    saved ar.pfs (as passed into the fsyscall handler)

  r15	    system call number (as passed into the fsyscall handler)

  r32-r39   system call arguments (as passed into the fsyscall handler)

  b6	    return address (as passed into the fsyscall handler)

  ar.pfs    previous frame-state (as passed into the fsyscall handler)

  ========= ===========================================================

Fsyscall handlers can execute with very little overhead, but with that

speed comes a set of restrictions:

 o Fsyscall-handlers MUST check for any pending work in the flags

 * Fsyscall-handlers MUST check for any pending work in the flags

   member of the thread-info structure and if any of the

   TIF_ALLWORK_MASK flags are set, the handler needs to fall back on

   doing a full system call (by calling fsys_fallback_syscall).

 o Fsyscall-handlers MUST preserve incoming arguments (r32-r39, r11,

 * Fsyscall-handlers MUST preserve incoming arguments (r32-r39, r11,

   r15, b6, and ar.pfs) because they will be needed in case of a

   system call restart.  Of course, all "preserved" registers also

   must be preserved, in accordance to the normal calling conventions.

 o Fsyscall-handlers MUST check argument registers for containing a

 * Fsyscall-handlers MUST check argument registers for containing a

   NaT value before using them in any way that could trigger a

   NaT-consumption fault.  If a system call argument is found to

   contain a NaT value, an fsyscall-handler may return immediately

   with r8=EINVAL, r10=-1.

 o Fsyscall-handlers MUST NOT use the "alloc" instruction or perform

 * Fsyscall-handlers MUST NOT use the "alloc" instruction or perform

   any other operation that would trigger mandatory RSE

   (register-stack engine) traffic.

 o Fsyscall-handlers MUST NOT write to any stacked registers because

 * Fsyscall-handlers MUST NOT write to any stacked registers because

   it is not safe to assume that user-level called a handler with the

   proper number of arguments.

 o Fsyscall-handlers need to be careful when accessing per-CPU variables:

 * Fsyscall-handlers need to be careful when accessing per-CPU variables:

   unless proper safe-guards are taken (e.g., interruptions are avoided),

   execution may be pre-empted and resumed on another CPU at any given

   time.

 o Fsyscall-handlers must be careful not to leak sensitive kernel'

 * Fsyscall-handlers must be careful not to leak sensitive kernel'

   information back to user-level.  In particular, before returning to

   user-level, care needs to be taken to clear any scratch registers

   that could contain sensitive information (note that the current

   task pointer is not considered sensitive: it's already exposed

   through ar.k6).

 o Fsyscall-handlers MUST NOT access user-memory without first

 * Fsyscall-handlers MUST NOT access user-memory without first

   validating access-permission (this can be done typically via

   probe.r.fault and/or probe.w.fault) and without guarding against

   memory access exceptions (this can be done with the EX() macros

semantics), but there is also a lot of flexibility in handling more

complicated cases.

* Signal handling

Signal handling

===============

The delivery of (asynchronous) signals must be delayed until fsys-mode

is exited.  This is accomplished with the help of the lower-privilege

occur.  The trap handler clears PSR.lp again and returns immediately.

The kernel exit path then checks for and delivers any pending signals.

* PSR Handling

PSR Handling

============

The "epc" instruction doesn't change the contents of PSR at all.  This

is in contrast to a regular interruption, which clears almost all

work as expected.  The following discussion describes how each PSR bit

is handled.

======= =======================================================================

PSR.be	Cleared when entering fsys-mode.  A srlz.d instruction is used

	to ensure the CPU is in little-endian mode before the first

	load/store instruction is executed.  PSR.be is normally NOT

PSR.di	Unchanged.

PSR.si	Unchanged.

PSR.db	Unchanged.  The kernel prevents user-level from setting a hardware

	breakpoint that triggers at any privilege level other than 3 (user-mode).

	breakpoint that triggers at any privilege level other than

	3 (user-mode).

PSR.lp	Unchanged.

PSR.tb	Lazy redirect.  If a taken-branch trap occurs while in

	fsys-mode, the trap-handler modifies the saved machine state

PSR.bn	Unchanged.  Note: fsys-mode handlers may clear the bit, if needed.

	Doing so requires clearing PSR.i and PSR.ic as well.

PSR.ia	Unchanged.  Note: the ia64 linux kernel never sets this bit.

======= =======================================================================

* Using fast system calls

Using fast system calls

=======================

To use fast system calls, userspace applications need simply call

__kernel_syscall_via_epc().  For example

-- example fgettimeofday() call --

-- fgettimeofday.S --

::

  #include <asm/asmmacro.h>

  GLOBAL_ENTRY(fgettimeofday)

In reality, getting the gate address is accomplished by two extra

values passed via the ELF auxiliary vector (include/asm-ia64/elf.h)

 o AT_SYSINFO : is the address of __kernel_syscall_via_epc()

 o AT_SYSINFO_EHDR : is the address of the kernel gate ELF DSO

 * AT_SYSINFO : is the address of __kernel_syscall_via_epc()

 * AT_SYSINFO_EHDR : is the address of the kernel gate ELF DSO

The ELF DSO is a pre-linked library that is mapped in by the kernel at

the gate page.  It is a proper ELF shared object so, with a dynamic

        Linux kernel release 2.4.xx for the IA-64 Platform

===========================================

Linux kernel release for the IA-64 Platform

===========================================

   These are the release notes for Linux version 2.4 for IA-64

   These are the release notes for Linux since version 2.4 for IA-64

   platform.  This document provides information specific to IA-64

   ONLY, to get additional information about the Linux kernel also

   read the original Linux README provided with the kernel.

INSTALLING the kernel:

Installing the Kernel

=====================

 - IA-64 kernel installation is the same as the other platforms, see

   original README for details.

SOFTWARE REQUIREMENTS

Software Requirements

=====================

   Compiling and running this kernel requires an IA-64 compliant GCC

   compiler.  And various software packages also compiled with an

   IA-64 compliant GCC compiler.

CONFIGURING the kernel:

Configuring the Kernel

======================

   Configuration is the same, see original README for details.

COMPILING the kernel:

Compiling the Kernel:

 - Compiling this kernel doesn't differ from other platform so read

   the original README for details BUT make sure you have an IA-64

   compliant GCC compiler.

IA-64 SPECIFICS

IA-64 Specifics

===============

 - General issues:

    o Hardly any performance tuning has been done. Obvious targets

    * Hardly any performance tuning has been done. Obvious targets

      include the library routines (IP checksum, etc.). Less

      obvious targets include making sure we don't flush the TLB

      needlessly, etc.

    o SMP locks cleanup/optimization

    * SMP locks cleanup/optimization

    o IA32 support.  Currently experimental.  It mostly works.

    * IA32 support.  Currently experimental.  It mostly works.