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