0001 =========================================
0002 Freescale QUICC Engine Firmware Uploading
0003 =========================================
0004
0005 (c) 2007 Timur Tabi <timur at freescale.com>,
0006 Freescale Semiconductor
0007
0008 .. Table of Contents
0009
0010 I - Software License for Firmware
0011
0012 II - Microcode Availability
0013
0014 III - Description and Terminology
0015
0016 IV - Microcode Programming Details
0017
0018 V - Firmware Structure Layout
0019
0020 VI - Sample Code for Creating Firmware Files
0021
0022 Revision Information
0023 ====================
0024
0025 November 30, 2007: Rev 1.0 - Initial version
0026
0027 I - Software License for Firmware
0028 =================================
0029
0030 Each firmware file comes with its own software license. For information on
0031 the particular license, please see the license text that is distributed with
0032 the firmware.
0033
0034 II - Microcode Availability
0035 ===========================
0036
0037 Firmware files are distributed through various channels. Some are available on
0038 http://opensource.freescale.com. For other firmware files, please contact
0039 your Freescale representative or your operating system vendor.
0040
0041 III - Description and Terminology
0042 =================================
0043
0044 In this document, the term 'microcode' refers to the sequence of 32-bit
0045 integers that compose the actual QE microcode.
0046
0047 The term 'firmware' refers to a binary blob that contains the microcode as
0048 well as other data that
0049
0050 1) describes the microcode's purpose
0051 2) describes how and where to upload the microcode
0052 3) specifies the values of various registers
0053 4) includes additional data for use by specific device drivers
0054
0055 Firmware files are binary files that contain only a firmware.
0056
0057 IV - Microcode Programming Details
0058 ===================================
0059
0060 The QE architecture allows for only one microcode present in I-RAM for each
0061 RISC processor. To replace any current microcode, a full QE reset (which
0062 disables the microcode) must be performed first.
0063
0064 QE microcode is uploaded using the following procedure:
0065
0066 1) The microcode is placed into I-RAM at a specific location, using the
0067 IRAM.IADD and IRAM.IDATA registers.
0068
0069 2) The CERCR.CIR bit is set to 0 or 1, depending on whether the firmware
0070 needs split I-RAM. Split I-RAM is only meaningful for SOCs that have
0071 QEs with multiple RISC processors, such as the 8360. Splitting the I-RAM
0072 allows each processor to run a different microcode, effectively creating an
0073 asymmetric multiprocessing (AMP) system.
0074
0075 3) The TIBCR trap registers are loaded with the addresses of the trap handlers
0076 in the microcode.
0077
0078 4) The RSP.ECCR register is programmed with the value provided.
0079
0080 5) If necessary, device drivers that need the virtual traps and extended mode
0081 data will use them.
0082
0083 Virtual Microcode Traps
0084
0085 These virtual traps are conditional branches in the microcode. These are
0086 "soft" provisional introduced in the ROMcode in order to enable higher
0087 flexibility and save h/w traps If new features are activated or an issue is
0088 being fixed in the RAM package utilizing they should be activated. This data
0089 structure signals the microcode which of these virtual traps is active.
0090
0091 This structure contains 6 words that the application should copy to some
0092 specific been defined. This table describes the structure::
0093
0094 ---------------------------------------------------------------
0095 | Offset in | | Destination Offset | Size of |
0096 | array | Protocol | within PRAM | Operand |
0097 --------------------------------------------------------------|
0098 | 0 | Ethernet | 0xF8 | 4 bytes |
0099 | | interworking | | |
0100 ---------------------------------------------------------------
0101 | 4 | ATM | 0xF8 | 4 bytes |
0102 | | interworking | | |
0103 ---------------------------------------------------------------
0104 | 8 | PPP | 0xF8 | 4 bytes |
0105 | | interworking | | |
0106 ---------------------------------------------------------------
0107 | 12 | Ethernet RX | 0x22 | 1 byte |
0108 | | Distributor Page | | |
0109 ---------------------------------------------------------------
0110 | 16 | ATM Globtal | 0x28 | 1 byte |
0111 | | Params Table | | |
0112 ---------------------------------------------------------------
0113 | 20 | Insert Frame | 0xF8 | 4 bytes |
0114 ---------------------------------------------------------------
0115
0116
0117 Extended Modes
0118
0119 This is a double word bit array (64 bits) that defines special functionality
0120 which has an impact on the software drivers. Each bit has its own impact
0121 and has special instructions for the s/w associated with it. This structure is
0122 described in this table::
0123
0124 -----------------------------------------------------------------------
0125 | Bit # | Name | Description |
0126 -----------------------------------------------------------------------
0127 | 0 | General | Indicates that prior to each host command |
0128 | | push command | given by the application, the software must |
0129 | | | assert a special host command (push command)|
0130 | | | CECDR = 0x00800000. |
0131 | | | CECR = 0x01c1000f. |
0132 -----------------------------------------------------------------------
0133 | 1 | UCC ATM | Indicates that after issuing ATM RX INIT |
0134 | | RX INIT | command, the host must issue another special|
0135 | | push command | command (push command) and immediately |
0136 | | | following that re-issue the ATM RX INIT |
0137 | | | command. (This makes the sequence of |
0138 | | | initializing the ATM receiver a sequence of |
0139 | | | three host commands) |
0140 | | | CECDR = 0x00800000. |
0141 | | | CECR = 0x01c1000f. |
0142 -----------------------------------------------------------------------
0143 | 2 | Add/remove | Indicates that following the specific host |
0144 | | command | command: "Add/Remove entry in Hash Lookup |
0145 | | validation | Table" used in Interworking setup, the user |
0146 | | | must issue another command. |
0147 | | | CECDR = 0xce000003. |
0148 | | | CECR = 0x01c10f58. |
0149 -----------------------------------------------------------------------
0150 | 3 | General push | Indicates that the s/w has to initialize |
0151 | | command | some pointers in the Ethernet thread pages |
0152 | | | which are used when Header Compression is |
0153 | | | activated. The full details of these |
0154 | | | pointers is located in the software drivers.|
0155 -----------------------------------------------------------------------
0156 | 4 | General push | Indicates that after issuing Ethernet TX |
0157 | | command | INIT command, user must issue this command |
0158 | | | for each SNUM of Ethernet TX thread. |
0159 | | | CECDR = 0x00800003. |
0160 | | | CECR = 0x7'b{0}, 8'b{Enet TX thread SNUM}, |
0161 | | | 1'b{1}, 12'b{0}, 4'b{1} |
0162 -----------------------------------------------------------------------
0163 | 5 - 31 | N/A | Reserved, set to zero. |
0164 -----------------------------------------------------------------------
0165
0166 V - Firmware Structure Layout
0167 ==============================
0168
0169 QE microcode from Freescale is typically provided as a header file. This
0170 header file contains macros that define the microcode binary itself as well as
0171 some other data used in uploading that microcode. The format of these files
0172 do not lend themselves to simple inclusion into other code. Hence,
0173 the need for a more portable format. This section defines that format.
0174
0175 Instead of distributing a header file, the microcode and related data are
0176 embedded into a binary blob. This blob is passed to the qe_upload_firmware()
0177 function, which parses the blob and performs everything necessary to upload
0178 the microcode.
0179
0180 All integers are big-endian. See the comments for function
0181 qe_upload_firmware() for up-to-date implementation information.
0182
0183 This structure supports versioning, where the version of the structure is
0184 embedded into the structure itself. To ensure forward and backwards
0185 compatibility, all versions of the structure must use the same 'qe_header'
0186 structure at the beginning.
0187
0188 'header' (type: struct qe_header):
0189 The 'length' field is the size, in bytes, of the entire structure,
0190 including all the microcode embedded in it, as well as the CRC (if
0191 present).
0192
0193 The 'magic' field is an array of three bytes that contains the letters
0194 'Q', 'E', and 'F'. This is an identifier that indicates that this
0195 structure is a QE Firmware structure.
0196
0197 The 'version' field is a single byte that indicates the version of this
0198 structure. If the layout of the structure should ever need to be
0199 changed to add support for additional types of microcode, then the
0200 version number should also be changed.
0201
0202 The 'id' field is a null-terminated string(suitable for printing) that
0203 identifies the firmware.
0204
0205 The 'count' field indicates the number of 'microcode' structures. There
0206 must be one and only one 'microcode' structure for each RISC processor.
0207 Therefore, this field also represents the number of RISC processors for this
0208 SOC.
0209
0210 The 'soc' structure contains the SOC numbers and revisions used to match
0211 the microcode to the SOC itself. Normally, the microcode loader should
0212 check the data in this structure with the SOC number and revisions, and
0213 only upload the microcode if there's a match. However, this check is not
0214 made on all platforms.
0215
0216 Although it is not recommended, you can specify '0' in the soc.model
0217 field to skip matching SOCs altogether.
0218
0219 The 'model' field is a 16-bit number that matches the actual SOC. The
0220 'major' and 'minor' fields are the major and minor revision numbers,
0221 respectively, of the SOC.
0222
0223 For example, to match the 8323, revision 1.0::
0224
0225 soc.model = 8323
0226 soc.major = 1
0227 soc.minor = 0
0228
0229 'padding' is necessary for structure alignment. This field ensures that the
0230 'extended_modes' field is aligned on a 64-bit boundary.
0231
0232 'extended_modes' is a bitfield that defines special functionality which has an
0233 impact on the device drivers. Each bit has its own impact and has special
0234 instructions for the driver associated with it. This field is stored in
0235 the QE library and available to any driver that calles qe_get_firmware_info().
0236
0237 'vtraps' is an array of 8 words that contain virtual trap values for each
0238 virtual traps. As with 'extended_modes', this field is stored in the QE
0239 library and available to any driver that calles qe_get_firmware_info().
0240
0241 'microcode' (type: struct qe_microcode):
0242 For each RISC processor there is one 'microcode' structure. The first
0243 'microcode' structure is for the first RISC, and so on.
0244
0245 The 'id' field is a null-terminated string suitable for printing that
0246 identifies this particular microcode.
0247
0248 'traps' is an array of 16 words that contain hardware trap values
0249 for each of the 16 traps. If trap[i] is 0, then this particular
0250 trap is to be ignored (i.e. not written to TIBCR[i]). The entire value
0251 is written as-is to the TIBCR[i] register, so be sure to set the EN
0252 and T_IBP bits if necessary.
0253
0254 'eccr' is the value to program into the ECCR register.
0255
0256 'iram_offset' is the offset into IRAM to start writing the
0257 microcode.
0258
0259 'count' is the number of 32-bit words in the microcode.
0260
0261 'code_offset' is the offset, in bytes, from the beginning of this
0262 structure where the microcode itself can be found. The first
0263 microcode binary should be located immediately after the 'microcode'
0264 array.
0265
0266 'major', 'minor', and 'revision' are the major, minor, and revision
0267 version numbers, respectively, of the microcode. If all values are 0,
0268 then these fields are ignored.
0269
0270 'reserved' is necessary for structure alignment. Since 'microcode'
0271 is an array, the 64-bit 'extended_modes' field needs to be aligned
0272 on a 64-bit boundary, and this can only happen if the size of
0273 'microcode' is a multiple of 8 bytes. To ensure that, we add
0274 'reserved'.
0275
0276 After the last microcode is a 32-bit CRC. It can be calculated using
0277 this algorithm::
0278
0279 u32 crc32(const u8 *p, unsigned int len)
0280 {
0281 unsigned int i;
0282 u32 crc = 0;
0283
0284 while (len--) {
0285 crc ^= *p++;
0286 for (i = 0; i < 8; i++)
0287 crc = (crc >> 1) ^ ((crc & 1) ? 0xedb88320 : 0);
0288 }
0289 return crc;
0290 }
0291
0292 VI - Sample Code for Creating Firmware Files
0293 ============================================
0294
0295 A Python program that creates firmware binaries from the header files normally
0296 distributed by Freescale can be found on http://opensource.freescale.com.
