qe_firmware.rst 13 KB

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