요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
1
=========================================
2
Freescale QUICC Engine Firmware Uploading
3
=========================================
5
(c) 2007 Timur Tabi <timur at freescale.com>,
6
Freescale Semiconductor
8
.. Table of Contents
10
I - Software License for Firmware
12
II - Microcode Availability
14
III - Description and Terminology
16
IV - Microcode Programming Details
18
V - Firmware Structure Layout
20
VI - Sample Code for Creating Firmware Files
22
Revision Information
23
====================
25
November 30, 2007: Rev 1.0 - Initial version
27
I - Software License for Firmware
28
=================================
30
Each firmware file comes with its own software license. For information on
31
the particular license, please see the license text that is distributed with
32
the firmware.
34
II - Microcode Availability
35
===========================
37
Firmware files are distributed through various channels. Some are available on
38
http://opensource.freescale.com. For other firmware files, please contact
39
your Freescale representative or your operating system vendor.
41
III - Description and Terminology
42
=================================
44
In this document, the term 'microcode' refers to the sequence of 32-bit
45
integers that compose the actual QE microcode.
47
The term 'firmware' refers to a binary blob that contains the microcode as
48
well as other data that
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
55
Firmware files are binary files that contain only a firmware.
57
IV - Microcode Programming Details
58
===================================
60
The QE architecture allows for only one microcode present in I-RAM for each
61
RISC processor. To replace any current microcode, a full QE reset (which
62
disables the microcode) must be performed first.
64
QE microcode is uploaded using the following procedure:
66
1) The microcode is placed into I-RAM at a specific location, using the
67
IRAM.IADD and IRAM.IDATA registers.
69
2) 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.
75
3) The TIBCR trap registers are loaded with the addresses of the trap handlers
76
in the microcode.
78
4) The RSP.ECCR register is programmed with the value provided.
80
5) If necessary, device drivers that need the virtual traps and extended mode
81
data will use them.
83
Virtual Microcode Traps
85
These virtual traps are conditional branches in the microcode. These are
86
"soft" provisional introduced in the ROMcode in order to enable higher
87
flexibility and save h/w traps If new features are activated or an issue is
88
being fixed in the RAM package utilizing they should be activated. This data
89
structure signals the microcode which of these virtual traps is active.
91
This structure contains 6 words that the application should copy to some
92
specific been defined. This table describes the structure::
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
---------------------------------------------------------------
117
Extended Modes
119
This is a double word bit array (64 bits) that defines special functionality
120
which has an impact on the software drivers. Each bit has its own impact
121
and has special instructions for the s/w associated with it. This structure is
122
described in this table::
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
-----------------------------------------------------------------------
166
V - Firmware Structure Layout
167
==============================
169
QE microcode from Freescale is typically provided as a header file. This
170
header file contains macros that define the microcode binary itself as well as
171
some other data used in uploading that microcode. The format of these files
172
do not lend themselves to simple inclusion into other code. Hence,
173
the need for a more portable format. This section defines that format.
175
Instead of distributing a header file, the microcode and related data are
176
embedded into a binary blob. This blob is passed to the qe_upload_firmware()
177
function, which parses the blob and performs everything necessary to upload
178
the microcode.
180
All integers are big-endian. See the comments for function
181
qe_upload_firmware() for up-to-date implementation information.
183
This structure supports versioning, where the version of the structure is
184
embedded into the structure itself. To ensure forward and backwards
185
compatibility, all versions of the structure must use the same 'qe_header'
186
structure at the beginning.
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).
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.
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.
202
The 'id' field is a null-terminated string(suitable for printing) that
203
identifies the firmware.
205
The 'count' field indicates the number of 'microcode' structures. There
206
must be one and only one 'microcode' structure for each RISC processor.
207
Therefore, this field also represents the number of RISC processors for this
208
SOC.
210
The 'soc' structure contains the SOC numbers and revisions used to match
211
the microcode to the SOC itself. Normally, the microcode loader should
212
check the data in this structure with the SOC number and revisions, and
213
only upload the microcode if there's a match. However, this check is not
214
made on all platforms.
216
Although it is not recommended, you can specify '0' in the soc.model
217
field to skip matching SOCs altogether.
219
The '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,
221
respectively, of the SOC.
223
For example, to match the 8323, revision 1.0::
225
soc.model = 8323
226
soc.major = 1
227
soc.minor = 0
229
'padding' is necessary for structure alignment. This field ensures that the
230
'extended_modes' field is aligned on a 64-bit boundary.
232
'extended_modes' is a bitfield that defines special functionality which has an
233
impact on the device drivers. Each bit has its own impact and has special
234
instructions for the driver associated with it. This field is stored in
235
the QE library and available to any driver that calls qe_get_firmware_info().
237
'vtraps' is an array of 8 words that contain virtual trap values for each
238
virtual traps. As with 'extended_modes', this field is stored in the QE
239
library and available to any driver that calls qe_get_firmware_info().
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.
245
The 'id' field is a null-terminated string suitable for printing that
246
identifies this particular microcode.
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.
254
'eccr' is the value to program into the ECCR register.
256
'iram_offset' is the offset into IRAM to start writing the
257
microcode.
259
'count' is the number of 32-bit words in the microcode.
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.
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.
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'.
276
After the last microcode is a 32-bit CRC. It can be calculated using
277
this algorithm::
279
u32 crc32(const u8 *p, unsigned int len)
280
{
281
unsigned int i;
282
u32 crc = 0;
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
}
292
VI - Sample Code for Creating Firmware Files
293
============================================
295
A Python program that creates firmware binaries from the header files normally
296
distributed by Freescale can be found on http://opensource.freescale.com.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
Freescale QUICC Engine firmware upload
1-26이 문서는 Freescale QUICC Engine(QE) firmware의 license, microcode 배포, programming 절차, binary layout과 firmware file 생성 방식을 설명합니다.
저작권 표기는 2007년 Timur Tabi와 Freescale Semiconductor이며, 문서 revision은 2007-11-30의 Rev 1.0 initial version입니다.
- 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
Firmware software license
27-33각 firmware file에는 고유한 software license가 함께 제공됩니다. 구체적인 license 조건은 firmware와 함께 배포되는 license text를 확인해야 합니다.
Microcode 배포 경로
34-40Firmware file은 여러 channel로 배포됩니다. 일부는 Freescale open-source site에서 제공되며, 나머지는 Freescale 담당자나 operating system vendor에게 문의해야 합니다.
Microcode와 firmware 용어
41-56이 문서에서 microcode는 실제 QE microcode를 이루는 32-bit integer sequence를 뜻합니다.
Firmware는 microcode와 함께 목적, upload 위치와 방법, 여러 register 값, 특정 device driver가 사용할 추가 data를 담는 binary blob입니다. Firmware file은 이 firmware 하나만 포함하는 binary file입니다.
- Microcode의 목적 설명
- Microcode를 upload할 위치와 방법 설명
- 여러 register에 설정할 값 지정
- 특정 device driver가 사용할 추가 data 포함
QE microcode programming 절차
57-82QE architecture에서는 RISC processor마다 I-RAM에 microcode 하나만 존재할 수 있습니다. 현재 microcode를 교체하려면 먼저 full QE reset을 수행하여 microcode를 disable해야 합니다.
- `IRAM.IADD`와 `IRAM.IDATA` register로 지정 위치의 I-RAM에 microcode를 기록합니다.
- Firmware가 split I-RAM을 요구하는지에 따라 `CERCR.CIR` bit를 0 또는 1로 설정합니다.
- Microcode trap handler address로 `TIBCR` trap register를 채웁니다.
- 제공된 값으로 `RSP.ECCR` register를 program합니다.
- 필요한 device driver가 virtual trap과 extended-mode data를 사용합니다.
Split I-RAM은 8360처럼 여러 RISC processor가 있는 QE SoC에서만 의미가 있습니다. I-RAM을 나누면 processor마다 다른 microcode를 실행할 수 있어 asymmetric multiprocessing(AMP) system이 됩니다.
Full QE reset→`IRAM.IADD`/`IRAM.IDATA`→`CERCR.CIR`→`TIBCR[]`→`RSP.ECCR`→Driver data 사용
Reset 뒤 I-RAM, split mode, trap register와 ECCR을 차례로 구성합니다.
I-RAM partition A→RISC 0→Microcode A
I-RAM partition B→RISC 1→Microcode B
Microcode A + B→Asymmetric multiprocessing
여러 RISC processor가 각자 다른 microcode image를 실행할 수 있습니다.
Virtual microcode traps
83-116Virtual trap은 microcode 안의 conditional branch입니다. ROM code에 software provision으로 도입되어 hardware trap을 절약하면서 유연성을 높입니다. RAM package에서 새 기능을 활성화하거나 문제를 수정할 때 해당 trap을 활성화하며, 이 data structure가 어떤 virtual trap이 active인지 microcode에 알립니다.
Application은 6개 word를 정의된 protocol RAM(PRAM) 위치로 복사합니다. 원문의 offset, protocol, destination offset과 operand 크기는 다음과 같습니다.
Array offsetProtocolPRAM destinationOperand size
0Ethernet interworking`0xF8`4 bytes
4ATM interworking`0xF8`4 bytes
8PPP interworking`0xF8`4 bytes
12Ethernet RX Distributor Page`0x22`1 byte
16ATM Global Params Table`0x28`1 byte
20Insert Frame`0xF8`4 bytes
6개 word의 array offset과 protocol별 PRAM destination을 보존했습니다.
Extended modes
117-165Extended mode는 software driver 동작에 영향을 주는 special functionality를 정의하는 double-word 64-bit bit array입니다. 각 bit에는 별도의 영향과 관련 software가 따라야 할 instruction이 있습니다.
BitNameDescription
0General push commandApplication의 각 host command 전에 `CECDR = 0x00800000`, `CECR = 0x01c1000f` push command 실행
1UCC ATM RX INIT push commandATM RX INIT 뒤 push command를 실행하고 ATM RX INIT를 즉시 다시 실행하여 3-command sequence 구성
2Add/remove command validationInterworking의 `Add/Remove entry in Hash Lookup Table` 뒤 `CECDR = 0xce000003`, `CECR = 0x01c10f58` 실행
3General push commandHeader Compression에서 사용하는 Ethernet thread page pointer를 software가 초기화
4General push commandEthernet TX INIT 뒤 각 Ethernet TX thread SNUM에 대해 지정 command 실행
5-31N/AReserved이며 0으로 설정
원문 bit table의 command sequence와 reserved 범위를 구조화했습니다.
Bit 4의 `CECR` 값은 원문 표기인 `7'b{0}, 8'b{Enet TX thread SNUM}, 1'b{1}, 12'b{0}, 4'b{1}`을 그대로 사용합니다.
Portable firmware binary layout
166-187Freescale QE microcode는 보통 microcode binary와 upload용 data를 macro로 정의한 header file로 제공되지만, 이 형식은 다른 code에 간단히 포함하기 어렵습니다. 따라서 microcode와 관련 data를 portable binary blob에 내장합니다.
Blob은 `qe_upload_firmware()`에 전달됩니다. 이 함수가 blob을 parse하고 microcode upload에 필요한 모든 작업을 수행합니다. 모든 integer는 big-endian입니다. 최신 구현 정보는 `qe_upload_firmware()`의 comment를 확인해야 합니다.
Structure 자체에 version을 넣어 versioning을 지원합니다. Forward/backward compatibility를 위해 모든 version은 시작 부분에 같은 `qe_header` structure를 사용해야 합니다.
`qe_header`→`qe_microcode[0..count-1]`→Microcode binaries→32-bit CRC
공통 header 뒤 RISC별 microcode descriptor와 binary, 마지막 CRC가 이어집니다.
struct qe_header
188-240| Field | 의미 |
|---|---|
| `length` | Embedded microcode와 선택적 CRC를 포함한 전체 structure의 byte 크기 |
| `magic` | QE Firmware structure를 식별하는 3-byte 배열 `Q`, `E`, `F` |
| `version` | Structure layout version |
| `id` | Firmware를 식별하는 null-terminated printable string |
| `count` | `microcode` structure 수이며 SoC의 RISC processor 수와 동일 |
| `soc` | Microcode와 SoC model/revision을 matching하기 위한 정보 |
| `soc.model` | 16-bit SoC number. `0`이면 SoC matching 전체를 건너뜀 |
| `soc.major`, `soc.minor` | SoC major/minor revision |
| `padding` | `extended_modes`를 64-bit boundary에 align |
| `extended_modes` | Driver 동작에 영향을 주는 64-bit special-function bitfield |
| `vtraps` | Virtual trap 값을 담는 8-word 배열 |
`count`는 RISC processor마다 정확히 하나 존재해야 하는 `microcode` structure 수입니다. 따라서 SoC의 RISC processor 수도 나타냅니다.
`soc` 정보는 microcode와 실제 SoC number 및 revision을 대조하는 데 사용합니다. Loader는 보통 match될 때만 upload하지만 모든 platform이 이 검사를 수행하는 것은 아닙니다. 권장되지는 않지만 `soc.model = 0`으로 전체 SoC matching을 건너뛸 수 있습니다.
8323 revision 1.0을 match하는 예입니다.
soc.model = 8323
soc.major = 1
soc.minor = 0`extended_modes`와 `vtraps`는 QE library에 저장되며 `qe_get_firmware_info()`를 호출하는 driver가 사용할 수 있습니다.
struct qe_microcode
241-275RISC processor마다 `microcode` structure 하나를 두며 array 순서가 RISC processor 순서와 대응합니다.
| Field | 의미 |
|---|---|
| `id` | 해당 microcode를 식별하는 null-terminated printable string |
| `traps[16]` | 16개 hardware trap 값. 0인 entry는 `TIBCR[i]`에 쓰지 않음 |
| `eccr` | `ECCR` register에 program할 값 |
| `iram_offset` | Microcode 기록을 시작할 IRAM offset |
| `count` | Microcode의 32-bit word 수 |
| `code_offset` | Structure 시작부터 microcode binary까지의 byte offset |
| `major`, `minor`, `revision` | Microcode version. 모두 0이면 무시 |
| `reserved` | Array element 크기를 8-byte 배수로 만들어 64-bit field alignment 보장 |
`traps[i]`가 0이면 해당 trap은 무시하여 `TIBCR[i]`에 쓰지 않습니다. 0이 아니면 전체 값을 그대로 기록하므로 필요할 때 `EN`과 `T_IBP` bit도 설정해야 합니다.
첫 microcode binary는 `microcode` descriptor array 바로 뒤에 있어야 합니다. `reserved` field는 각 descriptor 크기를 8-byte 배수로 만들어 이후 64-bit `extended_modes` alignment를 유지합니다.
Firmware CRC
276-291마지막 microcode 뒤에는 32-bit CRC가 위치합니다. CRC는 다음 원문 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;
}Firmware file 생성 sample
292-296Freescale이 배포하던 header file에서 firmware binary를 만드는 Python program은 Freescale open-source site에서 제공됩니다.
요약과 해설
qe_firmware.rst:1-296QE firmware는 RISC별 microcode와 trap, ECCR, driver metadata를 versioned binary blob으로 묶습니다. Loader는 reset 뒤 I-RAM과 register를 구성하며, 공통 `qe_header`, RISC별 `qe_microcode`, binary payload와 CRC 순서로 해석합니다.