readme.post

u-boot-1.1.6 for mini2440开发板。 支持网络下载

Power-On-Self-Test support in U-Boot
------------------------------------

This project is to support Power-On-Self-Test (POST) in U-Boot.

1. High-level requirements

The key requirements for this project are as follows:

1) The project shall develop a flexible framework for implementing
   and running Power-On-Self-Test in U-Boot. This framework shall
   possess the following features:

   o) Extensibility

      The framework shall allow adding/removing/replacing POST tests.
      Also, standalone POST tests shall be supported.

   o) Configurability

      The framework shall allow run-time configuration of the lists
      of tests running on normal/power-fail booting.

   o) Controllability

      The framework shall support manual running of the POST tests.

2) The results of tests shall be saved so that it will be possible to
   retrieve them from Linux.

3) The following POST tests shall be developed for MPC823E-based
   boards:

   o) CPU test
   o) Cache test
   o) Memory test
   o) Ethernet test
   o) Serial channels test
   o) Watchdog timer test
   o) RTC test
   o) I2C test
   o) SPI test
   o) USB test

4) The LWMON board shall be used for reference.

2. Design

This section details the key points of the design for the project.
The whole project can be divided into two independent tasks:
enhancing U-Boot/Linux to provide a common framework for running POST
tests and developing such tests for particular hardware.

2.1. Hardware-independent POST layer

A new optional module will be added to U-Boot, which will run POST
tests and collect their results at boot time. Also, U-Boot will
support running POST tests manually at any time by executing a
special command from the system console.

The list of available POST tests will be configured at U-Boot build
time. The POST layer will allow the developer to add any custom POST
tests. All POST tests will be divided into the following groups:

  1) Tests running on power-on booting only

     This group will contain those tests that run only once on
     power-on reset (e.g. watchdog test)

  2) Tests running on normal booting only

     This group will contain those tests that do not take much
     time and can be run on the regular basis (e.g. CPU test)

  3) Tests running in special "slow test mode" only

     This group will contain POST tests that consume much time
     and cannot be run regularly (e.g. strong memory test, I2C test)

  4) Manually executed tests

     This group will contain those tests that can be run manually.

If necessary, some tests may belong to several groups simultaneously.
For example, SDRAM test may run in both normal and "slow test" mode.
In normal mode, SDRAM test may perform a fast superficial memory test
only, while running in slow test mode it may perform a full memory
check-up.

Also, all tests will be discriminated by the moment they run at.
Specifically, the following groups will be singled out:

  1) Tests running before relocating to RAM

     These tests will run immediately after initializing RAM
     as to enable modifying it without taking care of its
     contents. Basically, this group will contain memory tests
     only.

  2) Tests running after relocating to RAM

     These tests will run immediately before entering the main
     loop as to guarantee full hardware initialization.

The POST layer will also distinguish a special group of tests that
may cause system rebooting (e.g. watchdog test). For such tests, the
layer will automatically detect rebooting and will notify the test
about it.

2.1.1. POST layer interfaces

This section details the interfaces between the POST layer and the
rest of U-Boot.

The following flags will be defined:

#define POST_POWERON		0x01	/* test runs on power-on booting */
#define POST_NORMAL		0x02	/* test runs on normal booting */
#define POST_SLOWTEST		0x04	/* test is slow, enabled by key press */
#define POST_POWERTEST		0x08	/* test runs after watchdog reset */
#define POST_ROM		0x100	/* test runs in ROM */
#define POST_RAM		0x200	/* test runs in RAM */
#define POST_MANUAL		0x400	/* test can be executed manually */
#define POST_REBOOT		0x800	/* test may cause rebooting */
#define POST_PREREL             0x1000  /* test runs before relocation */

The POST layer will export the following interface routines:

  o) int post_run(bd_t *bd, char *name, int flags);

     This routine will run the test (or the group of tests) specified
     by the name and flag arguments. More specifically, if the name
     argument is not NULL, the test with this name will be performed,
     otherwise all tests running in ROM/RAM (depending on the flag
     argument) will be executed. This routine will be called at least
     twice with name set to NULL, once from board_init_f() and once
     from board_init_r(). The flags argument will also specify the
     mode the test is executed in (power-on, normal, power-fail,
     manual).

  o) void post_reloc(ulong offset);

     This routine will be called from board_init_r() and will
     relocate the POST test table.

  o) int post_info(char *name);

     This routine will print the list of all POST tests that can be
     executed manually if name is NULL, and the description of a
     particular test if name is not NULL.

  o) int post_log(char *format, ...);

     This routine will be called from POST tests to log their
     results. Basically, this routine will print the results to
     stderr. The format of the arguments and the return value
     will be identical to the printf() routine.

Also, the following board-specific routines will be called from the
U-Boot common code:

  o) int board_power_mode(void)

     This routine will return the mode the system is running in
     (POST_POWERON, POST_NORMAL or POST_SHUTDOWN).

  o) void board_poweroff(void)

     This routine will turn off the power supply of the board. It
     will be called on power-fail booting after running all POST
     tests.

  o) int post_hotkeys_pressed(gd_t *gd)

     This routine will scan the keyboard to detect if a magic key
     combination has been pressed, or otherwise detect if the
     power-on long-running tests shall be executed or not ("normal"
     versus "slow" test mode).

The list of available POST tests be kept in the post_tests array
filled at U-Boot build time. The format of entry in this array will
be as follows:

