Feature Removal: disable "mtest" command by default

The "mtest" command is of little practical use (if any), and experience has shown that a large number of board configurations define useless or even dangerous start and end addresses. If not even the board maintainers are able to figure out which memory range can be reliably tested, how can we expect such from the end users? As this problem comes up repeatedly, we rather do not enable this command by default, so only people who know what they are doing will be confronted with it. As this changes the user interface, we allow for a grace period before this change takes effect. For now, we make "mtest" configurable through the CONFIG_CMD_MEMTEST variable, which is defined in include/config_cmd_default.h; we also add an entry to doc/feature-removal-schedule.txt which announces the removal of this default setting in two releases from now, i. e. with v2013.07. Signed-off-by: Wolfgang Denk <wd@denx.de> Cc: Tom Rini <trini@ti.com>

Feature Removal: disable "mtest" command by default
The "mtest" command is of little practical use (if any), and experience has shown that a large number of board configurations define useless or even dangerous start and end addresses. If not even the board maintainers are able to figure out which memory range can be reliably tested, how can we expect such from the end users? As this problem comes up repeatedly, we rather do not enable this command by default, so only people who know what they are doing will be confronted with it. As this changes the user interface, we allow for a grace period before this change takes effect. For now, we make "mtest" configurable through the CONFIG_CMD_MEMTEST variable, which is defined in include/config_cmd_default.h; we also add an entry to doc/feature-removal-schedule.txt which announces the removal of this default setting in two releases from now, i. e. with v2013.07. Signed-off-by: Wolfgang Denk <wd@denx.de> Cc: Tom Rini <trini@ti.com>
Wolfgang Denk · Tom Rini
1 parent c02bff3617
Showing 6 changed files with 125 additions and 4 deletions Side-by-side Diff
README
common/cmd_mem.c
doc/README.memory-test
doc/feature-removal-schedule.txt
include/config_cmd_all.h
include/config_cmd_default.h
@@ -860,7 +860,8 @@
 					  (requires CONFIG_CMD_MEMORY and CONFIG_MD5)
 		CONFIG_CMD_MEMINFO	* Display detailed memory information
 		CONFIG_CMD_MEMORY	  md, mm, nm, mw, cp, cmp, crc, base,
-					  loop, loopw, mtest
+					  loop, loopw
+		CONFIG_CMD_MEMTEST	  mtest
 		CONFIG_CMD_MISC		  Misc functions like sleep etc
 		CONFIG_CMD_MMC		* MMC memory mapped support
 		CONFIG_CMD_MII		* MII utility commands
@@ -910,6 +910,7 @@
 	return 0;
 }
  
+#ifdef CONFIG_CMD_MEMTEST
 /*
  * Perform a memory test. A more complete alternative test can be
  * configured using CONFIG_SYS_ALT_MEMTEST. The complete test loops until
  
@@ -1002,8 +1003,8 @@
  
 	return ret;	/* not reached */
 }
+#endif	/* CONFIG_CMD_MEMTEST */
  
-
 /* Modify memory.
  *
  * Syntax:
  
@@ -1240,11 +1241,13 @@
 );
 #endif /* CONFIG_LOOPW */
  
+#ifdef CONFIG_CMD_MEMTEST
 U_BOOT_CMD(
 	mtest,	5,	1,	do_mem_mtest,
 	"simple RAM read/write test",
 	"[start [end [pattern [iterations]]]]"
 );
