Power-On-Self-Test support in U-Boot------------------------------------This project is to support Power-On-Self-Test (POST) in U-Boot.1. High-level requirementsThe 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 test4) The LWMON board shall be used for reference.2. DesignThis 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 POSTtests and developing such tests for particular hardware.2.1. Hardware-independent POST layerA new optional module will be added to U-Boot, which will run POSTtests and collect their results at boot time. Also, U-Boot willsupport running POST tests manually at any time by executing aspecial command from the system console.The list of available POST tests will be configured at U-Boot buildtime. The POST layer will allow the developer to add any custom POSTtests. 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 testonly, while running in slow test mode it may perform a full memorycheck-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 thatmay cause system rebooting (e.g. watchdog test). For such tests, thelayer will automatically detect rebooting and will notify the testabout it.2.1.1. POST layer interfacesThis section details the interfaces between the POST layer and therest 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 theU-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 arrayfilled at U-Boot build time. The format of entry in this array willbe 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, thefollowing environment variables will be used: post_poweron,powet_normal, post_slowtest.2.1.2. Test resultsThe results of tests will be collected by the POST layer. The POSTlog will have the following format:...--------------------------------------------START <name><test-specific output>[PASSED|FAILED]--------------------------------------------...Basically, the results of tests will be printed to stderr. Thisfeature may be enhanced in future to spool the log to a serial line,save it in non-volatile RAM (NVRAM), transfer it to a dedicatedstorage server and etc.2.1.3. Integration issuesAll POST-related code will be #ifdef'ed with the CONFIG_POST macro.This macro will be defined in the config_<board>.h file for thoseboards that need POST. The CONFIG_POST macro will contain the list ofPOST tests for the board. The macro will have the format of arraycomposed 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. Thisfile will contain common POST declarations and will define a set ofmacros 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. Itwill contain the source code of the POST layer and most of POSTtests. Each POST test in this directory will be placed into aseparate file (it will be needed for building standalone tests). SomePOST tests (mainly those for testing peripheral devices) will belocated in the source files of the drivers for those devices. Thisway will be used only if the test subtantially uses the driver.2.1.4. Standalone testsThe POST framework will allow to develop and run standalone tests. Auser-space library will be developed to provide the POST interfacefunctions to standalone tests.2.1.5. Command line interfaceA new command, diag, will be added to U-Boot. This command will beused for listing all available hardware tests, getting detaileddescriptions of them and running these tests.More specifically, being run without any arguments, this command willprint the list of all available hardware tests:=> diagAvailable hardware tests:  cache             - cache test  cpu               - CPU test  enet              - SCC/FCC ethernet testUse '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', detaileddescriptions of the specified tests will be printed:=> diag cpu cachecpu - 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 beexecuted. If no tests are specified, all available tests will beexecuted.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 handlingThe Linux kernel will be modified to detect power failures andautomatically reboot the system in such cases. It will be assumedthat the power failure causes a system interrupt.To perform correct system shutdown, the kernel will register ahandler of the power-fail IRQ on booting. Being called, the handlerwill run /sbin/reboot using the call_usermodehelper() routine./sbin/reboot will automatically bring the system down in a secureway. This feature will be configured in/out from the kernelconfiguration file.The POST layer of U-Boot will check whether the system runs inpower-fail mode. If it does, the system will be powered off afterexecuting all hardware tests.2.1.7. Hazardous testsSome tests may cause system rebooting during their execution. Forsome tests, this will indicate a failure, while for the Watchdogtest, this means successful operation of the timer.In order to support such tests, the following scheme will beimplemented. All the tests that may cause system rebooting will havethe POST_REBOOT bit flag set in the flag field of the correspondentpost_test structure. Before starting tests marked with this bit flag,the POST layer will store an identification number of the test in alocation in IMMR. On booting, the POST layer will check the value ofthis variable and if it is set will skip over the tests preceding thefailed one. On second execution of the failed test, the POST_REBOOTbit flag will be set in the flag argument to the test routine. Thiswill allow to detect system rebooting on the previous iteration. Forexample, the watchdog timer test may have the followingdeclaration/body:...#define POST_WATCHDOG \	{