Merge branch 'for-2.6.25' of...

	- info on sound support under Linux/PPC

zImage_layout.txt

	- info on the kernel images for Linux/PPC

qe_firmware.txt

	- describes the layout of firmware binaries for the Freescale QUICC

	  Engine and the code that parses and uploads the microcode therein.

      i) Freescale QUICC Engine module (QE)

      j) CFI or JEDEC memory-mapped NOR flash

      k) Global Utilities Block

      l) Xilinx IP cores

      l) Freescale Communications Processor Module

      m) Chipselect/Local Bus

      n) 4xx/Axon EMAC ethernet nodes

      o) Xilinx IP cores

      p) Freescale Synchronous Serial Interface

  VII - Specifying interrupt information for devices

    1) interrupts property

      services interrupts for this device.

    - phy-handle : The phandle for the PHY connected to this ethernet

      controller.

    - fixed-link : <a b c d e> where a is emulated phy id - choose any,

      but unique to the all specified fixed-links, b is duplex - 0 half,

      1 full, c is link speed - d#10/d#100/d#1000, d is pause - 0 no

      pause, 1 pause, e is asym_pause - 0 no asym_pause, 1 asym_pause.

  Recommended properties:

   Example multi port host USB controller device node :

	usb@22000 {

	        device_type = "usb";

		compatible = "fsl-usb2-mph";

		reg = <22000 1000>;

		#address-cells = <1>;

   Example dual role USB controller device node :

	usb@23000 {

		device_type = "usb";

		compatible = "fsl-usb2-dr";

		reg = <23000 1000>;

		#address-cells = <1>;

   iii) USB (Universal Serial Bus Controller)

   Required properties:

   - device_type : should be "usb".

   - compatible : could be "qe_udc" or "fhci-hcd".

   - mode : the could be "host" or "slave".

   - reg : Offset and length of the register set for the device

   Example(slave):

	usb@6c0 {

		device_type = "usb";

		compatible = "qe_udc";

		reg = <6c0 40>;

		interrupts = <8b 0>;

   Required properties:

   - device_type : should be "network", "hldc", "uart", "transparent"

    "bisync" or "atm".

     "bisync", "atm", or "serial".

   - compatible : could be "ucc_geth" or "fsl_atm" and so on.

   - model : should be "UCC".

   - device-id : the ucc number(1-8), corresponding to UCCx in UM.

   - interrupt-parent : the phandle for the interrupt controller that

     services interrupts for this device.

   - pio-handle : The phandle for the Parallel I/O port configuration.

   - port-number : for UART drivers, the port number to use, between 0 and 3.

     This usually corresponds to the /dev/ttyQE device, e.g. <0> = /dev/ttyQE0.

     The port number is added to the minor number of the device.  Unlike the

     CPM UART driver, the port-number is required for the QE UART driver.

   - soft-uart : for UART drivers, if specified this means the QE UART device

     driver should use "Soft-UART" mode, which is needed on some SOCs that have

     broken UART hardware.  Soft-UART is provided via a microcode upload.

   - rx-clock-name: the UCC receive clock source

     "none": clock source is disabled

     "brg1" through "brg16": clock source is BRG1-BRG16, respectively

		};

	};

   viii) Uploaded QE firmware

	 If a new firwmare has been uploaded to the QE (usually by the

	 boot loader), then a 'firmware' child node should be added to the QE

	 node.  This node provides information on the uploaded firmware that

	 device drivers may need.

	 Required properties:

	 - id: The string name of the firmware.  This is taken from the 'id'

	       member of the qe_firmware structure of the uploaded firmware.

	       Device drivers can search this string to determine if the

	       firmware they want is already present.

	 - extended-modes: The Extended Modes bitfield, taken from the

			   firmware binary.  It is a 64-bit number represented

			   as an array of two 32-bit numbers.

	 - virtual-traps: The virtual traps, taken from the firmware binary.

			  It is an array of 8 32-bit numbers.

	 Example:

		firmware {

			id = "Soft-UART";

			extended-modes = <0 0>;

			virtual-traps = <0 0 0 0 0 0 0 0>;

		}

   j) CFI or JEDEC memory-mapped NOR flash

    Flash chips (Memory Technology Devices) are often used for solid state

			   available.

			   For Axon: 0x0000012a

   l) Xilinx IP cores

   o) Xilinx IP cores

   The Xilinx EDK toolchain ships with a set of IP cores (devices) for use

   in Xilinx Spartan and Virtex FPGAs.  The devices cover the whole range

      Requred properties:

       - current-speed : Baud rate of uartlite

    p) Freescale Synchronous Serial Interface

       The SSI is a serial device that communicates with audio codecs.  It can

       be programmed in AC97, I2S, left-justified, or right-justified modes.

       Required properties:

       - compatible	  : compatible list, containing "fsl,ssi"

       - cell-index	  : the SSI, <0> = SSI1, <1> = SSI2, and so on

       - reg		  : offset and length of the register set for the device

       - interrupts	  : <a b> where a is the interrupt number and b is a

                            field that represents an encoding of the sense and

			    level information for the interrupt.  This should be

			    encoded based on the information in section 2)

			    depending on the type of interrupt controller you

			    have.

       - interrupt-parent : the phandle for the interrupt controller that

                            services interrupts for this device.

       - fsl,mode	  : the operating mode for the SSI interface

			    "i2s-slave" - I2S mode, SSI is clock slave

			    "i2s-master" - I2S mode, SSI is clock master

			    "lj-slave" - left-justified mode, SSI is clock slave

			    "lj-master" - l.j. mode, SSI is clock master

			    "rj-slave" - right-justified mode, SSI is clock slave

			    "rj-master" - r.j., SSI is clock master

			    "ac97-slave" - AC97 mode, SSI is clock slave

			    "ac97-master" - AC97 mode, SSI is clock master

       Optional properties:

       - codec-handle	  : phandle to a 'codec' node that defines an audio

			    codec connected to this SSI.  This node is typically

			    a child of an I2C or other control node.

       Child 'codec' node required properties:

       - compatible	  : compatible list, contains the name of the codec

       Child 'codec' node optional properties:

       - clock-frequency  : The frequency of the input clock, which typically

                            comes from an on-board dedicated oscillator.

   More devices will be defined as this spec matures.

