]> git.sur5r.net Git - u-boot/blob - doc/README.POST
Merge branch 'master' of git://git.denx.de/u-boot-mpc85xx
[u-boot] / doc / README.POST
1 Power-On-Self-Test support in U-Boot
2 ------------------------------------
3
4 This project is to support Power-On-Self-Test (POST) in U-Boot.
5
6 1. High-level requirements
7
8 The key requirements for this project are as follows:
9
10 1) The project shall develop a flexible framework for implementing
11    and running Power-On-Self-Test in U-Boot. This framework shall
12    possess the following features:
13
14    o) Extensibility
15
16       The framework shall allow adding/removing/replacing POST tests.
17       Also, standalone POST tests shall be supported.
18
19    o) Configurability
20
21       The framework shall allow run-time configuration of the lists
22       of tests running on normal/power-fail booting.
23
24    o) Controllability
25
26       The framework shall support manual running of the POST tests.
27
28 2) The results of tests shall be saved so that it will be possible to
29    retrieve them from Linux.
30
31 3) The following POST tests shall be developed for MPC823E-based
32    boards:
33
34    o) CPU test
35    o) Cache test
36    o) Memory test
37    o) Ethernet test
38    o) Serial channels test
39    o) Watchdog timer test
40    o) RTC test
41    o) I2C test
42    o) SPI test
43    o) USB test
44
45 4) The LWMON board shall be used for reference.
46
47 2. Design
48
49 This section details the key points of the design for the project.
50 The whole project can be divided into two independent tasks:
51 enhancing U-Boot/Linux to provide a common framework for running POST
52 tests and developing such tests for particular hardware.
53
54 2.1. Hardware-independent POST layer
55
56 A new optional module will be added to U-Boot, which will run POST
57 tests and collect their results at boot time. Also, U-Boot will
58 support running POST tests manually at any time by executing a
59 special command from the system console.
60
61 The list of available POST tests will be configured at U-Boot build
62 time. The POST layer will allow the developer to add any custom POST
63 tests. All POST tests will be divided into the following groups:
64
65   1) Tests running on power-on booting only
66
67      This group will contain those tests that run only once on
68      power-on reset (e.g. watchdog test)
69
70   2) Tests running on normal booting only
71
72      This group will contain those tests that do not take much
73      time and can be run on the regular basis (e.g. CPU test)
74
75   3) Tests running in special "slow test mode" only
76
77      This group will contain POST tests that consume much time
78      and cannot be run regularly (e.g. strong memory test, I2C test)
79
80   4) Manually executed tests
81
82      This group will contain those tests that can be run manually.
83
84 If necessary, some tests may belong to several groups simultaneously.
85 For example, SDRAM test may run in both normal and "slow test" mode.
86 In normal mode, SDRAM test may perform a fast superficial memory test
87 only, while running in slow test mode it may perform a full memory
88 check-up.
89
90 Also, all tests will be discriminated by the moment they run at.
91 Specifically, the following groups will be singled out:
92
93   1) Tests running before relocating to RAM
94
95      These tests will run immediately after initializing RAM
96      as to enable modifying it without taking care of its
97      contents. Basically, this group will contain memory tests
98      only.
99
100   2) Tests running after relocating to RAM
101
102      These tests will run immediately before entering the main
103      loop as to guarantee full hardware initialization.
104
105 The POST layer will also distinguish a special group of tests that
106 may cause system rebooting (e.g. watchdog test). For such tests, the
107 layer will automatically detect rebooting and will notify the test
108 about it.
109
110 2.1.1. POST layer interfaces
111
112 This section details the interfaces between the POST layer and the
113 rest of U-Boot.
114
115 The following flags will be defined:
116
117 #define POST_POWERON            0x01    /* test runs on power-on booting */
118 #define POST_NORMAL             0x02    /* test runs on normal booting */
119 #define POST_SLOWTEST           0x04    /* test is slow, enabled by key press */
120 #define POST_POWERTEST          0x08    /* test runs after watchdog reset */
121 #define POST_ROM                0x100   /* test runs in ROM */
122 #define POST_RAM                0x200   /* test runs in RAM */
123 #define POST_MANUAL             0x400   /* test can be executed manually */
124 #define POST_REBOOT             0x800   /* test may cause rebooting */
125 #define POST_PREREL             0x1000  /* test runs before relocation */
126
127 The POST layer will export the following interface routines:
128
129   o) int post_run(bd_t *bd, char *name, int flags);
130
131      This routine will run the test (or the group of tests) specified
132      by the name and flag arguments. More specifically, if the name
133      argument is not NULL, the test with this name will be performed,
134      otherwise all tests running in ROM/RAM (depending on the flag
135      argument) will be executed. This routine will be called at least
136      twice with name set to NULL, once from board_init_f() and once
137      from board_init_r(). The flags argument will also specify the
138      mode the test is executed in (power-on, normal, power-fail,
139      manual).
140
141   o) void post_reloc(ulong offset);
142
143      This routine will be called from board_init_r() and will
144      relocate the POST test table.
145
146   o) int post_info(char *name);
147
148      This routine will print the list of all POST tests that can be
149      executed manually if name is NULL, and the description of a
150      particular test if name is not NULL.
151
152   o) int post_log(char *format, ...);
153
154      This routine will be called from POST tests to log their
155      results. Basically, this routine will print the results to
156      stderr. The format of the arguments and the return value
157      will be identical to the printf() routine.
158
159 Also, the following board-specific routines will be called from the
160 U-Boot common code:
161
162   o) int board_power_mode(void)
163
164      This routine will return the mode the system is running in
165      (POST_POWERON, POST_NORMAL or POST_SHUTDOWN).
166
167   o) void board_poweroff(void)
168
169      This routine will turn off the power supply of the board. It
170      will be called on power-fail booting after running all POST
171      tests.
172
173   o) int post_hotkeys_pressed(gd_t *gd)
174
175      This routine will scan the keyboard to detect if a magic key
176      combination has been pressed, or otherwise detect if the
177      power-on long-running tests shall be executed or not ("normal"
178      versus "slow" test mode).
179
180 The list of available POST tests be kept in the post_tests array
181 filled at U-Boot build time. The format of entry in this array will
182 be as follows:
183
184 struct post_test {
185     char *name;
186     char *cmd;
187     char *desc;
188     int flags;
189     int (*test)(bd_t *bd, int flags);
190 };
191
192   o) name
193
194      This field will contain a short name of the test, which will be
195      used in logs and on listing POST tests (e.g. CPU test).
196
197   o) cmd
198
199      This field will keep a name for identifying the test on manual
200      testing (e.g. cpu). For more information, refer to section
201      "Command line interface".
202
203   o) desc
204
205      This field will contain a detailed description of the test,
206      which will be printed on user request. For more information, see
207      section "Command line interface".
208
209   o) flags
210
211      This field will contain a combination of the bit flags described
212      above, which will specify the mode the test is running in
213      (power-on, normal, power-fail or manual mode), the moment it
214      should be run at (before or after relocating to RAM), whether it
215      can cause system rebooting or not.
216
217   o) test
218
219      This field will contain a pointer to the routine that will
220      perform the test, which will take 2 arguments. The first
221      argument will be a pointer to the board info structure, while
222      the second will be a combination of bit flags specifying the
223      mode the test is running in (POST_POWERON, POST_NORMAL,
224      POST_SLOWTEST, POST_MANUAL) and whether the last execution of
225      the test caused system rebooting (POST_REBOOT). The routine will
226      return 0 on successful execution of the test, and 1 if the test
227      failed.
228
229 The lists of the POST tests that should be run at power-on/normal/
230 power-fail booting will be kept in the environment. Namely, the
231 following environment variables will be used: post_poweron,
232 powet_normal, post_slowtest.
233
234 2.1.2. Test results
235
236 The results of tests will be collected by the POST layer. The POST
237 log will have the following format:
238
239 ...
240 --------------------------------------------
241 START <name>
242 <test-specific output>
243 [PASSED|FAILED]
244 --------------------------------------------
245 ...
246
247 Basically, the results of tests will be printed to stderr. This
248 feature may be enhanced in future to spool the log to a serial line,
249 save it in non-volatile RAM (NVRAM), transfer it to a dedicated
250 storage server and etc.
251
252 2.1.3. Integration issues
253
254 All POST-related code will be #ifdef'ed with the CONFIG_POST macro.
255 This macro will be defined in the config_<board>.h file for those
256 boards that need POST. The CONFIG_POST macro will contain the list of
257 POST tests for the board. The macro will have the format of array
258 composed of post_test structures:
259
260 #define CONFIG_POST \
261         {
262                 "On-board peripherals test", "board", \
263                 "  This test performs full check-up of the " \
264                 "on-board hardware.", \
265                 POST_RAM | POST_SLOWTEST, \
266                 &board_post_test \
267         }
268
269 A new file, post.h, will be created in the include/ directory. This
270 file will contain common POST declarations and will define a set of
271 macros that will be reused for defining CONFIG_POST. As an example,
272 the following macro may be defined:
273
274 #define POST_CACHE \
275         {
276                 "Cache test", "cache", \
277                 "  This test verifies the CPU cache operation.", \
278                 POST_RAM | POST_NORMAL, \
279                 &cache_post_test \
280         }
281
282 A new subdirectory will be created in the U-Boot root directory. It
283 will contain the source code of the POST layer and most of POST
284 tests. Each POST test in this directory will be placed into a
285 separate file (it will be needed for building standalone tests). Some
286 POST tests (mainly those for testing peripheral devices) will be
287 located in the source files of the drivers for those devices. This
288 way will be used only if the test subtantially uses the driver.
289
290 2.1.4. Standalone tests
291
292 The POST framework will allow to develop and run standalone tests. A
293 user-space library will be developed to provide the POST interface
294 functions to standalone tests.
295
296 2.1.5. Command line interface
297
298 A new command, diag, will be added to U-Boot. This command will be
299 used for listing all available hardware tests, getting detailed
300 descriptions of them and running these tests.
301
302 More specifically, being run without any arguments, this command will
303 print the list of all available hardware tests:
304
305 => diag
306 Available hardware tests:
307   cache             - cache test
308   cpu               - CPU test
309   enet              - SCC/FCC ethernet test
310 Use 'diag [<test1> [<test2>]] ... ' to get more info.
311 Use 'diag run [<test1> [<test2>]] ... ' to run tests.
312 =>
313
314 If the first argument to the diag command is not 'run', detailed
315 descriptions of the specified tests will be printed:
316
317 => diag cpu cache
318 cpu - CPU test
319   This test verifies the arithmetic logic unit of CPU.
320 cache - cache test
321   This test verifies the CPU cache operation.
322 =>
323
324 If the first argument to diag is 'run', the specified tests will be
325 executed. If no tests are specified, all available tests will be
326 executed.
327
328 It will be prohibited to execute tests running in ROM manually. The
329 'diag' command will not display such tests and/or run them.
330
331 2.1.6. Power failure handling
332
333 The Linux kernel will be modified to detect power failures and
334 automatically reboot the system in such cases. It will be assumed
335 that the power failure causes a system interrupt.
336
337 To perform correct system shutdown, the kernel will register a
338 handler of the power-fail IRQ on booting. Being called, the handler
339 will run /sbin/reboot using the call_usermodehelper() routine.
340 /sbin/reboot will automatically bring the system down in a secure
341 way. This feature will be configured in/out from the kernel
342 configuration file.
343
344 The POST layer of U-Boot will check whether the system runs in
345 power-fail mode. If it does, the system will be powered off after
346 executing all hardware tests.
347
348 2.1.7. Hazardous tests
349
350 Some tests may cause system rebooting during their execution. For
351 some tests, this will indicate a failure, while for the Watchdog
352 test, this means successful operation of the timer.
353
354 In order to support such tests, the following scheme will be
355 implemented. All the tests that may cause system rebooting will have
356 the POST_REBOOT bit flag set in the flag field of the correspondent
357 post_test structure. Before starting tests marked with this bit flag,
358 the POST layer will store an identification number of the test in a
359 location in IMMR. On booting, the POST layer will check the value of
360 this variable and if it is set will skip over the tests preceding the
361 failed one. On second execution of the failed test, the POST_REBOOT
362 bit flag will be set in the flag argument to the test routine. This
363 will allow to detect system rebooting on the previous iteration. For
364 example, the watchdog timer test may have the following
365 declaration/body:
366
367 ...
368 #define POST_WATCHDOG \
369         {
370                 "Watchdog timer test", "watchdog", \
371                 "  This test checks the watchdog timer.", \
372                 POST_RAM | POST_POWERON | POST_REBOOT, \
373                 &watchdog_post_test \
374         }
375 ...
376
377 ...
378 int watchdog_post_test(bd_t *bd, int flags)
379 {
380         unsigned long start_time;
381
382         if (flags & POST_REBOOT) {
383                 /* Test passed */
384                 return 0;
385         } else {
386                 /* disable interrupts */
387                 disable_interrupts();
388                 /* 10-second delay */
389                 ...
390                 /* if we've reached this, the watchdog timer does not work */
391                 enable_interrupts();
392                 return 1;
393         }
394 }
395 ...
396
397 2.2. Hardware-specific details
398
399 This project will also develop a set of POST tests for MPC8xx- based
400 systems. This section provides technical details of how it will be
401 done.
402
403 2.2.1. Generic PPC tests
404
405 The following generic POST tests will be developed:
406
407   o) CPU test
408
409      This test will check the arithmetic logic unit (ALU) of CPU. The
410      test will take several milliseconds and will run on normal
411      booting.
412
413   o) Cache test
414
415      This test will verify the CPU cache (L1 cache). The test will
416      run on normal booting.
417
418   o) Memory test
419
420      This test will examine RAM and check it for errors. The test
421      will always run on booting. On normal booting, only a limited
422      amount of RAM will be checked. On power-fail booting a fool
423      memory check-up will be performed.
424
425 2.2.1.1. CPU test
426
427 This test will verify the following ALU instructions:
428
429   o) Condition register istructions
430
431      This group will contain: mtcrf, mfcr, mcrxr, crand, crandc,
432      cror, crorc, crxor, crnand, crnor, creqv, mcrf.
433
434      The mtcrf/mfcr instructions will be tested by loading different
435      values into the condition register (mtcrf), moving its value to
436      a general-purpose register (mfcr) and comparing this value with
437      the expected one. The mcrxr instruction will be tested by
438      loading a fixed value into the XER register (mtspr), moving XER
439      value to the condition register (mcrxr), moving it to a
440      general-purpose register (mfcr) and comparing the value of this
441      register with the expected one. The rest of instructions will be
442      tested by loading a fixed value into the condition register
443      (mtcrf), executing each instruction several times to modify all
444      4-bit condition fields, moving the value of the conditional
445      register to a general-purpose register (mfcr) and comparing it
446      with the expected one.
447
448   o) Integer compare instructions
449
450      This group will contain: cmp, cmpi, cmpl, cmpli.
451
452      To verify these instructions the test will run them with
453      different combinations of operands, read the condition register
454      value and compare it with the expected one. More specifically,
455      the test will contain a pre-built table containing the
456      description of each test case: the instruction, the values of
457      the operands, the condition field to save the result in and the
458      expected result.
459
460   o) Arithmetic instructions
461
462      This group will contain: add, addc, adde, addme, addze, subf,
463      subfc, subfe, subme, subze, mullw, mulhw, mulhwu, divw, divwu,
464      extsb, extsh.
465
466      The test will contain a pre-built table of instructions,
467      operands, expected results and expected states of the condition
468      register. For each table entry, the test will cyclically use
469      different sets of operand registers and result registers. For
470      example, for instructions that use 3 registers on the first
471      iteration r0/r1 will be used as operands and r2 for result. On
472      the second iteration, r1/r2 will be used as operands and r3 as
473      for result and so on. This will enable to verify all
474      general-purpose registers.
475
476   o) Logic instructions
477
478      This group will contain: and, andc, andi, andis, or, orc, ori,
479      oris, xor, xori, xoris, nand, nor, neg, eqv, cntlzw.
480
481      The test scheme will be identical to that from the previous
482      point.
483
484   o) Shift instructions
485
486      This group will contain: slw, srw, sraw, srawi, rlwinm, rlwnm,
487      rlwimi
488
489      The test scheme will be identical to that from the previous
490      point.
491
492   o) Branch instructions
493
494      This group will contain: b, bl, bc.
495
496      The first 2 instructions (b, bl) will be verified by jumping to
497      a fixed address and checking whether control was transfered to
498      that very point. For the bl instruction the value of the link
499      register will be checked as well (using mfspr). To verify the bc
500      instruction various combinations of the BI/BO fields, the CTR
501      and the condition register values will be checked. The list of
502      such combinations will be pre-built and linked in U-Boot at
503      build time.
504
505   o) Load/store instructions
506
507      This group will contain: lbz(x)(u), lhz(x)(u), lha(x)(u),
508      lwz(x)(u), stb(x)(u), sth(x)(u), stw(x)(u).
509
510      All operations will be performed on a 16-byte array. The array
511      will be 4-byte aligned. The base register will point to offset
512      8. The immediate offset (index register) will range in [-8 ...
513      +7]. The test cases will be composed so that they will not cause
514      alignment exceptions. The test will contain a pre-built table
515      describing all test cases. For store instructions, the table
516      entry will contain: the instruction opcode, the value of the
517      index register and the value of the source register. After
518      executing the instruction, the test will verify the contents of
519      the array and the value of the base register (it must change for
520      "store with update" instructions). For load instructions, the
521      table entry will contain: the instruction opcode, the array
522      contents, the value of the index register and the expected value
523      of the destination register. After executing the instruction,
524      the test will verify the value of the destination register and
525      the value of the base register (it must change for "load with
526      update" instructions).
527
528   o) Load/store multiple/string instructions
529
530
531 The CPU test will run in RAM in order to allow run-time modification
532 of the code to reduce the memory footprint.
533
534 2.2.1.2 Special-Purpose Registers Tests
535
536 TBD.
537
538 2.2.1.3. Cache test
539
540 To verify the data cache operation the following test scenarios will
541 be used:
542
543   1) Basic test #1
544
545     - turn on the data cache
546     - switch the data cache to write-back or write-through mode
547     - invalidate the data cache
548     - write the negative pattern to a cached area
549     - read the area
550
551     The negative pattern must be read at the last step
552
553   2) Basic test #2
554
555     - turn on the data cache
556     - switch the data cache to write-back or write-through mode
557     - invalidate the data cache
558     - write the zero pattern to a cached area
559     - turn off the data cache
560     - write the negative pattern to the area
561     - turn on the data cache
562     - read the area
563
564     The negative pattern must be read at the last step
565
566   3) Write-through mode test
567
568     - turn on the data cache
569     - switch the data cache to write-through mode
570     - invalidate the data cache
571     - write the zero pattern to a cached area
572     - flush the data cache
573     - write the negative pattern to the area
574     - turn off the data cache
575     - read the area
576
577     The negative pattern must be read at the last step
578
579   4) Write-back mode test
580
581     - turn on the data cache
582     - switch the data cache to write-back mode
583     - invalidate the data cache
584     - write the negative pattern to a cached area
585     - flush the data cache
586     - write the zero pattern to the area
587     - invalidate the data cache
588     - read the area
589
590     The negative pattern must be read at the last step
591
592 To verify the instruction cache operation the following test
593 scenarios will be used:
594
595   1) Basic test #1
596
597     - turn on the instruction cache
598     - unlock the entire instruction cache
599     - invalidate the instruction cache
600     - lock a branch instruction in the instruction cache
601     - replace the branch instruction with "nop"
602     - jump to the branch instruction
603     - check that the branch instruction was executed
604
605   2) Basic test #2
606
607     - turn on the instruction cache
608     - unlock the entire instruction cache
609     - invalidate the instruction cache
610     - jump to a branch instruction
611     - check that the branch instruction was executed
612     - replace the branch instruction with "nop"
613     - invalidate the instruction cache
614     - jump to the branch instruction
615     - check that the "nop" instruction was executed
616
617 The CPU test will run in RAM in order to allow run-time modification
618 of the code.
619
620 2.2.1.4. Memory test
621
622 The memory test will verify RAM using sequential writes and reads
623 to/from RAM. Specifically, there will be several test cases that will
624 use different patterns to verify RAM. Each test case will first fill
625 a region of RAM with one pattern and then read the region back and
626 compare its contents with the pattern. The following patterns will be
627 used:
628
629  1) zero pattern (0x00000000)
630  2) negative pattern (0xffffffff)
631  3) checkerboard pattern (0x55555555, 0xaaaaaaaa)
632  4) bit-flip pattern ((1 << (offset % 32)), ~(1 << (offset % 32)))
633  5) address pattern (offset, ~offset)
634
635 Patterns #1, #2 will help to find unstable bits. Patterns #3, #4 will
636 be used to detect adherent bits, i.e. bits whose state may randomly
637 change if adjacent bits are modified. The last pattern will be used
638 to detect far-located errors, i.e. situations when writing to one
639 location modifies an area located far from it. Also, usage of the
640 last pattern will help to detect memory controller misconfigurations
641 when RAM represents a cyclically repeated portion of a smaller size.
642
643 Being run in normal mode, the test will verify only small 4Kb regions
644 of RAM around each 1Mb boundary. For example, for 64Mb RAM the
645 following areas will be verified: 0x00000000-0x00000800,
646 0x000ff800-0x00100800, 0x001ff800-0x00200800, ..., 0x03fff800-
647 0x04000000. If the test is run in power-fail mode, it will verify the
648 whole RAM.
649
650 The memory test will run in ROM before relocating U-Boot to RAM in
651 order to allow RAM modification without saving its contents.
652
653 2.2.2. Common tests
654
655 This section describes tests that are not based on any hardware
656 peculiarities and use common U-Boot interfaces only. These tests do
657 not need any modifications for porting them to another board/CPU.
658
659 2.2.2.1. I2C test
660
661 For verifying the I2C bus, a full I2C bus scanning will be performed
662 using the i2c_probe() routine. If any I2C device is found, the test
663 will be considered as passed, otherwise failed. This particular way
664 will be used because it provides the most common method of testing.
665 For example, using the internal loopback mode of the CPM I2C
666 controller for testing would not work on boards where the software
667 I2C driver (also known as bit-banged driver) is used.
668
669 2.2.2.2. Watchdog timer test
670
671 To test the watchdog timer the scheme mentioned above (refer to
672 section "Hazardous tests") will be used. Namely, this test will be
673 marked with the POST_REBOOT bit flag. On the first iteration, the
674 test routine will make a 10-second delay. If the system does not
675 reboot during this delay, the watchdog timer is not operational and
676 the test fails. If the system reboots, on the second iteration the
677 POST_REBOOT bit will be set in the flag argument to the test routine.
678 The test routine will check this bit and report a success if it is
679 set.
680
681 2.2.2.3. RTC test
682
683 The RTC test will use the rtc_get()/rtc_set() routines. The following
684 features will be verified:
685
686   o) Time uniformity
687
688      This will be verified by reading RTC in polling within a short
689      period of time (5-10 seconds).
690
691   o) Passing month boundaries
692
693      This will be checked by setting RTC to a second before a month
694      boundary and reading it after its passing the boundary. The test
695      will be performed for both leap- and nonleap-years.
696
697 2.2.3. MPC8xx peripherals tests
698
699 This project will develop a set of tests verifying the peripheral
700 units of MPC8xx processors. Namely, the following controllers of the
701 MPC8xx communication processor module (CPM) will be tested:
702
703   o) Serial Management Controllers (SMC)
704
705   o) Serial Communication Controllers (SCC)
706
707 2.2.3.1. Ethernet tests (SCC)
708
709 The internal (local) loopback mode will be used to test SCC. To do
710 that the controllers will be configured accordingly and several
711 packets will be transmitted. These tests may be enhanced in future to
712 use external loopback for testing. That will need appropriate
713 reconfiguration of the physical interface chip.
714
715 The test routines for the SCC ethernet tests will be located in
716 cpu/mpc8xx/scc.c.
717
718 2.2.3.2. UART tests (SMC/SCC)
719
720 To perform these tests the internal (local) loopback mode will be
721 used. The SMC/SCC controllers will be configured to connect the
722 transmitter output to the receiver input. After that, several bytes
723 will be transmitted. These tests may be enhanced to make to perform
724 "external" loopback test using a loopback cable. In this case, the
725 test will be executed manually.
726
727 The test routine for the SMC/SCC UART tests will be located in
728 cpu/mpc8xx/serial.c.
729
730 2.2.3.3. USB test
731
732 TBD
733
734 2.2.3.4. SPI test
735
736 TBD