aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/powerpc
diff options
context:
space:
mode:
authorTimur Tabi <timur@freescale.com>2008-01-08 11:30:58 -0500
committerKumar Gala <galak@kernel.crashing.org>2008-01-23 20:34:06 -0500
commitbc556ba940085e46e0ab1b5ed7c31428dc86dd03 (patch)
tree68d8aada0531c5d5070c3e7327de606894584971 /Documentation/powerpc
parenta21e282a124f4679c040087ab73aa5b147d4275f (diff)
[POWERPC] QE: Add ability to upload QE firmware
Define the layout of a binary blob that contains a QE firmware and instructions on how to upload it. Add function qe_upload_firmware() to parse the blob and perform the actual upload. Fully define 'struct rsp' in immap_qe.h to include the actual RISC Special Registers. Added description of a new QE firmware node to booting-without-of.txt. Signed-off-by: Timur Tabi <timur@freescale.com> Signed-off-by: Kumar Gala <galak@kernel.crashing.org>
Diffstat (limited to 'Documentation/powerpc')
-rw-r--r--Documentation/powerpc/00-INDEX3
-rw-r--r--Documentation/powerpc/booting-without-of.txt33
-rw-r--r--Documentation/powerpc/qe_firmware.txt295
3 files changed, 329 insertions, 2 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
28 - info on sound support under Linux/PPC 28 - info on sound support under Linux/PPC
29zImage_layout.txt 29zImage_layout.txt
30 - info on the kernel images for Linux/PPC 30 - info on the kernel images for Linux/PPC
31qe_firmware.txt
32 - describes the layout of firmware binaries for the Freescale QUICC
33 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 f920c2459e89..e8c67c9015b3 100644
--- a/Documentation/powerpc/booting-without-of.txt
+++ b/Documentation/powerpc/booting-without-of.txt
@@ -52,7 +52,10 @@ Table of Contents
52 i) Freescale QUICC Engine module (QE) 52 i) Freescale QUICC Engine module (QE)
53 j) CFI or JEDEC memory-mapped NOR flash 53 j) CFI or JEDEC memory-mapped NOR flash
54 k) Global Utilities Block 54 k) Global Utilities Block
55 l) Xilinx IP cores 55 l) Freescale Communications Processor Module
56 m) Chipselect/Local Bus
57 n) 4xx/Axon EMAC ethernet nodes
58 o) Xilinx IP cores
56 59
57 VII - Specifying interrupt information for devices 60 VII - Specifying interrupt information for devices
58 1) interrupts property 61 1) interrupts property
@@ -1788,6 +1791,32 @@ platforms are moved over to use the flattened-device-tree model.
1788 }; 1791 };
1789 }; 1792 };
1790 1793
1794 viii) Uploaded QE firmware
1795
1796 If a new firwmare has been uploaded to the QE (usually by the
1797 boot loader), then a 'firmware' child node should be added to the QE
1798 node. This node provides information on the uploaded firmware that
1799 device drivers may need.
1800
1801 Required properties:
1802 - id: The string name of the firmware. This is taken from the 'id'
1803 member of the qe_firmware structure of the uploaded firmware.
1804 Device drivers can search this string to determine if the
1805 firmware they want is already present.
1806 - extended-modes: The Extended Modes bitfield, taken from the
1807 firmware binary. It is a 64-bit number represented
1808 as an array of two 32-bit numbers.
1809 - virtual-traps: The virtual traps, taken from the firmware binary.
1810 It is an array of 8 32-bit numbers.
1811
1812 Example:
1813
1814 firmware {
1815 id = "Soft-UART";
1816 extended-modes = <0 0>;
1817 virtual-traps = <0 0 0 0 0 0 0 0>;
1818 }
1819
1791 j) CFI or JEDEC memory-mapped NOR flash 1820 j) CFI or JEDEC memory-mapped NOR flash
1792 1821
1793 Flash chips (Memory Technology Devices) are often used for solid state 1822 Flash chips (Memory Technology Devices) are often used for solid state
@@ -2269,7 +2298,7 @@ platforms are moved over to use the flattened-device-tree model.
2269 available. 2298 available.
2270 For Axon: 0x0000012a 2299 For Axon: 0x0000012a
2271 2300
2272 l) Xilinx IP cores 2301 o) Xilinx IP cores
2273 2302
2274 The Xilinx EDK toolchain ships with a set of IP cores (devices) for use 2303 The Xilinx EDK toolchain ships with a set of IP cores (devices) for use
2275 in Xilinx Spartan and Virtex FPGAs. The devices cover the whole range 2304 in Xilinx Spartan and Virtex FPGAs. The devices cover the whole range
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 @@
1 Freescale QUICC Engine Firmware Uploading
2 -----------------------------------------
3
4(c) 2007 Timur Tabi <timur at freescale.com>,
5 Freescale Semiconductor
6
7Table of Contents
8=================
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 softwarew 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 numbrs,
221respectively, of the SOC.
222
223For example, to match the 8323, revision 1.0:
224 soc.model = 8323
225 soc.major = 1
226 soc.minor = 0
227
228'padding' is neccessary for structure alignment. This field ensures that the
229'extended_modes' field is aligned on a 64-bit boundary.
230
231'extended_modes' is a bitfield that defines special functionality which has an
232impact on the device drivers. Each bit has its own impact and has special
233instructions for the driver associated with it. This field is stored in
234the QE library and available to any driver that calles qe_get_firmware_info().
235
236'vtraps' is an array of 8 words that contain virtual trap values for each
237virtual traps. As with 'extended_modes', this field is stored in the QE
238library and available to any driver that calles qe_get_firmware_info().
239
240'microcode' (type: struct qe_microcode):
241 For each RISC processor there is one 'microcode' structure. The first
242 'microcode' structure is for the first RISC, and so on.
243
244 The 'id' field is a null-terminated string suitable for printing that
245 identifies this particular microcode.
246
247 'traps' is an array of 16 words that contain hardware trap values
248 for each of the 16 traps. If trap[i] is 0, then this particular
249 trap is to be ignored (i.e. not written to TIBCR[i]). The entire value
250 is written as-is to the TIBCR[i] register, so be sure to set the EN
251 and T_IBP bits if necessary.
252
253 'eccr' is the value to program into the ECCR register.
254
255 'iram_offset' is the offset into IRAM to start writing the
256 microcode.
257
258 'count' is the number of 32-bit words in the microcode.
259
260 'code_offset' is the offset, in bytes, from the beginning of this
261 structure where the microcode itself can be found. The first
262 microcode binary should be located immediately after the 'microcode'
263 array.
264
265 'major', 'minor', and 'revision' are the major, minor, and revision
266 version numbers, respectively, of the microcode. If all values are 0,
267 then these fields are ignored.
268
269 'reserved' is necessary for structure alignment. Since 'microcode'
270 is an array, the 64-bit 'extended_modes' field needs to be aligned
271 on a 64-bit boundary, and this can only happen if the size of
272 'microcode' is a multiple of 8 bytes. To ensure that, we add
273 'reserved'.
274
275After the last microcode is a 32-bit CRC. It can be calculated using
276this algorithm:
277
278u32 crc32(const u8 *p, unsigned int len)
279{
280 unsigned int i;
281 u32 crc = 0;
282
283 while (len--) {
284 crc ^= *p++;
285 for (i = 0; i < 8; i++)
286 crc = (crc >> 1) ^ ((crc & 1) ? 0xedb88320 : 0);
287 }
288 return crc;
289}
290
291VI - Sample Code for Creating Firmware Files
292============================================
293
294A Python program that creates firmware binaries from the header files normally
295distributed by Freescale can be found on http://opensource.freescale.com.