VII - Specifying interrupt information for devices

	   Freescale QUICC Engine Firmware Uploading

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

(c) 2007 Timur Tabi <timur at freescale.com>,

    Freescale Semiconductor

Table of Contents

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

  I - Software License for Firmware

  II - Microcode Availability

  III - Description and Terminology

  IV - Microcode Programming Details

  V - Firmware Structure Layout

  VI - Sample Code for Creating Firmware Files

Revision Information

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

November 30, 2007: Rev 1.0 - Initial version

I - Software License for Firmware

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

Each firmware file comes with its own software license.  For information on

the particular license, please see the license text that is distributed with

the firmware.

II - Microcode Availability

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

Firmware files are distributed through various channels.  Some are available on

http://opensource.freescale.com.  For other firmware files, please contact

your Freescale representative or your operating system vendor.

III - Description and Terminology

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

In this document, the term 'microcode' refers to the sequence of 32-bit

integers that compose the actual QE microcode.

The term 'firmware' refers to a binary blob that contains the microcode as

well as other data that

	1) describes the microcode's purpose

	2) describes how and where to upload the microcode

	3) specifies the values of various registers

	4) includes additional data for use by specific device drivers

Firmware files are binary files that contain only a firmware.

IV - Microcode Programming Details

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

The QE architecture allows for only one microcode present in I-RAM for each

RISC processor.  To replace any current microcode, a full QE reset (which

disables the microcode) must be performed first.

QE microcode is uploaded using the following procedure:

1) The microcode is placed into I-RAM at a specific location, using the

   IRAM.IADD and IRAM.IDATA registers.

2) The CERCR.CIR bit is set to 0 or 1, depending on whether the firmware

   needs split I-RAM.  Split I-RAM is only meaningful for SOCs that have

   QEs with multiple RISC processors, such as the 8360.  Splitting the I-RAM

   allows each processor to run a different microcode, effectively creating an

   asymmetric multiprocessing (AMP) system.

3) The TIBCR trap registers are loaded with the addresses of the trap handlers

   in the microcode.

4) The RSP.ECCR register is programmed with the value provided.

5) If necessary, device drivers that need the virtual traps and extended mode

   data will use them.

