bkgpl/cyb4_linux
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Creation of Cybook 2416 (actually Gen4) repository

Browse Source
This commit is contained in:
mlt
2009-12-18 17:10:00 +00:00
committed by godzil
commit 76f20f4d40
13791 changed files with 6812321 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
Documentation/powerpc/00-INDEX Normal file
View File

@@ -0,0 +1,26 @@
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.
eeh-pci-error-recovery.txt
- info on PCI Bus EEH Error Recovery
hvcs.txt
- IBM "Hypervisor Virtual Console Server" Installation Guide
mpc52xx.txt
- Linux 2.6.x on MPC52xx family
ppc_htab.txt
- info about the Linux/PPC /proc/ppc_htab entry
SBC8260_memory_mapping.txt
- EST SBC8260 board info
smp.txt
- use and state info about Linux/PPC on MP machines
sound.txt
- info on sound support under Linux/PPC
zImage_layout.txt
- info on the kernel images for Linux/PPC

197
Documentation/powerpc/SBC8260_memory_mapping.txt Normal file
View File

@@ -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:

1852
Documentation/powerpc/booting-without-of.txt Normal file
View File

File diff suppressed because it is too large Load Diff

56
Documentation/powerpc/cpu_features.txt Normal file
View File

@@ -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.

334
Documentation/powerpc/eeh-pci-error-recovery.txt Normal file
View File

@@ -0,0 +1,334 @@
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 resetting 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 userspace/udev
infrastructure. Following 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/powerpc/platforms/pseries/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-powerpc/io.h macros readb(), inb(), insb(),
etc. include a check to see if 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/powerpc/platforms/pseries/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 uevents 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_uevent() { // in /libs/kobject.c
calls
kset_uevent() { // in /lib/kobject.c
calls
kset->uevent_ops->uevent() // which is really just
a call to
dev_uevent() { // in /drivers/base/core.c
calls
dev->bus->uevent() which is really just a call to
pci_uevent () { // in drivers/pci/hotplug.c
which prints device name, etc....
}
}
then kobject_uevent() sends a netlink uevent to userspace
--> userspace uevent
(during early boot, nobody listens to netlink events and
kobject_uevent() executes uevent_helper[], which runs the
event process /sbin/hotplug)
}
}
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 ...

567
Documentation/powerpc/hvcs.txt Normal file
View File

@@ -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 guaranteed 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
.. 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
PowerPC development mailing list at:
linuxppc-dev@ozlabs.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.

254
Documentation/powerpc/mpc52xx-device-tree-bindings.txt Normal file
View File