+#endif	/* CONFIG_CMD_MEMTEST */
  
 #ifdef CONFIG_MX_CYCLIC
 U_BOOT_CMD(
+The most frequent cause of problems when porting U-Boot to new
+hardware, or when using a sloppy port on some board, is memory errors.
+In most cases these are not caused by failing hardware, but by
+incorrect initialization of the memory controller.  So it appears to
+be a good idea to always test if the memory is working correctly,
+before looking for any other potential causes of any problems.
+
+U-Boot implements 3 different approaches to perform memory tests:
+
+1. The get_ram_size() function (see "common/memsize.c").
+
+   This function is supposed to be used in each and every U-Boot port
+   determine the presence and actual size of each of the potential
+   memory banks on this piece of hardware.  The code is supposed to be
+   very fast, so running it for each reboot does not hurt.  It is a
+   little known and generally underrated fact that this code will also
+   catch 99% of hardware related (i. e. reliably reproducible) memory
+   errors.  It is strongly recommended to always use this function, in
+   each and every port of U-Boot.
+
+2. The "mtest" command.
+
+   This is probably the best known memory test utility in U-Boot.
+   Unfortunately, it is also the most problematic, and the most
+   useless one.
+
+   There are a number of serious problems with this command:
+
+   - It is terribly slow.  Running "mtest" on the whole system RAM
+     takes a _long_ time before there is any significance in the fact
+     that no errors have been found so far.
+
+   - It is difficult to configure, and to use.  And any errors here
+     will reliably crash or hang your system.  "mtest" is dumb and has
+     no knowledge about memory ranges that may be in use for other
+     purposes, like exception code, U-Boot code and data, stack,
+     malloc arena, video buffer, log buffer, etc.  If you let it, it
+     will happily "test" all such areas, which of course will cause
+     some problems.
+
+   - It is not easy to configure and use, and a large number of
+     systems are seriously misconfigured.  The original idea was to
+     test basically the whole system RAM, with only exempting the
+     areas used by U-Boot itself - on most systems these are the areas
+     used for the exception vectors (usually at the very lower end of
+     system memory) and for U-Boot (code, data, etc. - see above;
+     these are usually at the very upper end of system memory).  But
+     experience has shown that a very large number of ports use
+     pretty much bogus settings of CONFIG_SYS_MEMTEST_START and
+     CONFIG_SYS_MEMTEST_END; this results in useless tests (because
+     the ranges is too small and/or badly located) or in critical
+     failures (system crashes).
+
+   Because of these issues, the "mtest" command is considered depre-
+   cated.  It should not be enabled in most normal ports of U-Boot,
+   especially not in production.  If you really need a memory test,
+   then see 1. and 3. above resp. below.
+
+3. The most thorough memory test facility is available as part of the
+   POST (Power-On Self Test) sub-system, see "post/drivers/memory.c".
+
+   If you really need to perform memory tests (for example, because
+   it is mandatory part of your requirement specification), then
+   enable this test which is generic and should work on all archi-
+   tectures.
+
+WARNING:
+
+It should pointed out that _all_ these memory tests have one
+fundamental, unfixable design flaw:  they are based on the assumption
+that memory errors can be found by writing to and reading from memory.
+Unfortunately, this is only true for the relatively harmless, usually
+static errors like shorts between data or address lines, unconnected
+pins, etc.  All the really nasty errors which will first turn your
+hair gray, only to make you tear it out later, are dynamical errors,
+which usually happen not with simple read or write cycles on the bus,
+but when performing back-to-back data transfers in burst mode.  Such
+accesses usually happen only for certain DMA operations, or for heavy
+cache use (instruction fetching, cache flushing).  So far I am not
+aware of any freely available code that implements a generic, and
+efficient, memory test like that.  The best known test case to stress
+a system like that is to boot Linux with root file system mounted over
+NFS, and then build some larger software package natively (say,
+compile a Linux kernel on the system) - this will cause enough context
+switches, network traffic (and thus DMA transfers from the network
+controller), varying RAM use, etc. to trigger any weak spots in this
+area.
+
+Note: An attempt was made once to implement such a test to catch
+memory problems on a specific board.  The code is pretty much board
+specific (for example, it includes setting specific GPIO signals to
+provide triggers for an attached logic analyzer), but you can get an
+idea how it works: see "examples/standalone/test_burst*".
+
+Note 2: Ironically enough, the "test_burst" did not catch any RAM
+errors, not a single one ever.  The problems this code was supposed
+to catch did not happen when accessing the RAM, but when reading from
+NOR flash.
@@ -7,6 +7,23 @@
  
 ---------------------------
  
+What:	Remove CONFIG_CMD_MEMTEST from default list
+When:	Release v2013.07
+
+Why:	The "mtest" command is of little practical use (if any), and
+	experience has shown that a large number of board configu-
+	rations define useless or even dangerous start and end
+	addresses.  If not even the board maintainers are able to
+	figure out which memory range can be reliably tested, how can
+	we expect such from the end users?  As this problem comes up
+	repeatedly, we rather do not enable this command by default,
+	so only people who know what they are doing will be confronted
+	with it.
+
+Who:	Wolfgang Denk <wd@denx.de>
+
+---------------------------
+
 What:	Users of the legacy miiphy_* code
 When:	undetermined
  
@@ -57,7 +57,8 @@
 #define CONFIG_CMD_LOADB	/* loadb			*/
 #define CONFIG_CMD_LOADS	/* loads			*/
 #define CONFIG_CMD_MEMINFO	/* meminfo			*/
-#define CONFIG_CMD_MEMORY	/* md mm nm mw cp cmp crc base loop mtest */
+#define CONFIG_CMD_MEMORY	/* md mm nm mw cp cmp crc base loop */
+#define CONFIG_CMD_MEMTEST	/* mtest			*/
 #define CONFIG_CMD_MFSL		/* FSL support for Microblaze	*/
 #define CONFIG_CMD_MII		/* MII support			*/
 #define CONFIG_CMD_MISC		/* Misc functions like sleep etc*/
@@ -30,7 +30,8 @@
 #endif
 #define CONFIG_CMD_LOADB	/* loadb			*/
 #define CONFIG_CMD_LOADS	/* loads			*/
-#define CONFIG_CMD_MEMORY	/* md mm nm mw cp cmp crc base loop mtest */
+#define CONFIG_CMD_MEMORY	/* md mm nm mw cp cmp crc base loop */
+#define CONFIG_CMD_MEMTEST	/* mtest			*/
 #define CONFIG_CMD_MISC		/* Misc functions like sleep etc*/
 #define CONFIG_CMD_NET		/* bootp, tftpboot, rarpboot	*/
 #define CONFIG_CMD_NFS		/* NFS support			*/
...	...	@@ -860,7 +860,8 @@
860	860	(requires CONFIG_CMD_MEMORY and CONFIG_MD5)
861	861	CONFIG_CMD_MEMINFO * Display detailed memory information
862	862	CONFIG_CMD_MEMORY md, mm, nm, mw, cp, cmp, crc, base,
863		- loop, loopw, mtest
	863	+ loop, loopw
	864	+ CONFIG_CMD_MEMTEST mtest
864	865	CONFIG_CMD_MISC Misc functions like sleep etc
865	866	CONFIG_CMD_MMC * MMC memory mapped support
866	867	CONFIG_CMD_MII * MII utility commands
...	...	@@ -910,6 +910,7 @@
910	910	return 0;
911	911	}
912	912
	913	+#ifdef CONFIG_CMD_MEMTEST