Virtual Microcode Traps

These virtual traps are conditional branches in the microcode.  These are

"soft" provisional introduced in the ROMcode in order to enable higher

flexibility and save h/w traps If new features are activated or an issue is

being fixed in the RAM package utilizing they should be activated.  This data

structure signals the microcode which of these virtual traps is active.

This structure contains 6 words that the application should copy to some

specific been defined.  This table describes the structure.

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

	| Offset in |                  | Destination Offset | Size of |

	|   array   |     Protocol     |   within PRAM      | Operand |

	--------------------------------------------------------------|

	|     0     | Ethernet         |      0xF8          | 4 bytes |

	|           | interworking     |                    |         |

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

	|     4     | ATM              |      0xF8          | 4 bytes |

	|           | interworking     |                    |         |

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

	|     8     | PPP              |      0xF8          | 4 bytes |

	|           | interworking     |                    |         |

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

	|     12    | Ethernet RX      |      0x22          | 1 byte  |

	|           | Distributor Page |                    |         |

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

	|     16    | ATM Globtal      |      0x28          | 1 byte  |

	|           | Params Table     |                    |         |

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

	|     20    | Insert Frame     |      0xF8          | 4 bytes |

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

Extended Modes

This is a double word bit array (64 bits) that defines special functionality

which has an impact on the softwarew drivers.  Each bit has its own impact

and has special instructions for the s/w associated with it.  This structure is

described in this table:

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

	| Bit #  |     Name     |   Description                               |

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

	|   0    | General      | Indicates that prior to each host command   |

	|        | push command | given by the application, the software must |

	|        |              | assert a special host command (push command)|

	|        |              | CECDR = 0x00800000.                         |

	|        |              | CECR = 0x01c1000f.                          |

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

	|   1    | UCC ATM      | Indicates that after issuing ATM RX INIT    |

	|        | RX INIT      | command, the host must issue another special|

	|        | push command | command (push command) and immediately      |

	|        |              | following that re-issue the ATM RX INIT     |

	|        |              | command. (This makes the sequence of        |

	|        |              | initializing the ATM receiver a sequence of |

	|        |              | three host commands)                        |

	|        |              | CECDR = 0x00800000.                         |

	|        |              | CECR = 0x01c1000f.                          |

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

	|   2    | Add/remove   | Indicates that following the specific host  |

	|        | command      | command: "Add/Remove entry in Hash Lookup   |

	|        | validation   | Table" used in Interworking setup, the user |

	|        |              | must issue another command.                 |

	|        |              | CECDR = 0xce000003.                         |

	|        |              | CECR = 0x01c10f58.                          |

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

	|   3    | General push | Indicates that the s/w has to initialize    |

	|        | command      | some pointers in the Ethernet thread pages  |

	|        |              | which are used when Header Compression is   |

	|        |              | activated.  The full details of these       |

	|        |              | pointers is located in the software drivers.|

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

	|   4    | General push | Indicates that after issuing Ethernet TX    |

	|        | command      | INIT command, user must issue this command  |

	|        |              | for each SNUM of Ethernet TX thread.        |

	|        |              | CECDR = 0x00800003.                         |

	|        |              | CECR = 0x7'b{0}, 8'b{Enet TX thread SNUM},  |

	|        |              |        1'b{1}, 12'b{0}, 4'b{1}              |

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

	| 5 - 31 |     N/A      | Reserved, set to zero.                      |

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

V - Firmware Structure Layout

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

QE microcode from Freescale is typically provided as a header file.  This

header file contains macros that define the microcode binary itself as well as

some other data used in uploading that microcode.  The format of these files

do not lend themselves to simple inclusion into other code.  Hence,

the need for a more portable format.  This section defines that format.

Instead of distributing a header file, the microcode and related data are

embedded into a binary blob.  This blob is passed to the qe_upload_firmware()

function, which parses the blob and performs everything necessary to upload

the microcode.

All integers are big-endian.  See the comments for function

qe_upload_firmware() for up-to-date implementation information.

This structure supports versioning, where the version of the structure is

embedded into the structure itself.  To ensure forward and backwards

compatibility, all versions of the structure must use the same 'qe_header'

structure at the beginning.