@@ -0,0 +1,254 @@
MPC5200 Device Tree Bindings
----------------------------
(c) 2006-2007 Secret Lab Technologies Ltd
Grant Likely <grant.likely at secretlab.ca>
********** DRAFT ***********
* WARNING: Do not depend on the stability of these bindings just yet.
* The MPC5200 device tree conventions are still in flux
* Keep an eye on the linuxppc-dev mailing list for more details
********** DRAFT ***********
I - Introduction
================
Boards supported by the arch/powerpc architecture require device tree be
passed by the boot loader to the kernel at boot time. The device tree
describes what devices are present on the board and how they are
connected. The device tree can either be passed as a binary blob (as
described in Documentation/powerpc/booting-without-of.txt), or passed
by Open Firmare (IEEE 1275) compatible firmware using an OF compatible
client interface API.
This document specifies the requirements on the device-tree for mpc5200
based boards. These requirements are above and beyond the details
specified in either the OpenFirmware spec or booting-without-of.txt
All new mpc5200-based boards are expected to match this document. In
cases where this document is not sufficient to support a new board port,
this document should be updated as part of adding the new board support.
II - Philosophy
===============
The core of this document is naming convention. The whole point of
defining this convention is to reduce or eliminate the number of
special cases required to support a 5200 board. If all 5200 boards
follow the same convention, then generic 5200 support code will work
rather than coding special cases for each new board.
This section tries to capture the thought process behind why the naming
convention is what it is.
1. names
---------
There is strong convention/requirements already established for children
of the root node. 'cpus' describes the processor cores, 'memory'
describes memory, and 'chosen' provides boot configuration. Other nodes
are added to describe devices attached to the processor local bus.
Following convention already established with other system-on-chip
processors, 5200 device trees should use the name 'soc5200' for the
parent node of on chip devices, and the root node should be its parent.
Child nodes are typically named after the configured function. ie.
the FEC node is named 'ethernet', and a PSC in uart mode is named 'serial'.
2. device_type property
-----------------------
similar to the node name convention above; the device_type reflects the
configured function of a device. ie. 'serial' for a uart and 'spi' for
an spi controller. However, while node names *should* reflect the
configured function, device_type *must* match the configured function
exactly.
3. compatible property
----------------------
Since device_type isn't enough to match devices to drivers, there also
needs to be a naming convention for the compatible property. Compatible
is an list of device descriptions sorted from specific to generic. For
the mpc5200, the required format for each compatible value is
<chip>-<device>[-<mode>]. The OS should be able to match a device driver
to the device based solely on the compatible value. If two drivers
match on the compatible list; the 'most compatible' driver should be
selected.
The split between the MPC5200 and the MPC5200B leaves a bit of a
connundrum. How should the compatible property be set up to provide
maximum compatability information; but still acurately describe the
chip? For the MPC5200; the answer is easy. Most of the SoC devices
originally appeared on the MPC5200. Since they didn't exist anywhere
else; the 5200 compatible properties will contain only one item;
"mpc5200-<device>".
The 5200B is almost the same as the 5200, but not quite. It fixes
silicon bugs and it adds a small number of enhancements. Most of the
devices either provide exactly the same interface as on the 5200. A few
devices have extra functions but still have a backwards compatible mode.
To express this infomation as completely as possible, 5200B device trees
should have two items in the compatible list;
"mpc5200b-<device>\0mpc5200-<device>". It is *strongly* recommended
that 5200B device trees follow this convention (instead of only listing
the base mpc5200 item).
If another chip appear on the market with one of the mpc5200 SoC
devices, then the compatible list should include mpc5200-<device>.
ie. ethernet on mpc5200: compatible = "mpc5200-ethernet"
ethernet on mpc5200b: compatible = "mpc5200b-ethernet\0mpc5200-ethernet"
Modal devices, like PSCs, also append the configured function to the
end of the compatible field. ie. A PSC in i2s mode would specify
"mpc5200-psc-i2s", not "mpc5200-i2s". This convention is chosen to
avoid naming conflicts with non-psc devices providing the same
function. For example, "mpc5200-spi" and "mpc5200-psc-spi" describe
the mpc5200 simple spi device and a PSC spi mode respectively.
If the soc device is more generic and present on other SOCs, the
compatible property can specify the more generic device type also.
ie. mscan: compatible = "mpc5200-mscan\0fsl,mscan";
At the time of writing, exact chip may be either 'mpc5200' or
'mpc5200b'.
Device drivers should always try to match as generically as possible.
III - Structure
===============
The device tree for an mpc5200 board follows the structure defined in
booting-without-of.txt with the following additional notes:
0) the root node
----------------
Typical root description node; see booting-without-of
1) The cpus node
----------------
The cpus node follows the basic layout described in booting-without-of.
The bus-frequency property holds the XLB bus frequency
The clock-frequency property holds the core frequency
2) The memory node
------------------
Typical memory description node; see booting-without-of.
3) The soc5200 node
-------------------
This node describes the on chip SOC peripherals. Every mpc5200 based
board will have this node, and as such there is a common naming
convention for SOC devices.
Required properties:
name type description
---- ---- -----------
device_type string must be "soc"
ranges int should be <0 baseaddr baseaddr+10000>
reg int must be <baseaddr 10000>
compatible string mpc5200: "mpc5200-soc"
mpc5200b: "mpc5200b-soc\0mpc5200-soc"
system-frequency int Fsystem frequency; source of all
other clocks.
bus-frequency int IPB bus frequency in HZ. Clock rate
used by most of the soc devices.
#interrupt-cells int must be <3>.
Recommended properties:
name type description
---- ---- -----------
model string Exact model of the chip;
ie: model="fsl,mpc5200"
revision string Silicon revision of chip
ie: revision="M08A"
The 'model' and 'revision' properties are *strongly* recommended. Having
them presence acts as a bit of a safety net for working around as yet
undiscovered bugs on one version of silicon. For example, device drivers
can use the model and revision properties to decide if a bug fix should
be turned on.
4) soc5200 child nodes
----------------------
Any on chip SOC devices available to Linux must appear as soc5200 child nodes.
Note: The tables below show the value for the mpc5200. A mpc5200b device
tree should use the "mpc5200b-<device>\0mpc5200-<device> form.
Required soc5200 child nodes:
name device_type compatible Description
---- ----------- ---------- -----------
cdm@<addr> cdm mpc5200-cmd Clock Distribution
pic@<addr> interrupt-controller mpc5200-pic need an interrupt
controller to boot
bestcomm@<addr> dma-controller mpc5200-bestcomm 5200 pic also requires
the bestcomm device
Recommended soc5200 child nodes; populate as needed for your board
name device_type compatible Description
---- ----------- ---------- -----------
gpt@<addr> gpt mpc5200-gpt General purpose timers
rtc@<addr> rtc mpc5200-rtc Real time clock
mscan@<addr> mscan mpc5200-mscan CAN bus controller
pci@<addr> pci mpc5200-pci PCI bridge
serial@<addr> serial mpc5200-psc-uart PSC in serial mode
i2s@<addr> sound mpc5200-psc-i2s PSC in i2s mode
ac97@<addr> sound mpc5200-psc-ac97 PSC in ac97 mode
spi@<addr> spi mpc5200-psc-spi PSC in spi mode
irda@<addr> irda mpc5200-psc-irda PSC in IrDA mode
spi@<addr> spi mpc5200-spi MPC5200 spi device
ethernet@<addr> network mpc5200-fec MPC5200 ethernet device
ata@<addr> ata mpc5200-ata IDE ATA interface
i2c@<addr> i2c mpc5200-i2c I2C controller
usb@<addr> usb-ohci-be mpc5200-ohci,ohci-be USB controller
xlb@<addr> xlb mpc5200-xlb XLB arbritrator
Important child node properties
name type description
---- ---- -----------
cell-index int When multiple devices are present, is the
index of the device in the hardware (ie. There
are 6 PSC on the 5200 numbered PSC1 to PSC6)
PSC1 has 'cell-index = <0>'
PSC4 has 'cell-index = <3>'
5) General Purpose Timer nodes (child of soc5200 node)
On the mpc5200 and 5200b, GPT0 has a watchdog timer function. If the board
design supports the internal wdt, then the device node for GPT0 should
include the empty property 'has-wdt'.
6) PSC nodes (child of soc5200 node)
PSC nodes can define the optional 'port-number' property to force assignment
order of serial ports. For example, PSC5 might be physically connected to
the port labeled 'COM1' and PSC1 wired to 'COM1'. In this case, PSC5 would
have a "port-number = <0>" property, and PSC1 would have "port-number = <1>".
PSC in i2s mode: The mpc5200 and mpc5200b PSCs are not compatible when in
i2s mode. An 'mpc5200b-psc-i2s' node cannot include 'mpc5200-psc-i2s' in the
compatible field.
IV - Extra Notes
================
1. Interrupt mapping
--------------------
The mpc5200 pic driver splits hardware IRQ numbers into two levels. The
split reflects the layout of the PIC hardware itself, which groups
interrupts into one of three groups; CRIT, MAIN or PERP. Also, the
Bestcomm dma engine has it's own set of interrupt sources which are
cascaded off of peripheral interrupt 0, which the driver interprets as a
fourth group, SDMA.
The interrupts property for device nodes using the mpc5200 pic consists
of three cells; <L1 L2 level>
L1 := [CRIT=0, MAIN=1, PERP=2, SDMA=3]
L2 := interrupt number; directly mapped from the value in the
"ICTL PerStat, MainStat, CritStat Encoded Register"
level := [LEVEL_HIGH=0, EDGE_RISING=1, EDGE_FALLING=2, LEVEL_LOW=3]
2. Shared registers
-------------------
Some SoC devices share registers between them. ie. the i2c devices use
a single clock control register, and almost all device are affected by
the port_config register. Devices which need to manipulate shared regs
should look to the parent SoC node. The soc node is responsible
for arbitrating all shared register access.

39
Documentation/powerpc/mpc52xx.txt Normal file
View File

@@ -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.

118
Documentation/powerpc/ppc_htab.txt Normal file
View File

@@ -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.

34
Documentation/powerpc/smp.txt Normal file
View File

@@ -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.

81
Documentation/powerpc/sound.txt Normal file
View File

@@ -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

47
Documentation/powerpc/zImage_layout.txt Normal file
View File

@@ -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.