qe_firmware.rst (13163B)
1========================================= 2Freescale QUICC Engine Firmware Uploading 3========================================= 4 5(c) 2007 Timur Tabi <timur at freescale.com>, 6 Freescale Semiconductor 7 8.. Table of Contents 9 10 I - Software License for Firmware 11 12 II - Microcode Availability 13 14 III - Description and Terminology 15 16 IV - Microcode Programming Details 17 18 V - Firmware Structure Layout 19 20 VI - Sample Code for Creating Firmware Files 21 22Revision Information 23==================== 24 25November 30, 2007: Rev 1.0 - Initial version 26 27I - Software License for Firmware 28================================= 29 30Each firmware file comes with its own software license. For information on 31the particular license, please see the license text that is distributed with 32the firmware. 33 34II - Microcode Availability 35=========================== 36 37Firmware files are distributed through various channels. Some are available on 38http://opensource.freescale.com. For other firmware files, please contact 39your Freescale representative or your operating system vendor. 40 41III - Description and Terminology 42================================= 43 44In this document, the term 'microcode' refers to the sequence of 32-bit 45integers that compose the actual QE microcode. 46 47The term 'firmware' refers to a binary blob that contains the microcode as 48well as other data that 49 50 1) describes the microcode's purpose 51 2) describes how and where to upload the microcode 52 3) specifies the values of various registers 53 4) includes additional data for use by specific device drivers 54 55Firmware files are binary files that contain only a firmware. 56 57IV - Microcode Programming Details 58=================================== 59 60The QE architecture allows for only one microcode present in I-RAM for each 61RISC processor. To replace any current microcode, a full QE reset (which 62disables the microcode) must be performed first. 63 64QE microcode is uploaded using the following procedure: 65 661) The microcode is placed into I-RAM at a specific location, using the 67 IRAM.IADD and IRAM.IDATA registers. 68 692) The CERCR.CIR bit is set to 0 or 1, depending on whether the firmware 70 needs split I-RAM. Split I-RAM is only meaningful for SOCs that have 71 QEs with multiple RISC processors, such as the 8360. Splitting the I-RAM 72 allows each processor to run a different microcode, effectively creating an 73 asymmetric multiprocessing (AMP) system. 74 753) The TIBCR trap registers are loaded with the addresses of the trap handlers 76 in the microcode. 77 784) The RSP.ECCR register is programmed with the value provided. 79 805) If necessary, device drivers that need the virtual traps and extended mode 81 data will use them. 82 83Virtual Microcode Traps 84 85These virtual traps are conditional branches in the microcode. These are 86"soft" provisional introduced in the ROMcode in order to enable higher 87flexibility and save h/w traps If new features are activated or an issue is 88being fixed in the RAM package utilizing they should be activated. This data 89structure signals the microcode which of these virtual traps is active. 90 91This structure contains 6 words that the application should copy to some 92specific been defined. This table describes the structure:: 93 94 --------------------------------------------------------------- 95 | Offset in | | Destination Offset | Size of | 96 | array | Protocol | within PRAM | Operand | 97 --------------------------------------------------------------| 98 | 0 | Ethernet | 0xF8 | 4 bytes | 99 | | interworking | | | 100 --------------------------------------------------------------- 101 | 4 | ATM | 0xF8 | 4 bytes | 102 | | interworking | | | 103 --------------------------------------------------------------- 104 | 8 | PPP | 0xF8 | 4 bytes | 105 | | interworking | | | 106 --------------------------------------------------------------- 107 | 12 | Ethernet RX | 0x22 | 1 byte | 108 | | Distributor Page | | | 109 --------------------------------------------------------------- 110 | 16 | ATM Globtal | 0x28 | 1 byte | 111 | | Params Table | | | 112 --------------------------------------------------------------- 113 | 20 | Insert Frame | 0xF8 | 4 bytes | 114 --------------------------------------------------------------- 115 116 117Extended Modes 118 119This is a double word bit array (64 bits) that defines special functionality 120which has an impact on the software drivers. Each bit has its own impact 121and has special instructions for the s/w associated with it. This structure is 122described in this table:: 123 124 ----------------------------------------------------------------------- 125 | Bit # | Name | Description | 126 ----------------------------------------------------------------------- 127 | 0 | General | Indicates that prior to each host command | 128 | | push command | given by the application, the software must | 129 | | | assert a special host command (push command)| 130 | | | CECDR = 0x00800000. | 131 | | | CECR = 0x01c1000f. | 132 ----------------------------------------------------------------------- 133 | 1 | UCC ATM | Indicates that after issuing ATM RX INIT | 134 | | RX INIT | command, the host must issue another special| 135 | | push command | command (push command) and immediately | 136 | | | following that re-issue the ATM RX INIT | 137 | | | command. (This makes the sequence of | 138 | | | initializing the ATM receiver a sequence of | 139 | | | three host commands) | 140 | | | CECDR = 0x00800000. | 141 | | | CECR = 0x01c1000f. | 142 ----------------------------------------------------------------------- 143 | 2 | Add/remove | Indicates that following the specific host | 144 | | command | command: "Add/Remove entry in Hash Lookup | 145 | | validation | Table" used in Interworking setup, the user | 146 | | | must issue another command. | 147 | | | CECDR = 0xce000003. | 148 | | | CECR = 0x01c10f58. | 149 ----------------------------------------------------------------------- 150 | 3 | General push | Indicates that the s/w has to initialize | 151 | | command | some pointers in the Ethernet thread pages | 152 | | | which are used when Header Compression is | 153 | | | activated. The full details of these | 154 | | | pointers is located in the software drivers.| 155 ----------------------------------------------------------------------- 156 | 4 | General push | Indicates that after issuing Ethernet TX | 157 | | command | INIT command, user must issue this command | 158 | | | for each SNUM of Ethernet TX thread. | 159 | | | CECDR = 0x00800003. | 160 | | | CECR = 0x7'b{0}, 8'b{Enet TX thread SNUM}, | 161 | | | 1'b{1}, 12'b{0}, 4'b{1} | 162 ----------------------------------------------------------------------- 163 | 5 - 31 | N/A | Reserved, set to zero. | 164 ----------------------------------------------------------------------- 165 166V - Firmware Structure Layout 167============================== 168 169QE microcode from Freescale is typically provided as a header file. This 170header file contains macros that define the microcode binary itself as well as 171some other data used in uploading that microcode. The format of these files 172do not lend themselves to simple inclusion into other code. Hence, 173the need for a more portable format. This section defines that format. 174 175Instead of distributing a header file, the microcode and related data are 176embedded into a binary blob. This blob is passed to the qe_upload_firmware() 177function, which parses the blob and performs everything necessary to upload 178the microcode. 179 180All integers are big-endian. See the comments for function 181qe_upload_firmware() for up-to-date implementation information. 182 183This structure supports versioning, where the version of the structure is 184embedded into the structure itself. To ensure forward and backwards 185compatibility, all versions of the structure must use the same 'qe_header' 186structure at the beginning. 187 188'header' (type: struct qe_header): 189 The 'length' field is the size, in bytes, of the entire structure, 190 including all the microcode embedded in it, as well as the CRC (if 191 present). 192 193 The 'magic' field is an array of three bytes that contains the letters 194 'Q', 'E', and 'F'. This is an identifier that indicates that this 195 structure is a QE Firmware structure. 196 197 The 'version' field is a single byte that indicates the version of this 198 structure. If the layout of the structure should ever need to be 199 changed to add support for additional types of microcode, then the 200 version number should also be changed. 201 202The 'id' field is a null-terminated string(suitable for printing) that 203identifies the firmware. 204 205The 'count' field indicates the number of 'microcode' structures. There 206must be one and only one 'microcode' structure for each RISC processor. 207Therefore, this field also represents the number of RISC processors for this 208SOC. 209 210The 'soc' structure contains the SOC numbers and revisions used to match 211the microcode to the SOC itself. Normally, the microcode loader should 212check the data in this structure with the SOC number and revisions, and 213only upload the microcode if there's a match. However, this check is not 214made on all platforms. 215 216Although it is not recommended, you can specify '0' in the soc.model 217field to skip matching SOCs altogether. 218 219The 'model' field is a 16-bit number that matches the actual SOC. The 220'major' and 'minor' fields are the major and minor revision numbers, 221respectively, of the SOC. 222 223For example, to match the 8323, revision 1.0:: 224 225 soc.model = 8323 226 soc.major = 1 227 soc.minor = 0 228 229'padding' is necessary for structure alignment. This field ensures that the 230'extended_modes' field is aligned on a 64-bit boundary. 231 232'extended_modes' is a bitfield that defines special functionality which has an 233impact on the device drivers. Each bit has its own impact and has special 234instructions for the driver associated with it. This field is stored in 235the QE library and available to any driver that calles qe_get_firmware_info(). 236 237'vtraps' is an array of 8 words that contain virtual trap values for each 238virtual traps. As with 'extended_modes', this field is stored in the QE 239library and available to any driver that calles qe_get_firmware_info(). 240 241'microcode' (type: struct qe_microcode): 242 For each RISC processor there is one 'microcode' structure. The first 243 'microcode' structure is for the first RISC, and so on. 244 245 The 'id' field is a null-terminated string suitable for printing that 246 identifies this particular microcode. 247 248 'traps' is an array of 16 words that contain hardware trap values 249 for each of the 16 traps. If trap[i] is 0, then this particular 250 trap is to be ignored (i.e. not written to TIBCR[i]). The entire value 251 is written as-is to the TIBCR[i] register, so be sure to set the EN 252 and T_IBP bits if necessary. 253 254 'eccr' is the value to program into the ECCR register. 255 256 'iram_offset' is the offset into IRAM to start writing the 257 microcode. 258 259 'count' is the number of 32-bit words in the microcode. 260 261 'code_offset' is the offset, in bytes, from the beginning of this 262 structure where the microcode itself can be found. The first 263 microcode binary should be located immediately after the 'microcode' 264 array. 265 266 'major', 'minor', and 'revision' are the major, minor, and revision 267 version numbers, respectively, of the microcode. If all values are 0, 268 then these fields are ignored. 269 270 'reserved' is necessary for structure alignment. Since 'microcode' 271 is an array, the 64-bit 'extended_modes' field needs to be aligned 272 on a 64-bit boundary, and this can only happen if the size of 273 'microcode' is a multiple of 8 bytes. To ensure that, we add 274 'reserved'. 275 276After the last microcode is a 32-bit CRC. It can be calculated using 277this algorithm:: 278 279 u32 crc32(const u8 *p, unsigned int len) 280 { 281 unsigned int i; 282 u32 crc = 0; 283 284 while (len--) { 285 crc ^= *p++; 286 for (i = 0; i < 8; i++) 287 crc = (crc >> 1) ^ ((crc & 1) ? 0xedb88320 : 0); 288 } 289 return crc; 290 } 291 292VI - Sample Code for Creating Firmware Files 293============================================ 294 295A Python program that creates firmware binaries from the header files normally 296distributed by Freescale can be found on http://opensource.freescale.com.