913	914	/*
914	915	* Perform a memory test. A more complete alternative test can be
915	916	* configured using CONFIG_SYS_ALT_MEMTEST. The complete test loops until
916	917
...	...	@@ -1002,8 +1003,8 @@
1002	1003
1003	1004	return ret; /* not reached */
1004	1005	}
	1006	+#endif /* CONFIG_CMD_MEMTEST */
1005	1007
1006		-
1007	1008	/* Modify memory.
1008	1009	*
1009	1010	* Syntax:
1010	1011
...	...	@@ -1240,11 +1241,13 @@
1240	1241	);
1241	1242	#endif /* CONFIG_LOOPW */
1242	1243
	1244	+#ifdef CONFIG_CMD_MEMTEST
1243	1245	U_BOOT_CMD(
1244	1246	mtest, 5, 1, do_mem_mtest,
1245	1247	"simple RAM read/write test",
1246	1248	"[start [end [pattern [iterations]]]]"
1247	1249	);
	1250	+#endif /* CONFIG_CMD_MEMTEST */
1248	1251
1249	1252	#ifdef CONFIG_MX_CYCLIC
1250	1253	U_BOOT_CMD(
	1	+The most frequent cause of problems when porting U-Boot to new
	2	+hardware, or when using a sloppy port on some board, is memory errors.
	3	+In most cases these are not caused by failing hardware, but by
	4	+incorrect initialization of the memory controller. So it appears to
	5	+be a good idea to always test if the memory is working correctly,
	6	+before looking for any other potential causes of any problems.
	7	+
	8	+U-Boot implements 3 different approaches to perform memory tests:
	9	+
	10	+1. The get_ram_size() function (see "common/memsize.c").
	11	+
	12	+ This function is supposed to be used in each and every U-Boot port
	13	+ determine the presence and actual size of each of the potential
	14	+ memory banks on this piece of hardware. The code is supposed to be
	15	+ very fast, so running it for each reboot does not hurt. It is a
	16	+ little known and generally underrated fact that this code will also
	17	+ catch 99% of hardware related (i. e. reliably reproducible) memory
	18	+ errors. It is strongly recommended to always use this function, in
	19	+ each and every port of U-Boot.
	20	+
	21	+2. The "mtest" command.
	22	+
	23	+ This is probably the best known memory test utility in U-Boot.
	24	+ Unfortunately, it is also the most problematic, and the most
	25	+ useless one.
	26	+
	27	+ There are a number of serious problems with this command:
	28	+
	29	+ - It is terribly slow. Running "mtest" on the whole system RAM
	30	+ takes a _long_ time before there is any significance in the fact
	31	+ that no errors have been found so far.
	32	+
	33	+ - It is difficult to configure, and to use. And any errors here
	34	+ will reliably crash or hang your system. "mtest" is dumb and has
	35	+ no knowledge about memory ranges that may be in use for other
	36	+ purposes, like exception code, U-Boot code and data, stack,
	37	+ malloc arena, video buffer, log buffer, etc. If you let it, it
	38	+ will happily "test" all such areas, which of course will cause
	39	+ some problems.
	40	+
	41	+ - It is not easy to configure and use, and a large number of
	42	+ systems are seriously misconfigured. The original idea was to
	43	+ test basically the whole system RAM, with only exempting the
	44	+ areas used by U-Boot itself - on most systems these are the areas
	45	+ used for the exception vectors (usually at the very lower end of
	46	+ system memory) and for U-Boot (code, data, etc. - see above;
	47	+ these are usually at the very upper end of system memory). But
	48	+ experience has shown that a very large number of ports use
	49	+ pretty much bogus settings of CONFIG_SYS_MEMTEST_START and
	50	+ CONFIG_SYS_MEMTEST_END; this results in useless tests (because
	51	+ the ranges is too small and/or badly located) or in critical
	52	+ failures (system crashes).
	53	+
	54	+ Because of these issues, the "mtest" command is considered depre-
	55	+ cated. It should not be enabled in most normal ports of U-Boot,
	56	+ especially not in production. If you really need a memory test,
	57	+ then see 1. and 3. above resp. below.
	58	+
	59	+3. The most thorough memory test facility is available as part of the
	60	+ POST (Power-On Self Test) sub-system, see "post/drivers/memory.c".
	61	+
	62	+ If you really need to perform memory tests (for example, because
	63	+ it is mandatory part of your requirement specification), then
	64	+ enable this test which is generic and should work on all archi-
	65	+ tectures.
	66	+
	67	+WARNING:
	68	+
	69	+It should pointed out that _all_ these memory tests have one
	70	+fundamental, unfixable design flaw: they are based on the assumption
	71	+that memory errors can be found by writing to and reading from memory.
	72	+Unfortunately, this is only true for the relatively harmless, usually
	73	+static errors like shorts between data or address lines, unconnected
	74	+pins, etc. All the really nasty errors which will first turn your
	75	+hair gray, only to make you tear it out later, are dynamical errors,
	76	+which usually happen not with simple read or write cycles on the bus,
	77	+but when performing back-to-back data transfers in burst mode. Such
	78	+accesses usually happen only for certain DMA operations, or for heavy
	79	+cache use (instruction fetching, cache flushing). So far I am not
	80	+aware of any freely available code that implements a generic, and
	81	+efficient, memory test like that. The best known test case to stress
	82	+a system like that is to boot Linux with root file system mounted over
	83	+NFS, and then build some larger software package natively (say,
	84	+compile a Linux kernel on the system) - this will cause enough context
	85	+switches, network traffic (and thus DMA transfers from the network
	86	+controller), varying RAM use, etc. to trigger any weak spots in this
	87	+area.
	88	+
	89	+Note: An attempt was made once to implement such a test to catch
	90	+memory problems on a specific board. The code is pretty much board
	91	+specific (for example, it includes setting specific GPIO signals to
	92	+provide triggers for an attached logic analyzer), but you can get an
	93	+idea how it works: see "examples/standalone/test_burst*".
	94	+
	95	+Note 2: Ironically enough, the "test_burst" did not catch any RAM
	96	+errors, not a single one ever. The problems this code was supposed
	97	+to catch did not happen when accessing the RAM, but when reading from
	98	+NOR flash.
...	...	@@ -7,6 +7,23 @@
7	7
8	8	---------------------------
9	9
	10	+What: Remove CONFIG_CMD_MEMTEST from default list
	11	+When: Release v2013.07
	12	+
	13	+Why: The "mtest" command is of little practical use (if any), and
	14	+ experience has shown that a large number of board configu-
	15	+ rations define useless or even dangerous start and end
	16	+ addresses. If not even the board maintainers are able to
	17	+ figure out which memory range can be reliably tested, how can
	18	+ we expect such from the end users? As this problem comes up
	19	+ repeatedly, we rather do not enable this command by default,
	20	+ so only people who know what they are doing will be confronted
	21	+ with it.
	22	+
	23	+Who: Wolfgang Denk <wd@denx.de>
	24	+
	25	+---------------------------
	26	+
10	27	What: Users of the legacy miiphy_* code
11	28	When: undetermined
12	29
...	...	@@ -57,7 +57,8 @@
57	57	#define CONFIG_CMD_LOADB /* loadb */
58	58	#define CONFIG_CMD_LOADS /* loads */
59	59	#define CONFIG_CMD_MEMINFO /* meminfo */
60		-#define CONFIG_CMD_MEMORY /* md mm nm mw cp cmp crc base loop mtest */
	60	+#define CONFIG_CMD_MEMORY /* md mm nm mw cp cmp crc base loop */
	61	+#define CONFIG_CMD_MEMTEST /* mtest */
61	62	#define CONFIG_CMD_MFSL /* FSL support for Microblaze */
62	63	#define CONFIG_CMD_MII /* MII support */
63	64	#define CONFIG_CMD_MISC /* Misc functions like sleep etc*/
...	...	@@ -30,7 +30,8 @@
30	30	#endif
31	31	#define CONFIG_CMD_LOADB /* loadb */
32	32	#define CONFIG_CMD_LOADS /* loads */
33		-#define CONFIG_CMD_MEMORY /* md mm nm mw cp cmp crc base loop mtest */
	33	+#define CONFIG_CMD_MEMORY /* md mm nm mw cp cmp crc base loop */
	34	+#define CONFIG_CMD_MEMTEST /* mtest */
34	35	#define CONFIG_CMD_MISC /* Misc functions like sleep etc*/
35	36	#define CONFIG_CMD_NET /* bootp, tftpboot, rarpboot */
36	37	#define CONFIG_CMD_NFS /* NFS support */