Linux-2.6.12-rc2
Initial git repository build. I'm not bothering with the full history,
even though we have it. We can create a separate "historical" git
archive of that later if we want to, and in the meantime it's about
3.2GB when imported into git - space that would just make the early
git days unnecessarily complicated, when we don't have a lot of good
infrastructure for it.
Let it rip!
diff --git a/Documentation/powerpc/00-INDEX b/Documentation/powerpc/00-INDEX
new file mode 100644
index 0000000..e7bea0a
--- /dev/null
+++ b/Documentation/powerpc/00-INDEX
@@ -0,0 +1,20 @@
+Index of files in Documentation/powerpc. If you think something about
+Linux/PPC needs an entry here, needs correction or you've written one
+please mail me.
+ Cort Dougan (cort@fsmlabs.com)
+
+00-INDEX
+ - this file
+cpu_features.txt
+ - info on how we support a variety of CPUs with minimal compile-time
+ options.
+ppc_htab.txt
+ - info about the Linux/PPC /proc/ppc_htab entry
+smp.txt
+ - use and state info about Linux/PPC on MP machines
+SBC8260_memory_mapping.txt
+ - EST SBC8260 board info
+sound.txt
+ - info on sound support under Linux/PPC
+zImage_layout.txt
+ - info on the kernel images for Linux/PPC
diff --git a/Documentation/powerpc/SBC8260_memory_mapping.txt b/Documentation/powerpc/SBC8260_memory_mapping.txt
new file mode 100644
index 0000000..e6e9ee0
--- /dev/null
+++ b/Documentation/powerpc/SBC8260_memory_mapping.txt
@@ -0,0 +1,197 @@
+Please mail me (Jon Diekema, diekema_jon@si.com or diekema@cideas.com)
+if you have questions, comments or corrections.
+
+ * EST SBC8260 Linux memory mapping rules
+
+ http://www.estc.com/
+ http://www.estc.com/products/boards/SBC8260-8240_ds.html
+
+ Initial conditions:
+ -------------------
+
+ Tasks that need to be perform by the boot ROM before control is
+ transferred to zImage (compressed Linux kernel):
+
+ - Define the IMMR to 0xf0000000
+
+ - Initialize the memory controller so that RAM is available at
+ physical address 0x00000000. On the SBC8260 is this 16M (64M)
+ SDRAM.
+
+ - The boot ROM should only clear the RAM that it is using.
+
+ The reason for doing this is to enhances the chances of a
+ successful post mortem on a Linux panic. One of the first
+ items to examine is the 16k (LOG_BUF_LEN) circular console
+ buffer called log_buf which is defined in kernel/printk.c.
+
+ - To enhance boot ROM performance, the I-cache can be enabled.
+
+ Date: Mon, 22 May 2000 14:21:10 -0700
+ From: Neil Russell <caret@c-side.com>
+
+ LiMon (LInux MONitor) runs with and starts Linux with MMU
+ off, I-cache enabled, D-cache disabled. The I-cache doesn't
+ need hints from the MMU to work correctly as the D-cache
+ does. No D-cache means no special code to handle devices in
+ the presence of cache (no snooping, etc). The use of the
+ I-cache means that the monitor can run acceptably fast
+ directly from ROM, rather than having to copy it to RAM.
+
+ - Build the board information structure (see
+ include/asm-ppc/est8260.h for its definition)
+
+ - The compressed Linux kernel (zImage) contains a bootstrap loader
+ that is position independent; you can load it into any RAM,
+ ROM or FLASH memory address >= 0x00500000 (above 5 MB), or
+ at its link address of 0x00400000 (4 MB).
+
+ Note: If zImage is loaded at its link address of 0x00400000 (4 MB),
+ then zImage will skip the step of moving itself to
+ its link address.
+
+ - Load R3 with the address of the board information structure
+
+ - Transfer control to zImage
+
+ - The Linux console port is SMC1, and the baud rate is controlled
+ from the bi_baudrate field of the board information structure.
+ On thing to keep in mind when picking the baud rate, is that
+ there is no flow control on the SMC ports. I would stick
+ with something safe and standard like 19200.
+
+ On the EST SBC8260, the SMC1 port is on the COM1 connector of
+ the board.
+
+
+ EST SBC8260 defaults:
+ ---------------------
+
+ Chip
+ Memory Sel Bus Use
+ --------------------- --- --- ----------------------------------
+ 0x00000000-0x03FFFFFF CS2 60x (16M or 64M)/64M SDRAM
+ 0x04000000-0x04FFFFFF CS4 local 4M/16M SDRAM (soldered to the board)
+ 0x21000000-0x21000000 CS7 60x 1B/64K Flash present detect (from the flash SIMM)
+ 0x21000001-0x21000001 CS7 60x 1B/64K Switches (read) and LEDs (write)
+ 0x22000000-0x2200FFFF CS5 60x 8K/64K EEPROM
+ 0xFC000000-0xFCFFFFFF CS6 60x 2M/16M flash (8 bits wide, soldered to the board)
+ 0xFE000000-0xFFFFFFFF CS0 60x 4M/16M flash (SIMM)
+
+ Notes:
+ ------
+
+ - The chip selects can map 32K blocks and up (powers of 2)
+
+ - The SDRAM machine can handled up to 128Mbytes per chip select
+
+ - Linux uses the 60x bus memory (the SDRAM DIMM) for the
+ communications buffers.
+
+ - BATs can map 128K-256Mbytes each. There are four data BATs and
+ four instruction BATs. Generally the data and instruction BATs
+ are mapped the same.
+
+ - The IMMR must be set above the kernel virtual memory addresses,
+ which start at 0xC0000000. Otherwise, the kernel may crash as
+ soon as you start any threads or processes due to VM collisions
+ in the kernel or user process space.
+
+
+ Details from Dan Malek <dan_malek@mvista.com> on 10/29/1999:
+
+ The user application virtual space consumes the first 2 Gbytes
+ (0x00000000 to 0x7FFFFFFF). The kernel virtual text starts at
+ 0xC0000000, with data following. There is a "protection hole"
+ between the end of kernel data and the start of the kernel
+ dynamically allocated space, but this space is still within
+ 0xCxxxxxxx.
+
+ Obviously the kernel can't map any physical addresses 1:1 in
+ these ranges.
+
+
+ Details from Dan Malek <dan_malek@mvista.com> on 5/19/2000:
+
+ During the early kernel initialization, the kernel virtual
+ memory allocator is not operational. Prior to this KVM
+ initialization, we choose to map virtual to physical addresses
+ 1:1. That is, the kernel virtual address exactly matches the
+ physical address on the bus. These mappings are typically done
+ in arch/ppc/kernel/head.S, or arch/ppc/mm/init.c. Only
+ absolutely necessary mappings should be done at this time, for
+ example board control registers or a serial uart. Normal device
+ driver initialization should map resources later when necessary.
+
+ Although platform dependent, and certainly the case for embedded
+ 8xx, traditionally memory is mapped at physical address zero,
+ and I/O devices above physical address 0x80000000. The lowest
+ and highest (above 0xf0000000) I/O addresses are traditionally
+ used for devices or registers we need to map during kernel
+ initialization and prior to KVM operation. For this reason,
+ and since it followed prior PowerPC platform examples, I chose
+ to map the embedded 8xx kernel to the 0xc0000000 virtual address.
+ This way, we can enable the MMU to map the kernel for proper
+ operation, and still map a few windows before the KVM is operational.
+
+ On some systems, you could possibly run the kernel at the
+ 0x80000000 or any other virtual address. It just depends upon
+ mapping that must be done prior to KVM operational. You can never
+ map devices or kernel spaces that overlap with the user virtual
+ space. This is why default IMMR mapping used by most BDM tools
+ won't work. They put the IMMR at something like 0x10000000 or
+ 0x02000000 for example. You simply can't map these addresses early
+ in the kernel, and continue proper system operation.
+
+ The embedded 8xx/82xx kernel is mature enough that all you should
+ need to do is map the IMMR someplace at or above 0xf0000000 and it
+ should boot far enough to get serial console messages and KGDB
+ connected on any platform. There are lots of other subtle memory
+ management design features that you simply don't need to worry
+ about. If you are changing functions related to MMU initialization,
+ you are likely breaking things that are known to work and are
+ heading down a path of disaster and frustration. Your changes
+ should be to make the flexibility of the processor fit Linux,
+ not force arbitrary and non-workable memory mappings into Linux.
+
+ - You don't want to change KERNELLOAD or KERNELBASE, otherwise the
+ virtual memory and MMU code will get confused.
+
+ arch/ppc/Makefile:KERNELLOAD = 0xc0000000
+
+ include/asm-ppc/page.h:#define PAGE_OFFSET 0xc0000000
+ include/asm-ppc/page.h:#define KERNELBASE PAGE_OFFSET
+
+ - RAM is at physical address 0x00000000, and gets mapped to
+ virtual address 0xC0000000 for the kernel.
+
+
+ Physical addresses used by the Linux kernel:
+ --------------------------------------------
+
+ 0x00000000-0x3FFFFFFF 1GB reserved for RAM
+ 0xF0000000-0xF001FFFF 128K IMMR 64K used for dual port memory,
+ 64K for 8260 registers
+
+
+ Logical addresses used by the Linux kernel:
+ -------------------------------------------
+
+ 0xF0000000-0xFFFFFFFF 256M BAT0 (IMMR: dual port RAM, registers)
+ 0xE0000000-0xEFFFFFFF 256M BAT1 (I/O space for custom boards)
+ 0xC0000000-0xCFFFFFFF 256M BAT2 (RAM)
+ 0xD0000000-0xDFFFFFFF 256M BAT3 (if RAM > 256MByte)
+
+
+ EST SBC8260 Linux mapping:
+ --------------------------
+
+ DBAT0, IBAT0, cache inhibited:
+
+ Chip
+ Memory Sel Use
+ --------------------- --- ---------------------------------
+ 0xF0000000-0xF001FFFF n/a IMMR: dual port RAM, registers
+
+ DBAT1, IBAT1, cache inhibited:
+
diff --git a/Documentation/powerpc/cpu_features.txt b/Documentation/powerpc/cpu_features.txt
new file mode 100644
index 0000000..4727398
--- /dev/null
+++ b/Documentation/powerpc/cpu_features.txt
@@ -0,0 +1,56 @@
+Hollis Blanchard <hollis@austin.ibm.com>
+5 Jun 2002
+
+This document describes the system (including self-modifying code) used in the
+PPC Linux kernel to support a variety of PowerPC CPUs without requiring
+compile-time selection.
+
+Early in the boot process the ppc32 kernel detects the current CPU type and
+chooses a set of features accordingly. Some examples include Altivec support,
+split instruction and data caches, and if the CPU supports the DOZE and NAP
+sleep modes.
+
+Detection of the feature set is simple. A list of processors can be found in
+arch/ppc/kernel/cputable.c. The PVR register is masked and compared with each
+value in the list. If a match is found, the cpu_features of cur_cpu_spec is
+assigned to the feature bitmask for this processor and a __setup_cpu function
+is called.
+
+C code may test 'cur_cpu_spec[smp_processor_id()]->cpu_features' for a
+particular feature bit. This is done in quite a few places, for example
+in ppc_setup_l2cr().
+
+Implementing cpufeatures in assembly is a little more involved. There are
+several paths that are performance-critical and would suffer if an array
+index, structure dereference, and conditional branch were added. To avoid the
+performance penalty but still allow for runtime (rather than compile-time) CPU
+selection, unused code is replaced by 'nop' instructions. This nop'ing is
+based on CPU 0's capabilities, so a multi-processor system with non-identical
+processors will not work (but such a system would likely have other problems
+anyways).
+
+After detecting the processor type, the kernel patches out sections of code
+that shouldn't be used by writing nop's over it. Using cpufeatures requires
+just 2 macros (found in include/asm-ppc/cputable.h), as seen in head.S
+transfer_to_handler:
+
+ #ifdef CONFIG_ALTIVEC
+ BEGIN_FTR_SECTION
+ mfspr r22,SPRN_VRSAVE /* if G4, save vrsave register value */
+ stw r22,THREAD_VRSAVE(r23)
+ END_FTR_SECTION_IFSET(CPU_FTR_ALTIVEC)
+ #endif /* CONFIG_ALTIVEC */
+
+If CPU 0 supports Altivec, the code is left untouched. If it doesn't, both
+instructions are replaced with nop's.
+
+The END_FTR_SECTION macro has two simpler variations: END_FTR_SECTION_IFSET
+and END_FTR_SECTION_IFCLR. These simply test if a flag is set (in
+cur_cpu_spec[0]->cpu_features) or is cleared, respectively. These two macros
+should be used in the majority of cases.
+
+The END_FTR_SECTION macros are implemented by storing information about this
+code in the '__ftr_fixup' ELF section. When do_cpu_ftr_fixups
+(arch/ppc/kernel/misc.S) is invoked, it will iterate over the records in
+__ftr_fixup, and if the required feature is not present it will loop writing
+nop's from each BEGIN_FTR_SECTION to END_FTR_SECTION.
diff --git a/Documentation/powerpc/eeh-pci-error-recovery.txt b/Documentation/powerpc/eeh-pci-error-recovery.txt
new file mode 100644
index 0000000..2bfe71b
--- /dev/null
+++ b/Documentation/powerpc/eeh-pci-error-recovery.txt
@@ -0,0 +1,332 @@
+
+
+ PCI Bus EEH Error Recovery
+ --------------------------
+ Linas Vepstas
+ <linas@austin.ibm.com>
+ 12 January 2005
+
+
+Overview:
+---------
+The IBM POWER-based pSeries and iSeries computers include PCI bus
+controller chips that have extended capabilities for detecting and
+reporting a large variety of PCI bus error conditions. These features
+go under the name of "EEH", for "Extended Error Handling". The EEH
+hardware features allow PCI bus errors to be cleared and a PCI
+card to be "rebooted", without also having to reboot the operating
+system.
+
+This is in contrast to traditional PCI error handling, where the
+PCI chip is wired directly to the CPU, and an error would cause
+a CPU machine-check/check-stop condition, halting the CPU entirely.
+Another "traditional" technique is to ignore such errors, which
+can lead to data corruption, both of user data or of kernel data,
+hung/unresponsive adapters, or system crashes/lockups. Thus,
+the idea behind EEH is that the operating system can become more
+reliable and robust by protecting it from PCI errors, and giving
+the OS the ability to "reboot"/recover individual PCI devices.
+
+Future systems from other vendors, based on the PCI-E specification,
+may contain similar features.
+
+
+Causes of EEH Errors
+--------------------
+EEH was originally designed to guard against hardware failure, such
+as PCI cards dying from heat, humidity, dust, vibration and bad
+electrical connections. The vast majority of EEH errors seen in
+"real life" are due to eithr poorly seated PCI cards, or,
+unfortunately quite commonly, due device driver bugs, device firmware
+bugs, and sometimes PCI card hardware bugs.
+
+The most common software bug, is one that causes the device to
+attempt to DMA to a location in system memory that has not been
+reserved for DMA access for that card. This is a powerful feature,
+as it prevents what; otherwise, would have been silent memory
+corruption caused by the bad DMA. A number of device driver
+bugs have been found and fixed in this way over the past few
+years. Other possible causes of EEH errors include data or
+address line parity errors (for example, due to poor electrical
+connectivity due to a poorly seated card), and PCI-X split-completion
+errors (due to software, device firmware, or device PCI hardware bugs).
+The vast majority of "true hardware failures" can be cured by
+physically removing and re-seating the PCI card.
+
+
+Detection and Recovery
+----------------------
+In the following discussion, a generic overview of how to detect
+and recover from EEH errors will be presented. This is followed
+by an overview of how the current implementation in the Linux
+kernel does it. The actual implementation is subject to change,
+and some of the finer points are still being debated. These
+may in turn be swayed if or when other architectures implement
+similar functionality.
+
+When a PCI Host Bridge (PHB, the bus controller connecting the
+PCI bus to the system CPU electronics complex) detects a PCI error
+condition, it will "isolate" the affected PCI card. Isolation
+will block all writes (either to the card from the system, or
+from the card to the system), and it will cause all reads to
+return all-ff's (0xff, 0xffff, 0xffffffff for 8/16/32-bit reads).
+This value was chosen because it is the same value you would
+get if the device was physically unplugged from the slot.
+This includes access to PCI memory, I/O space, and PCI config
+space. Interrupts; however, will continued to be delivered.
+
+Detection and recovery are performed with the aid of ppc64
+firmware. The programming interfaces in the Linux kernel
+into the firmware are referred to as RTAS (Run-Time Abstraction
+Services). The Linux kernel does not (should not) access
+the EEH function in the PCI chipsets directly, primarily because
+there are a number of different chipsets out there, each with
+different interfaces and quirks. The firmware provides a
+uniform abstraction layer that will work with all pSeries
+and iSeries hardware (and be forwards-compatible).
+
+If the OS or device driver suspects that a PCI slot has been
+EEH-isolated, there is a firmware call it can make to determine if
+this is the case. If so, then the device driver should put itself
+into a consistent state (given that it won't be able to complete any
+pending work) and start recovery of the card. Recovery normally
+would consist of reseting the PCI device (holding the PCI #RST
+line high for two seconds), followed by setting up the device
+config space (the base address registers (BAR's), latency timer,
+cache line size, interrupt line, and so on). This is followed by a
+reinitialization of the device driver. In a worst-case scenario,
+the power to the card can be toggled, at least on hot-plug-capable
+slots. In principle, layers far above the device driver probably
+do not need to know that the PCI card has been "rebooted" in this
+way; ideally, there should be at most a pause in Ethernet/disk/USB
+I/O while the card is being reset.
+
+If the card cannot be recovered after three or four resets, the
+kernel/device driver should assume the worst-case scenario, that the
+card has died completely, and report this error to the sysadmin.
+In addition, error messages are reported through RTAS and also through
+syslogd (/var/log/messages) to alert the sysadmin of PCI resets.
+The correct way to deal with failed adapters is to use the standard
+PCI hotplug tools to remove and replace the dead card.
+
+
+Current PPC64 Linux EEH Implementation
+--------------------------------------
+At this time, a generic EEH recovery mechanism has been implemented,
+so that individual device drivers do not need to be modified to support
+EEH recovery. This generic mechanism piggy-backs on the PCI hotplug
+infrastructure, and percolates events up through the hotplug/udev
+infrastructure. Followiing is a detailed description of how this is
+accomplished.
+
+EEH must be enabled in the PHB's very early during the boot process,
+and if a PCI slot is hot-plugged. The former is performed by
+eeh_init() in arch/ppc64/kernel/eeh.c, and the later by
+drivers/pci/hotplug/pSeries_pci.c calling in to the eeh.c code.
+EEH must be enabled before a PCI scan of the device can proceed.
+Current Power5 hardware will not work unless EEH is enabled;
+although older Power4 can run with it disabled. Effectively,
+EEH can no longer be turned off. PCI devices *must* be
+registered with the EEH code; the EEH code needs to know about
+the I/O address ranges of the PCI device in order to detect an
+error. Given an arbitrary address, the routine
+pci_get_device_by_addr() will find the pci device associated
+with that address (if any).
+
+The default include/asm-ppc64/io.h macros readb(), inb(), insb(),
+etc. include a check to see if the the i/o read returned all-0xff's.
+If so, these make a call to eeh_dn_check_failure(), which in turn
+asks the firmware if the all-ff's value is the sign of a true EEH
+error. If it is not, processing continues as normal. The grand
+total number of these false alarms or "false positives" can be
+seen in /proc/ppc64/eeh (subject to change). Normally, almost
+all of these occur during boot, when the PCI bus is scanned, where
+a large number of 0xff reads are part of the bus scan procedure.
+
+If a frozen slot is detected, code in arch/ppc64/kernel/eeh.c will
+print a stack trace to syslog (/var/log/messages). This stack trace
+has proven to be very useful to device-driver authors for finding
+out at what point the EEH error was detected, as the error itself
+usually occurs slightly beforehand.
+
+Next, it uses the Linux kernel notifier chain/work queue mechanism to
+allow any interested parties to find out about the failure. Device
+drivers, or other parts of the kernel, can use
+eeh_register_notifier(struct notifier_block *) to find out about EEH
+events. The event will include a pointer to the pci device, the
+device node and some state info. Receivers of the event can "do as
+they wish"; the default handler will be described further in this
+section.
+
+To assist in the recovery of the device, eeh.c exports the
+following functions:
+
+rtas_set_slot_reset() -- assert the PCI #RST line for 1/8th of a second
+rtas_configure_bridge() -- ask firmware to configure any PCI bridges
+ located topologically under the pci slot.
+eeh_save_bars() and eeh_restore_bars(): save and restore the PCI
+ config-space info for a device and any devices under it.
+
+
+A handler for the EEH notifier_block events is implemented in
+drivers/pci/hotplug/pSeries_pci.c, called handle_eeh_events().
+It saves the device BAR's and then calls rpaphp_unconfig_pci_adapter().
+This last call causes the device driver for the card to be stopped,
+which causes hotplug events to go out to user space. This triggers
+user-space scripts that might issue commands such as "ifdown eth0"
+for ethernet cards, and so on. This handler then sleeps for 5 seconds,
+hoping to give the user-space scripts enough time to complete.
+It then resets the PCI card, reconfigures the device BAR's, and
+any bridges underneath. It then calls rpaphp_enable_pci_slot(),
+which restarts the device driver and triggers more user-space
+events (for example, calling "ifup eth0" for ethernet cards).
+
+
+Device Shutdown and User-Space Events
+-------------------------------------
+This section documents what happens when a pci slot is unconfigured,
+focusing on how the device driver gets shut down, and on how the
+events get delivered to user-space scripts.
+
+Following is an example sequence of events that cause a device driver
+close function to be called during the first phase of an EEH reset.
+The following sequence is an example of the pcnet32 device driver.
+
+ rpa_php_unconfig_pci_adapter (struct slot *) // in rpaphp_pci.c
+ {
+ calls
+ pci_remove_bus_device (struct pci_dev *) // in /drivers/pci/remove.c
+ {
+ calls
+ pci_destroy_dev (struct pci_dev *)
+ {
+ calls
+ device_unregister (&dev->dev) // in /drivers/base/core.c
+ {
+ calls
+ device_del (struct device *)
+ {
+ calls
+ bus_remove_device() // in /drivers/base/bus.c
+ {
+ calls
+ device_release_driver()
+ {
+ calls
+ struct device_driver->remove() which is just
+ pci_device_remove() // in /drivers/pci/pci_driver.c
+ {
+ calls
+ struct pci_driver->remove() which is just
+ pcnet32_remove_one() // in /drivers/net/pcnet32.c
+ {
+ calls
+ unregister_netdev() // in /net/core/dev.c
+ {
+ calls
+ dev_close() // in /net/core/dev.c
+ {
+ calls dev->stop();
+ which is just pcnet32_close() // in pcnet32.c
+ {
+ which does what you wanted
+ to stop the device
+ }
+ }
+ }
+ which
+ frees pcnet32 device driver memory
+ }
+ }}}}}}
+
+
+ in drivers/pci/pci_driver.c,
+ struct device_driver->remove() is just pci_device_remove()
+ which calls struct pci_driver->remove() which is pcnet32_remove_one()
+ which calls unregister_netdev() (in net/core/dev.c)
+ which calls dev_close() (in net/core/dev.c)
+ which calls dev->stop() which is pcnet32_close()
+ which then does the appropriate shutdown.
+
+---
+Following is the analogous stack trace for events sent to user-space
+when the pci device is unconfigured.
+
+rpa_php_unconfig_pci_adapter() { // in rpaphp_pci.c
+ calls
+ pci_remove_bus_device (struct pci_dev *) { // in /drivers/pci/remove.c
+ calls
+ pci_destroy_dev (struct pci_dev *) {
+ calls
+ device_unregister (&dev->dev) { // in /drivers/base/core.c
+ calls
+ device_del(struct device * dev) { // in /drivers/base/core.c
+ calls
+ kobject_del() { //in /libs/kobject.c
+ calls
+ kobject_hotplug() { // in /libs/kobject.c
+ calls
+ kset_hotplug() { // in /lib/kobject.c
+ calls
+ kset->hotplug_ops->hotplug() which is really just
+ a call to
+ dev_hotplug() { // in /drivers/base/core.c
+ calls
+ dev->bus->hotplug() which is really just a call to
+ pci_hotplug () { // in drivers/pci/hotplug.c
+ which prints device name, etc....
+ }
+ }
+ then kset_hotplug() calls
+ call_usermodehelper () with
+ argv[0]=hotplug_path[] which is "/sbin/hotplug"
+ --> event to userspace,
+ }
+ }
+ kobject_del() then calls sysfs_remove_dir(), which would
+ trigger any user-space daemon that was watching /sysfs,
+ and notice the delete event.
+
+
+Pro's and Con's of the Current Design
+-------------------------------------
+There are several issues with the current EEH software recovery design,
+which may be addressed in future revisions. But first, note that the
+big plus of the current design is that no changes need to be made to
+individual device drivers, so that the current design throws a wide net.
+The biggest negative of the design is that it potentially disturbs
+network daemons and file systems that didn't need to be disturbed.
+
+-- A minor complaint is that resetting the network card causes
+ user-space back-to-back ifdown/ifup burps that potentially disturb
+ network daemons, that didn't need to even know that the pci
+ card was being rebooted.
+
+-- A more serious concern is that the same reset, for SCSI devices,
+ causes havoc to mounted file systems. Scripts cannot post-facto
+ unmount a file system without flushing pending buffers, but this
+ is impossible, because I/O has already been stopped. Thus,
+ ideally, the reset should happen at or below the block layer,
+ so that the file systems are not disturbed.
+
+ Reiserfs does not tolerate errors returned from the block device.
+ Ext3fs seems to be tolerant, retrying reads/writes until it does
+ succeed. Both have been only lightly tested in this scenario.
+
+ The SCSI-generic subsystem already has built-in code for performing
+ SCSI device resets, SCSI bus resets, and SCSI host-bus-adapter
+ (HBA) resets. These are cascaded into a chain of attempted
+ resets if a SCSI command fails. These are completely hidden
+ from the block layer. It would be very natural to add an EEH
+ reset into this chain of events.
+
+-- If a SCSI error occurs for the root device, all is lost unless
+ the sysadmin had the foresight to run /bin, /sbin, /etc, /var
+ and so on, out of ramdisk/tmpfs.
+
+
+Conclusions
+-----------
+There's forward progress ...
+
+
diff --git a/Documentation/powerpc/hvcs.txt b/Documentation/powerpc/hvcs.txt
new file mode 100644
index 0000000..c0a62e1
--- /dev/null
+++ b/Documentation/powerpc/hvcs.txt
@@ -0,0 +1,567 @@
+===========================================================================
+ HVCS
+ IBM "Hypervisor Virtual Console Server" Installation Guide
+ for Linux Kernel 2.6.4+
+ Copyright (C) 2004 IBM Corporation
+
+===========================================================================
+NOTE:Eight space tabs are the optimum editor setting for reading this file.
+===========================================================================
+
+ Author(s) : Ryan S. Arnold <rsa@us.ibm.com>
+ Date Created: March, 02, 2004
+ Last Changed: August, 24, 2004
+
+---------------------------------------------------------------------------
+Table of contents:
+
+ 1. Driver Introduction:
+ 2. System Requirements
+ 3. Build Options:
+ 3.1 Built-in:
+ 3.2 Module:
+ 4. Installation:
+ 5. Connection:
+ 6. Disconnection:
+ 7. Configuration:
+ 8. Questions & Answers:
+ 9. Reporting Bugs:
+
+---------------------------------------------------------------------------
+1. Driver Introduction:
+
+This is the device driver for the IBM Hypervisor Virtual Console Server,
+"hvcs". The IBM hvcs provides a tty driver interface to allow Linux user
+space applications access to the system consoles of logically partitioned
+operating systems (Linux and AIX) running on the same partitioned Power5
+ppc64 system. Physical hardware consoles per partition are not practical
+on this hardware so system consoles are accessed by this driver using
+firmware interfaces to virtual terminal devices.
+
+---------------------------------------------------------------------------
+2. System Requirements:
+
+This device driver was written using 2.6.4 Linux kernel APIs and will only
+build and run on kernels of this version or later.
+
+This driver was written to operate solely on IBM Power5 ppc64 hardware
+though some care was taken to abstract the architecture dependent firmware
+calls from the driver code.
+
+Sysfs must be mounted on the system so that the user can determine which
+major and minor numbers are associated with each vty-server. Directions
+for sysfs mounting are outside the scope of this document.
+
+---------------------------------------------------------------------------
+3. Build Options:
+
+The hvcs driver registers itself as a tty driver. The tty layer
+dynamically allocates a block of major and minor numbers in a quantity
+requested by the registering driver. The hvcs driver asks the tty layer
+for 64 of these major/minor numbers by default to use for hvcs device node
+entries.
+
+If the default number of device entries is adequate then this driver can be
+built into the kernel. If not, the default can be over-ridden by inserting
+the driver as a module with insmod parameters.
+
+---------------------------------------------------------------------------
+3.1 Built-in:
+
+The following menuconfig example demonstrates selecting to build this
+driver into the kernel.
+
+ Device Drivers --->
+ Character devices --->
+ <*> IBM Hypervisor Virtual Console Server Support
+
+Begin the kernel make process.
+
+---------------------------------------------------------------------------
+3.2 Module:
+
+The following menuconfig example demonstrates selecting to build this
+driver as a kernel module.
+
+ Device Drivers --->
+ Character devices --->
+ <M> IBM Hypervisor Virtual Console Server Support
+
+The make process will build the following kernel modules:
+
+ hvcs.ko
+ hvcserver.ko
+
+To insert the module with the default allocation execute the following
+commands in the order they appear:
+
+ insmod hvcserver.ko
+ insmod hvcs.ko
+
+The hvcserver module contains architecture specific firmware calls and must
+be inserted first, otherwise the hvcs module will not find some of the
+symbols it expects.
+
+To override the default use an insmod parameter as follows (requesting 4
+tty devices as an example):
+
+ insmod hvcs.ko hvcs_parm_num_devs=4
+
+There is a maximum number of dev entries that can be specified on insmod.
+We think that 1024 is currently a decent maximum number of server adapters
+to allow. This can always be changed by modifying the constant in the
+source file before building.
+
+NOTE: The length of time it takes to insmod the driver seems to be related
+to the number of tty interfaces the registering driver requests.
+
+In order to remove the driver module execute the following command:
+
+ rmmod hvcs.ko
+
+The recommended method for installing hvcs as a module is to use depmod to
+build a current modules.dep file in /lib/modules/`uname -r` and then
+execute:
+
+modprobe hvcs hvcs_parm_num_devs=4
+
+The modules.dep file indicates that hvcserver.ko needs to be inserted
+before hvcs.ko and modprobe uses this file to smartly insert the modules in
+the proper order.
+
+The following modprobe command is used to remove hvcs and hvcserver in the
+proper order:
+
+modprobe -r hvcs
+
+---------------------------------------------------------------------------
+4. Installation:
+
+The tty layer creates sysfs entries which contain the major and minor
+numbers allocated for the hvcs driver. The following snippet of "tree"
+output of the sysfs directory shows where these numbers are presented:
+
+ sys/
+ |-- *other sysfs base dirs*
+ |
+ |-- class
+ | |-- *other classes of devices*
+ | |
+ | `-- tty
+ | |-- *other tty devices*
+ | |
+ | |-- hvcs0
+ | | `-- dev
+ | |-- hvcs1
+ | | `-- dev
+ | |-- hvcs2
+ | | `-- dev
+ | |-- hvcs3
+ | | `-- dev
+ | |
+ | |-- *other tty devices*
+ |
+ |-- *other sysfs base dirs*
+
+For the above examples the following output is a result of cat'ing the
+"dev" entry in the hvcs directory:
+
+ Pow5:/sys/class/tty/hvcs0/ # cat dev
+ 254:0
+
+ Pow5:/sys/class/tty/hvcs1/ # cat dev
+ 254:1
+
+ Pow5:/sys/class/tty/hvcs2/ # cat dev
+ 254:2
+
+ Pow5:/sys/class/tty/hvcs3/ # cat dev
+ 254:3
+
+The output from reading the "dev" attribute is the char device major and
+minor numbers that the tty layer has allocated for this driver's use. Most
+systems running hvcs will already have the device entries created or udev
+will do it automatically.
+
+Given the example output above, to manually create a /dev/hvcs* node entry
+mknod can be used as follows:
+
+ mknod /dev/hvcs0 c 254 0
+ mknod /dev/hvcs1 c 254 1
+ mknod /dev/hvcs2 c 254 2
+ mknod /dev/hvcs3 c 254 3
+
+Using mknod to manually create the device entries makes these device nodes
+persistent. Once created they will exist prior to the driver insmod.
+
+Attempting to connect an application to /dev/hvcs* prior to insertion of
+the hvcs module will result in an error message similar to the following:
+
+ "/dev/hvcs*: No such device".
+
+NOTE: Just because there is a device node present doesn't mean that there
+is a vty-server device configured for that node.
+
+---------------------------------------------------------------------------
+5. Connection
+
+Since this driver controls devices that provide a tty interface a user can
+interact with the device node entries using any standard tty-interactive
+method (e.g. "cat", "dd", "echo"). The intent of this driver however, is
+to provide real time console interaction with a Linux partition's console,
+which requires the use of applications that provide bi-directional,
+interactive I/O with a tty device.
+
+Applications (e.g. "minicom" and "screen") that act as terminal emulators
+or perform terminal type control sequence conversion on the data being
+passed through them are NOT acceptable for providing interactive console
+I/O. These programs often emulate antiquated terminal types (vt100 and
+ANSI) and expect inbound data to take the form of one of these supported
+terminal types but they either do not convert, or do not _adequately_
+convert, outbound data into the terminal type of the terminal which invoked
+them (though screen makes an attempt and can apparently be configured with
+much termcap wrestling.)
+
+For this reason kermit and cu are two of the recommended applications for
+interacting with a Linux console via an hvcs device. These programs simply
+act as a conduit for data transfer to and from the tty device. They do not
+require inbound data to take the form of a particular terminal type, nor do
+they cook outbound data to a particular terminal type.
+
+In order to ensure proper functioning of console applications one must make
+sure that once connected to a /dev/hvcs console that the console's $TERM
+env variable is set to the exact terminal type of the terminal emulator
+used to launch the interactive I/O application. If one is using xterm and
+kermit to connect to /dev/hvcs0 when the console prompt becomes available
+one should "export TERM=xterm" on the console. This tells ncurses
+applications that are invoked from the console that they should output
+control sequences that xterm can understand.
+
+As a precautionary measure an hvcs user should always "exit" from their
+session before disconnecting an application such as kermit from the device
+node. If this is not done, the next user to connect to the console will
+continue using the previous user's logged in session which includes
+using the $TERM variable that the previous user supplied.
+
+Hotplug add and remove of vty-server adapters affects which /dev/hvcs* node
+is used to connect to each vty-server adapter. In order to determine which
+vty-server adapter is associated with which /dev/hvcs* node a special sysfs
+attribute has been added to each vty-server sysfs entry. This entry is
+called "index" and showing it reveals an integer that refers to the
+/dev/hvcs* entry to use to connect to that device. For instance cating the
+index attribute of vty-server adapter 30000004 shows the following.
+
+ Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat index
+ 2
+
+This index of '2' means that in order to connect to vty-server adapter
+30000004 the user should interact with /dev/hvcs2.
+
+It should be noted that due to the system hotplug I/O capabilities of a
+system the /dev/hvcs* entry that interacts with a particular vty-server
+adapter is not guarenteed to remain the same across system reboots. Look
+in the Q & A section for more on this issue.
+
+---------------------------------------------------------------------------
+6. Disconnection
+
+As a security feature to prevent the delivery of stale data to an
+unintended target the Power5 system firmware disables the fetching of data
+and discards that data when a connection between a vty-server and a vty has
+been severed. As an example, when a vty-server is immediately disconnected
+from a vty following output of data to the vty the vty adapter may not have
+enough time between when it received the data interrupt and when the
+connection was severed to fetch the data from firmware before the fetch is
+disabled by firmware.
+
+When hvcs is being used to serve consoles this behavior is not a huge issue
+because the adapter stays connected for large amounts of time following
+almost all data writes. When hvcs is being used as a tty conduit to tunnel
+data between two partitions [see Q & A below] this is a huge problem
+because the standard Linux behavior when cat'ing or dd'ing data to a device
+is to open the tty, send the data, and then close the tty. If this driver
+manually terminated vty-server connections on tty close this would close
+the vty-server and vty connection before the target vty has had a chance to
+fetch the data.
+
+Additionally, disconnecting a vty-server and vty only on module removal or
+adapter removal is impractical because other vty-servers in other
+partitions may require the usage of the target vty at any time.
+
+Due to this behavioral restriction disconnection of vty-servers from the
+connected vty is a manual procedure using a write to a sysfs attribute
+outlined below, on the other hand the initial vty-server connection to a
+vty is established automatically by this driver. Manual vty-server
+connection is never required.
+
+In order to terminate the connection between a vty-server and vty the
+"vterm_state" sysfs attribute within each vty-server's sysfs entry is used.
+Reading this attribute reveals the current connection state of the
+vty-server adapter. A zero means that the vty-server is not connected to a
+vty. A one indicates that a connection is active.
+
+Writing a '0' (zero) to the vterm_state attribute will disconnect the VTERM
+connection between the vty-server and target vty ONLY if the vterm_state
+previously read '1'. The write directive is ignored if the vterm_state
+read '0' or if any value other than '0' was written to the vterm_state
+attribute. The following example will show the method used for verifying
+the vty-server connection status and disconnecting a vty-server connection.
+
+ Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat vterm_state
+ 1
+
+ Pow5:/sys/bus/vio/drivers/hvcs/30000004 # echo 0 > vterm_state
+
+ Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat vterm_state
+ 0
+
+All vty-server connections are automatically terminated when the device is
+hotplug removed and when the module is removed.
+
+---------------------------------------------------------------------------
+7. Configuration
+
+Each vty-server has a sysfs entry in the /sys/devices/vio directory, which
+is symlinked in several other sysfs tree directories, notably under the
+hvcs driver entry, which looks like the following example:
+
+ Pow5:/sys/bus/vio/drivers/hvcs # ls
+ . .. 30000003 30000004 rescan
+
+By design, firmware notifies the hvcs driver of vty-server lifetimes and
+partner vty removals but not the addition of partner vtys. Since an HMC
+Super Admin can add partner info dynamically we have provided the hvcs
+driver sysfs directory with the "rescan" update attribute which will query
+firmware and update the partner info for all the vty-servers that this
+driver manages. Writing a '1' to the attribute triggers the update. An
+explicit example follows:
+
+ Pow5:/sys/bus/vio/drivers/hvcs # echo 1 > rescan
+
+Reading the attribute will indicate a state of '1' or '0'. A one indicates
+that an update is in process. A zero indicates that an update has
+completed or was never executed.
+
+Vty-server entries in this directory are a 32 bit partition unique unit
+address that is created by firmware. An example vty-server sysfs entry
+looks like the following:
+
+ Pow5:/sys/bus/vio/drivers/hvcs/30000004 # ls
+ . current_vty devspec name partner_vtys
+ .. detach_state index partner_clcs vterm_state
+
+Each entry is provided, by default with a "name" attribute. Reading the
+"name" attribute will reveal the device type as shown in the following
+example:
+
+ Pow5:/sys/bus/vio/drivers/hvcs/30000003 # cat name
+ vty-server
+
+Each entry is also provided, by default, with a "devspec" attribute which
+reveals the full device specification when read, as shown in the following
+example:
+
+ Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat devspec
+ /vdevice/vty-server@30000004
+
+Each vty-server sysfs dir is provided with two read-only attributes that
+provide lists of easily parsed partner vty data: "partner_vtys" and
+"partner_clcs".
+
+ Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat partner_vtys
+ 30000000
+ 30000001
+ 30000002
+ 30000000
+ 30000000
+
+ Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat partner_clcs
+ U5112.428.103048A-V3-C0
+ U5112.428.103048A-V3-C2
+ U5112.428.103048A-V3-C3
+ U5112.428.103048A-V4-C0
+ U5112.428.103048A-V5-C0
+
+Reading partner_vtys returns a list of partner vtys. Vty unit address
+numbering is only per-partition-unique so entries will frequently repeat.
+
+Reading partner_clcs returns a list of "converged location codes" which are
+composed of a system serial number followed by "-V*", where the '*' is the
+target partition number, and "-C*", where the '*' is the slot of the
+adapter. The first vty partner corresponds to the first clc item, the
+second vty partner to the second clc item, etc.
+
+A vty-server can only be connected to a single vty at a time. The entry,
+"current_vty" prints the clc of the currently selected partner vty when
+read.
+
+The current_vty can be changed by writing a valid partner clc to the entry
+as in the following example:
+
+ Pow5:/sys/bus/vio/drivers/hvcs/30000004 # echo U5112.428.10304
+ 8A-V4-C0 > current_vty
+
+Changing the current_vty when a vty-server is already connected to a vty
+does not affect the current connection. The change takes effect when the
+currently open connection is freed.
+
+Information on the "vterm_state" attribute was covered earlier on the
+chapter entitled "disconnection".
+
+---------------------------------------------------------------------------
+8. Questions & Answers:
+===========================================================================
+Q: What are the security concerns involving hvcs?
+
+A: There are three main security concerns:
+
+ 1. The creator of the /dev/hvcs* nodes has the ability to restrict
+ the access of the device entries to certain users or groups. It
+ may be best to create a special hvcs group privilege for providing
+ access to system consoles.
+
+ 2. To provide network security when grabbing the console it is
+ suggested that the user connect to the console hosting partition
+ using a secure method, such as SSH or sit at a hardware console.
+
+ 3. Make sure to exit the user session when done with a console or
+ the next vty-server connection (which may be from another
+ partition) will experience the previously logged in session.
+
+---------------------------------------------------------------------------
+Q: How do I multiplex a console that I grab through hvcs so that other
+people can see it:
+
+A: You can use "screen" to directly connect to the /dev/hvcs* device and
+setup a session on your machine with the console group privileges. As
+pointed out earlier by default screen doesn't provide the termcap settings
+for most terminal emulators to provide adequate character conversion from
+term type "screen" to others. This means that curses based programs may
+not display properly in screen sessions.
+
+---------------------------------------------------------------------------
+Q: Why are the colors all messed up?
+Q: Why are the control characters acting strange or not working?
+Q: Why is the console output all strange and unintelligible?
+
+A: Please see the preceding section on "Connection" for a discussion of how
+applications can affect the display of character control sequences.
+Additionally, just because you logged into the console using and xterm
+doesn't mean someone else didn't log into the console with the HMC console
+(vt320) before you and leave the session logged in. The best thing to do
+is to export TERM to the terminal type of your terminal emulator when you
+get the console. Additionally make sure to "exit" the console before you
+disconnect from the console. This will ensure that the next user gets
+their own TERM type set when they login.
+
+---------------------------------------------------------------------------
+Q: When I try to CONNECT kermit to an hvcs device I get:
+"Sorry, can't open connection: /dev/hvcs*"What is happening?
+
+A: Some other Power5 console mechanism has a connection to the vty and
+isn't giving it up. You can try to force disconnect the consoles from the
+HMC by right clicking on the partition and then selecting "close terminal".
+Otherwise you have to hunt down the people who have console authority. It
+is possible that you already have the console open using another kermit
+session and just forgot about it. Please review the console options for
+Power5 systems to determine the many ways a system console can be held.
+
+OR
+
+A: Another user may not have a connectivity method currently attached to a
+/dev/hvcs device but the vterm_state may reveal that they still have the
+vty-server connection established. They need to free this using the method
+outlined in the section on "Disconnection" in order for others to connect
+to the target vty.
+
+OR
+
+A: The user profile you are using to execute kermit probably doesn't have
+permissions to use the /dev/hvcs* device.
+
+OR
+
+A: You probably haven't inserted the hvcs.ko module yet but the /dev/hvcs*
+entry still exists (on systems without udev).
+
+OR
+
+A: There is not a corresponding vty-server device that maps to an existing
+/dev/hvcs* entry.
+
+---------------------------------------------------------------------------
+Q: When I try to CONNECT kermit to an hvcs device I get:
+"Sorry, write access to UUCP lockfile directory denied."
+
+A: The /dev/hvcs* entry you have specified doesn't exist where you said it
+does? Maybe you haven't inserted the module (on systems with udev).
+
+---------------------------------------------------------------------------
+Q: If I already have one Linux partition installed can I use hvcs on said
+partition to provide the console for the install of a second Linux
+partition?
+
+A: Yes granted that your are connected to the /dev/hvcs* device using
+kermit or cu or some other program that doesn't provide terminal emulation.
+
+---------------------------------------------------------------------------
+Q: Can I connect to more than one partition's console at a time using this
+driver?
+
+A: Yes. Of course this means that there must be more than one vty-server
+configured for this partition and each must point to a disconnected vty.
+
+---------------------------------------------------------------------------
+Q: Does the hvcs driver support dynamic (hotplug) addition of devices?
+
+A: Yes, if you have dlpar and hotplug enabled for your system and it has
+been built into the kernel the hvcs drivers is configured to dynamically
+handle additions of new devices and removals of unused devices.
+
+---------------------------------------------------------------------------
+Q: For some reason /dev/hvcs* doesn't map to the same vty-server adapter
+after a reboot. What happened?
+
+A: Assignment of vty-server adapters to /dev/hvcs* entries is always done
+in the order that the adapters are exposed. Due to hotplug capabilities of
+this driver assignment of hotplug added vty-servers may be in a different
+order than how they would be exposed on module load. Rebooting or
+reloading the module after dynamic addition may result in the /dev/hvcs*
+and vty-server coupling changing if a vty-server adapter was added in a
+slot inbetween two other vty-server adapters. Refer to the section above
+on how to determine which vty-server goes with which /dev/hvcs* node.
+Hint; look at the sysfs "index" attribute for the vty-server.
+
+---------------------------------------------------------------------------
+Q: Can I use /dev/hvcs* as a conduit to another partition and use a tty
+device on that partition as the other end of the pipe?
+
+A: Yes, on Power5 platforms the hvc_console driver provides a tty interface
+for extra /dev/hvc* devices (where /dev/hvc0 is most likely the console).
+In order to get a tty conduit working between the two partitions the HMC
+Super Admin must create an additional "serial server" for the target
+partition with the HMC gui which will show up as /dev/hvc* when the target
+partition is rebooted.
+
+The HMC Super Admin then creates an additional "serial client" for the
+current partition and points this at the target partition's newly created
+"serial server" adapter (remember the slot). This shows up as an
+additional /dev/hvcs* device.
+
+Now a program on the target system can be configured to read or write to
+/dev/hvc* and another program on the current partition can be configured to
+read or write to /dev/hvcs*. Now you have a tty conduit between two
+partitions.
+
+---------------------------------------------------------------------------
+9. Reporting Bugs:
+
+The proper channel for reporting bugs is either through the Linux OS
+distribution company that provided your OS or by posting issues to the
+ppc64 development mailing list at:
+
+linuxppc64-dev@lists.linuxppc.org
+
+This request is to provide a documented and searchable public exchange
+of the problems and solutions surrounding this driver for the benefit of
+all users.
diff --git a/Documentation/powerpc/mpc52xx.txt b/Documentation/powerpc/mpc52xx.txt
new file mode 100644
index 0000000..10dd4ab
--- /dev/null
+++ b/Documentation/powerpc/mpc52xx.txt
@@ -0,0 +1,39 @@
+Linux 2.6.x on MPC52xx family
+-----------------------------
+
+For the latest info, go to http://www.246tNt.com/mpc52xx/
+
+To compile/use :
+
+ - U-Boot:
+ # <edit Makefile to set ARCH=ppc & CROSS_COMPILE=... ( also EXTRAVERSION
+ if you wish to ).
+ # make lite5200_defconfig
+ # make uImage
+
+ then, on U-boot:
+ => tftpboot 200000 uImage
+ => tftpboot 400000 pRamdisk
+ => bootm 200000 400000
+
+ - DBug:
+ # <edit Makefile to set ARCH=ppc & CROSS_COMPILE=... ( also EXTRAVERSION
+ if you wish to ).
+ # make lite5200_defconfig
+ # cp your_initrd.gz arch/ppc/boot/images/ramdisk.image.gz
+ # make zImage.initrd
+ # make
+
+ then in DBug:
+ DBug> dn -i zImage.initrd.lite5200
+
+
+Some remarks :
+ - The port is named mpc52xxx, and config options are PPC_MPC52xx. The MGT5100
+ is not supported, and I'm not sure anyone is interesting in working on it
+ so. I didn't took 5xxx because there's apparently a lot of 5xxx that have
+ nothing to do with the MPC5200. I also included the 'MPC' for the same
+ reason.
+ - Of course, I inspired myself from the 2.4 port. If you think I forgot to
+ mention you/your company in the copyright of some code, I'll correct it
+ ASAP.
diff --git a/Documentation/powerpc/ppc_htab.txt b/Documentation/powerpc/ppc_htab.txt
new file mode 100644
index 0000000..8b8c7df
--- /dev/null
+++ b/Documentation/powerpc/ppc_htab.txt
@@ -0,0 +1,118 @@
+ Information about /proc/ppc_htab
+=====================================================================
+
+This document and the related code was written by me (Cort Dougan), please
+email me (cort@fsmlabs.com) if you have questions, comments or corrections.
+
+Last Change: 2.16.98
+
+This entry in the proc directory is readable by all users but only
+writable by root.
+
+The ppc_htab interface is a user level way of accessing the
+performance monitoring registers as well as providing information
+about the PTE hash table.
+
+1. Reading
+
+ Reading this file will give you information about the memory management
+ hash table that serves as an extended tlb for page translation on the
+ powerpc. It will also give you information about performance measurement
+ specific to the cpu that you are using.
+
+ Explanation of the 604 Performance Monitoring Fields:
+ MMCR0 - the current value of the MMCR0 register
+ PMC1
+ PMC2 - the value of the performance counters and a
+ description of what events they are counting
+ which are based on MMCR0 bit settings.
+ Explanation of the PTE Hash Table fields:
+
+ Size - hash table size in Kb.
+ Buckets - number of buckets in the table.
+ Address - the virtual kernel address of the hash table base.
+ Entries - the number of ptes that can be stored in the hash table.
+ User/Kernel - how many pte's are in use by the kernel or user at that time.
+ Overflows - How many of the entries are in their secondary hash location.
+ Percent full - ratio of free pte entries to in use entries.
+ Reloads - Count of how many hash table misses have occurred
+ that were fixed with a reload from the linux tables.
+ Should always be 0 on 603 based machines.
+ Non-error Misses - Count of how many hash table misses have occurred
+ that were completed with the creation of a pte in the linux
+ tables with a call to do_page_fault().
+ Error Misses - Number of misses due to errors such as bad address
+ and permission violations. This includes kernel access of
+ bad user addresses that are fixed up by the trap handler.
+
+ Note that calculation of the data displayed from /proc/ppc_htab takes
+ a long time and spends a great deal of time in the kernel. It would
+ be quite hard on performance to read this file constantly. In time
+ there may be a counter in the kernel that allows successive reads from
+ this file only after a given amount of time has passed to reduce the
+ possibility of a user slowing the system by reading this file.
+
+2. Writing
+
+ Writing to the ppc_htab allows you to change the characteristics of
+ the powerpc PTE hash table and setup performance monitoring.
+
+ Resizing the PTE hash table is not enabled right now due to many
+ complications with moving the hash table, rehashing the entries
+ and many many SMP issues that would have to be dealt with.
+
+ Write options to ppc_htab:
+
+ - To set the size of the hash table to 64Kb:
+
+ echo 'size 64' > /proc/ppc_htab
+
+ The size must be a multiple of 64 and must be greater than or equal to
+ 64.
+
+ - To turn off performance monitoring:
+
+ echo 'off' > /proc/ppc_htab
+
+ - To reset the counters without changing what they're counting:
+
+ echo 'reset' > /proc/ppc_htab
+
+ Note that counting will continue after the reset if it is enabled.
+
+ - To count only events in user mode or only in kernel mode:
+
+ echo 'user' > /proc/ppc_htab
+ ...or...
+ echo 'kernel' > /proc/ppc_htab
+
+ Note that these two options are exclusive of one another and the
+ lack of either of these options counts user and kernel.
+ Using 'reset' and 'off' reset these flags.
+
+ - The 604 has 2 performance counters which can each count events from
+ a specific set of events. These sets are disjoint so it is not
+ possible to count _any_ combination of 2 events. One event can
+ be counted by PMC1 and one by PMC2.
+
+ To start counting a particular event use:
+
+ echo 'event' > /proc/ppc_htab
+
+ and choose from these events:
+
+ PMC1
+ ----
+ 'ic miss' - instruction cache misses
+ 'dtlb' - data tlb misses (not hash table misses)
+
+ PMC2
+ ----
+ 'dc miss' - data cache misses
+ 'itlb' - instruction tlb misses (not hash table misses)
+ 'load miss time' - cycles to complete a load miss
+
+3. Bugs
+
+ The PMC1 and PMC2 counters can overflow and give no indication of that
+ in /proc/ppc_htab.
diff --git a/Documentation/powerpc/smp.txt b/Documentation/powerpc/smp.txt
new file mode 100644
index 0000000..5b581b8
--- /dev/null
+++ b/Documentation/powerpc/smp.txt
@@ -0,0 +1,34 @@
+ Information about Linux/PPC SMP mode
+=====================================================================
+
+This document and the related code was written by me
+(Cort Dougan, cort@fsmlabs.com) please email me if you have questions,
+comments or corrections.
+
+Last Change: 3.31.99
+
+If you want to help by writing code or testing different hardware please
+email me!
+
+1. State of Supported Hardware
+
+ PowerSurge Architecture - tested on UMAX s900, Apple 9600
+ The second processor on this machine boots up just fine and
+ enters its idle loop. Hopefully a completely working SMP kernel
+ on this machine will be done shortly.
+
+ The code makes the assumption of only two processors. The changes
+ necessary to work with any number would not be overly difficult but
+ I don't have any machines with >2 processors so it's not high on my
+ list of priorities. If anyone else would like do to the work email
+ me and I can point out the places that need changed. If you have >2
+ processors and don't want to add support yourself let me know and I
+ can take a look into it.
+
+ BeBox
+ BeBox support hasn't been added to the 2.1.X kernels from 2.0.X
+ but work is being done and SMP support for BeBox is in the works.
+
+ CHRP
+ CHRP SMP works and is fairly solid. It's been tested on the IBM F50
+ with 4 processors for quite some time now.
diff --git a/Documentation/powerpc/sound.txt b/Documentation/powerpc/sound.txt
new file mode 100644
index 0000000..df23d95
--- /dev/null
+++ b/Documentation/powerpc/sound.txt
@@ -0,0 +1,81 @@
+ Information about PowerPC Sound support
+=====================================================================
+
+Please mail me (Cort Dougan, cort@fsmlabs.com) if you have questions,
+comments or corrections.
+
+Last Change: 6.16.99
+
+This just covers sound on the PReP and CHRP systems for now and later
+will contain information on the PowerMac's.
+
+Sound on PReP has been tested and is working with the PowerStack and IBM
+Power Series onboard sound systems which are based on the cs4231(2) chip.
+The sound options when doing the make config are a bit different from
+the default, though.
+
+The I/O base, irq and dma lines that you enter during the make config
+are ignored and are set when booting according to the machine type.
+This is so that one binary can be used for Motorola and IBM machines
+which use different values and isn't allowed by the driver, so things
+are hacked together in such a way as to allow this information to be
+set automatically on boot.
+
+1. Motorola PowerStack PReP machines
+
+ Enable support for "Crystal CS4232 based (PnP) cards" and for the
+ Microsoft Sound System. The MSS isn't used, but some of the routines
+ that the CS4232 driver uses are in it.
+
+ Although the options you set are ignored and determined automatically
+ on boot these are included for information only:
+
+ (830) CS4232 audio I/O base 530, 604, E80 or F40
+ (10) CS4232 audio IRQ 5, 7, 9, 11, 12 or 15
+ (6) CS4232 audio DMA 0, 1 or 3
+ (7) CS4232 second (duplex) DMA 0, 1 or 3
+
+ This will allow simultaneous record and playback, as 2 different dma
+ channels are used.
+
+ The sound will be all left channel and very low volume since the
+ auxiliary input isn't muted by default. I had the changes necessary
+ for this in the kernel but the sound driver maintainer didn't want
+ to include them since it wasn't common in other machines. To fix this
+ you need to mute it using a mixer utility of some sort (if you find one
+ please let me know) or by patching the driver yourself and recompiling.
+
+ There is a problem on the PowerStack 2's (PowerStack Pro's) using a
+ different irq/drq than the kernel expects. Unfortunately, I don't know
+ which irq/drq it is so if anyone knows please email me.
+
+ Midi is not supported since the cs4232 driver doesn't support midi yet.
+
+2. IBM PowerPersonal PReP machines
+
+ I've only tested sound on the Power Personal Series of IBM workstations
+ so if you try it on others please let me know the result. I'm especially
+ interested in the 43p's sound system, which I know nothing about.
+
+ Enable support for "Crystal CS4232 based (PnP) cards" and for the
+ Microsoft Sound System. The MSS isn't used, but some of the routines
+ that the CS4232 driver uses are in it.
+
+ Although the options you set are ignored and determined automatically
+ on boot these are included for information only:
+
+ (530) CS4232 audio I/O base 530, 604, E80 or F40
+ (5) CS4232 audio IRQ 5, 7, 9, 11, 12 or 15
+ (1) CS4232 audio DMA 0, 1 or 3
+ (7) CS4232 second (duplex) DMA 0, 1 or 3
+ (330) CS4232 MIDI I/O base 330, 370, 3B0 or 3F0
+ (9) CS4232 MIDI IRQ 5, 7, 9, 11, 12 or 15
+
+ This setup does _NOT_ allow for recording yet.
+
+ Midi is not supported since the cs4232 driver doesn't support midi yet.
+
+2. IBM CHRP
+
+ I have only tested this on the 43P-150. Build the kernel with the cs4232
+ set as a module and load the module with irq=9 dma=1 dma2=2 io=0x550
diff --git a/Documentation/powerpc/zImage_layout.txt b/Documentation/powerpc/zImage_layout.txt
new file mode 100644
index 0000000..048e015
--- /dev/null
+++ b/Documentation/powerpc/zImage_layout.txt
@@ -0,0 +1,47 @@
+ Information about the Linux/PPC kernel images
+=====================================================================
+
+Please mail me (Cort Dougan, cort@fsmlabs.com) if you have questions,
+comments or corrections.
+
+This document is meant to answer several questions I've had about how
+the PReP system boots and how Linux/PPC interacts with that mechanism.
+It would be nice if we could have information on how other architectures
+boot here as well. If you have anything to contribute, please
+let me know.
+
+
+1. PReP boot file
+
+ This is the file necessary to boot PReP systems from floppy or
+ hard drive. The firmware reads the PReP partition table entry
+ and will load the image accordingly.
+
+ To boot the zImage, copy it onto a floppy with dd if=zImage of=/dev/fd0h1440
+ or onto a PReP hard drive partition with dd if=zImage of=/dev/sda4
+ assuming you've created a PReP partition (type 0x41) with fdisk on
+ /dev/sda4.
+
+ The layout of the image format is:
+
+ 0x0 +------------+
+ | | PReP partition table entry
+ | |
+ 0x400 +------------+
+ | | Bootstrap program code + data
+ | |
+ | |
+ +------------+
+ | | compressed kernel, elf header removed
+ +------------+
+ | | initrd (if loaded)
+ +------------+
+ | | Elf section table for bootstrap program
+ +------------+
+
+
+2. MBX boot file
+
+ The MBX boards can load an elf image, and relocate it to the
+ proper location in memory - it copies the image to the location it was
+ linked at.
