3 files changed, 382 insertions, 7 deletions

diff --git a/Documentation/powerpc/00-INDEX b/Documentation/powerpc/00-INDEX
index 94a3c577b083..3be84aa38dfe 100644
--- a/Documentation/powerpc/00-INDEX
+++ b/Documentation/powerpc/00-INDEX
@@ -28,3 +28,6 @@ sound.txt
         - 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.
diff --git a/Documentation/powerpc/booting-without-of.txt b/Documentation/powerpc/booting-without-of.txt
index 6d1d0856063e..da98154328a0 100644
--- a/Documentation/powerpc/booting-without-of.txt
+++ b/Documentation/powerpc/booting-without-of.txt
@@ -52,7 +52,11 @@ Table of Contents
       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
@@ -1257,6 +1261,10 @@ platforms are moved over to use the flattened-device-tree model.
       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:
 
@@ -1411,7 +1419,6 @@ platforms are moved over to use the flattened-device-tree model.
 
    Example multi port host USB controller device node :
         usb@22000 {
-                device_type = "usb";
                 compatible = "fsl-usb2-mph";
                 reg = <22000 1000>;
                 #address-cells = <1>;
@@ -1425,7 +1432,6 @@ platforms are moved over to use the flattened-device-tree model.
 
    Example dual role USB controller device node :
         usb@23000 {
-                device_type = "usb";
                 compatible = "fsl-usb2-dr";
                 reg = <23000 1000>;
                 #address-cells = <1>;
@@ -1589,7 +1595,6 @@ platforms are moved over to use the flattened-device-tree model.
    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
@@ -1603,7 +1608,6 @@ platforms are moved over to use the flattened-device-tree model.
 
    Example(slave):
         usb@6c0 {
-                device_type = "usb";
                 compatible = "qe_udc";
                 reg = <6c0 40>;
                 interrupts = <8b 0>;
@@ -1616,7 +1620,7 @@ platforms are moved over to use the flattened-device-tree model.
 
    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.
@@ -1629,6 +1633,13 @@ platforms are moved over to use the flattened-device-tree model.
    - 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
@@ -1788,6 +1799,32 @@ platforms are moved over to use the flattened-device-tree model.
                 };
         };
 
+   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
@@ -2269,7 +2306,7 @@ platforms are moved over to use the flattened-device-tree model.
                            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
@@ -2539,6 +2576,46 @@ platforms are moved over to use the flattened-device-tree model.
       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
diff --git a/Documentation/powerpc/qe_firmware.txt b/Documentation/powerpc/qe_firmware.txt
new file mode 100644
index 000000000000..896266432d33
--- /dev/null
+++ b/Documentation/powerpc/qe_firmware.txt
@@ -0,0 +1,295 @@
+           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.