struct post_test {
    char *name;
    char *cmd;
    char *desc;
    int flags;
    int (*test)(bd_t *bd, int flags);
};

  o) name

     This field will contain a short name of the test, which will be
     used in logs and on listing POST tests (e.g. CPU test).

  o) cmd

     This field will keep a name for identifying the test on manual
     testing (e.g. cpu). For more information, refer to section
     "Command line interface".

  o) desc

     This field will contain a detailed description of the test,
     which will be printed on user request. For more information, see
     section "Command line interface".

  o) flags

     This field will contain a combination of the bit flags described
     above, which will specify the mode the test is running in
     (power-on, normal, power-fail or manual mode), the moment it
     should be run at (before or after relocating to RAM), whether it
     can cause system rebooting or not.

  o) test

     This field will contain a pointer to the routine that will
     perform the test, which will take 2 arguments. The first
     argument will be a pointer to the board info structure, while
     the second will be a combination of bit flags specifying the
     mode the test is running in (POST_POWERON, POST_NORMAL,
     POST_SLOWTEST, POST_MANUAL) and whether the last execution of
     the test caused system rebooting (POST_REBOOT). The routine will
     return 0 on successful execution of the test, and 1 if the test
     failed.

The lists of the POST tests that should be run at power-on/normal/
power-fail booting will be kept in the environment. Namely, the
following environment variables will be used: post_poweron,
powet_normal, post_slowtest.

2.1.2. Test results

The results of tests will be collected by the POST layer. The POST
log will have the following format:

...
--------------------------------------------
START <name>
<test-specific output>
[PASSED|FAILED]
--------------------------------------------
...

Basically, the results of tests will be printed to stderr. This
feature may be enhanced in future to spool the log to a serial line,
save it in non-volatile RAM (NVRAM), transfer it to a dedicated
storage server and etc.

2.1.3. Integration issues

All POST-related code will be #ifdef'ed with the CONFIG_POST macro.
This macro will be defined in the config_<board>.h file for those
boards that need POST. The CONFIG_POST macro will contain the list of
POST tests for the board. The macro will have the format of array
composed of post_test structures:

#define CONFIG_POST \
	{
		"On-board peripherals test", "board", \
		"  This test performs full check-up of the " \
		"on-board hardware.", \
		POST_RAM | POST_SLOWTEST, \
		&board_post_test \
	}

A new file, post.h, will be created in the include/ directory. This
file will contain common POST declarations and will define a set of
macros that will be reused for defining CONFIG_POST. As an example,
the following macro may be defined:

#define POST_CACHE \
	{
		"Cache test", "cache", \
		"  This test verifies the CPU cache operation.", \
		POST_RAM | POST_NORMAL, \
		&cache_post_test \
	}

A new subdirectory will be created in the U-Boot root directory. It
will contain the source code of the POST layer and most of POST
tests. Each POST test in this directory will be placed into a
separate file (it will be needed for building standalone tests). Some
POST tests (mainly those for testing peripheral devices) will be
located in the source files of the drivers for those devices. This
way will be used only if the test subtantially uses the driver.

2.1.4. Standalone tests

The POST framework will allow to develop and run standalone tests. A
user-space library will be developed to provide the POST interface
functions to standalone tests.

2.1.5. Command line interface

A new command, diag, will be added to U-Boot. This command will be
used for listing all available hardware tests, getting detailed
descriptions of them and running these tests.

More specifically, being run without any arguments, this command will
print the list of all available hardware tests:

=> diag
Available hardware tests:
  cache             - cache test
  cpu               - CPU test
  enet              - SCC/FCC ethernet test
Use 'diag [<test1> [<test2>]] ... ' to get more info.
Use 'diag run [<test1> [<test2>]] ... ' to run tests.
=>

If the first argument to the diag command is not 'run', detailed
descriptions of the specified tests will be printed:

=> diag cpu cache
cpu - CPU test
  This test verifies the arithmetic logic unit of CPU.
cache - cache test
  This test verifies the CPU cache operation.
=>

If the first argument to diag is 'run', the specified tests will be
executed. If no tests are specified, all available tests will be
executed.

It will be prohibited to execute tests running in ROM manually. The
'diag' command will not display such tests and/or run them.

2.1.6. Power failure handling

The Linux kernel will be modified to detect power failures and
automatically reboot the system in such cases. It will be assumed
that the power failure causes a system interrupt.

To perform correct system shutdown, the kernel will register a
handler of the power-fail IRQ on booting. Being called, the handler
will run /sbin/reboot using the call_usermodehelper() routine.
/sbin/reboot will automatically bring the system down in a secure
way. This feature will be configured in/out from the kernel
configuration file.

The POST layer of U-Boot will check whether the system runs in
power-fail mode. If it does, the system will be powered off after
executing all hardware tests.

2.1.7. Hazardous tests

Some tests may cause system rebooting during their execution. For
some tests, this will indicate a failure, while for the Watchdog
test, this means successful operation of the timer.

In order to support such tests, the following scheme will be
implemented. All the tests that may cause system rebooting will have
the POST_REBOOT bit flag set in the flag field of the correspondent
post_test structure. Before starting tests marked with this bit flag,
the POST layer will store an identification number of the test in a
location in IMMR. On booting, the POST layer will check the value of
this variable and if it is set will skip over the tests preceding the
failed one. On second execution of the failed test, the POST_REBOOT
bit flag will be set in the flag argument to the test routine. This
will allow to detect system rebooting on the previous iteration. For
example, the watchdog timer test may have the following
declaration/body:

...
#define POST_WATCHDOG \
	{