'header' (type: struct qe_header):

	The 'length' field is the size, in bytes, of the entire structure,

	including all the microcode embedded in it, as well as the CRC (if

	present).

	The 'magic' field is an array of three bytes that contains the letters

	'Q', 'E', and 'F'.  This is an identifier that indicates that this

	structure is a QE Firmware structure.

	The 'version' field is a single byte that indicates the version of this

	structure.  If the layout of the structure should ever need to be

	changed to add support for additional types of microcode, then the

	version number should also be changed.

The 'id' field is a null-terminated string(suitable for printing) that

identifies the firmware.

The 'count' field indicates the number of 'microcode' structures.  There

must be one and only one 'microcode' structure for each RISC processor.

Therefore, this field also represents the number of RISC processors for this

SOC.

The 'soc' structure contains the SOC numbers and revisions used to match

the microcode to the SOC itself.  Normally, the microcode loader should

check the data in this structure with the SOC number and revisions, and

only upload the microcode if there's a match.  However, this check is not

made on all platforms.

Although it is not recommended, you can specify '0' in the soc.model

field to skip matching SOCs altogether.

The 'model' field is a 16-bit number that matches the actual SOC. The

'major' and 'minor' fields are the major and minor revision numbrs,

respectively, of the SOC.

For example, to match the 8323, revision 1.0:

     soc.model = 8323

     soc.major = 1

     soc.minor = 0

'padding' is neccessary for structure alignment.  This field ensures that the

'extended_modes' field is aligned on a 64-bit boundary.

'extended_modes' is a bitfield that defines special functionality which has an

impact on the device drivers.  Each bit has its own impact and has special

instructions for the driver associated with it.  This field is stored in

the QE library and available to any driver that calles qe_get_firmware_info().

'vtraps' is an array of 8 words that contain virtual trap values for each

virtual traps.  As with 'extended_modes', this field is stored in the QE

library and available to any driver that calles qe_get_firmware_info().

'microcode' (type: struct qe_microcode):

	For each RISC processor there is one 'microcode' structure.  The first

	'microcode' structure is for the first RISC, and so on.

	The 'id' field is a null-terminated string suitable for printing that

	identifies this particular microcode.

	'traps' is an array of 16 words that contain hardware trap values

	for each of the 16 traps.  If trap[i] is 0, then this particular

	trap is to be ignored (i.e. not written to TIBCR[i]).  The entire value

	is written as-is to the TIBCR[i] register, so be sure to set the EN

	and T_IBP bits if necessary.

	'eccr' is the value to program into the ECCR register.

	'iram_offset' is the offset into IRAM to start writing the

	microcode.

	'count' is the number of 32-bit words in the microcode.

	'code_offset' is the offset, in bytes, from the beginning of this

	structure where the microcode itself can be found.  The first

	microcode binary should be located immediately after the 'microcode'

	array.

	'major', 'minor', and 'revision' are the major, minor, and revision

	version numbers, respectively, of the microcode.  If all values are 0,

	then these fields are ignored.

	'reserved' is necessary for structure alignment.  Since 'microcode'

	is an array, the 64-bit 'extended_modes' field needs to be aligned

	on a 64-bit boundary, and this can only happen if the size of

	'microcode' is a multiple of 8 bytes.  To ensure that, we add

	'reserved'.

After the last microcode is a 32-bit CRC.  It can be calculated using

this algorithm:

u32 crc32(const u8 *p, unsigned int len)

{

	unsigned int i;

	u32 crc = 0;

	while (len--) {

	   crc ^= *p++;

	   for (i = 0; i < 8; i++)

		   crc = (crc >> 1) ^ ((crc & 1) ? 0xedb88320 : 0);

	}

	return crc;

}

VI - Sample Code for Creating Firmware Files

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

A Python program that creates firmware binaries from the header files normally

distributed by Freescale can be found on http://opensource.freescale.com.

	  Used to allow a board to specify it wants a uImage built by default

	default n

config REDBOOT

	bool

config PPC64_SWSUSP

	bool

	depends on PPC64 && (BROKEN || (PPC_PMAC64 && EXPERIMENTAL))

zImage.miboot

zImage.pmac

zImage.pseries

zImage.redboot*

zImage.sandpoint

zImage.vmode

zconf.h