* Allow crc32 to be used at address 0x000

* Provide consistent interface to standalone applications to access
  the 'global_data' structure
  Provide a doc/README.standalone more useful to users/developers.

* Make IceCube MGT5100 FEC driver work

1 files changed, 83 insertions, 143 deletions

diff --git a/doc/README.standalone b/doc/README.standalone
index a5992ab876b..39988317ee5 100644
--- a/doc/README.standalone
+++ b/doc/README.standalone
@@ -1,156 +1,96 @@
 Design Notes on Exporting U-Boot Functions to Standalone Applications:
 ======================================================================
 
-1. Add a field to the global_data structure, the pointer to a jump
-   table.
-
-2. Jump table itself is allocated and filled in the same way as the
-   syscall table is (allocated with malloc() after the code has been
-   relocated to RAM); a special function, fixed to the table element
-   number 0, will be added which returns the ABI version so
-   applications can check for compatibility issues.
-
-3. It is application's responsibility to check the ABI version and
-   act accordingly.
-
-4. Pointer to the global_data is passed to the application in the
-   dedicated register that is used in the U-Boot to hold this
-   pointer. This assumes that the application is built with the same
-   register- allocation flags as the U-Boot itself. (Actually, this
-   is a requirement even now, as the 'go' command does not perform
-   any actions to protect this register against being clobbered by
-   the application).
-
-   This approach won't work on the x86 architecture. See below.
-
-5. Application now calls standard library functions like printf()
-   instead of specially prefixed names like mon_printf() as it did
-   before. Present implementation of these functions (using the
-   system calls mechanism) will be replaced with jump stubs.
-
-6. To export additional functions, the following steps will have to be 
-   taken:
-
-   - Add the xxx() U-Boot function to the EXPORT_FUNC list
-   - Add initialization of the appropriate slot in the jump table
-
-7. To port to a new architecture, the appropriate stub code should be
-   provided. No other machine-dependent code is used. Once the stub
-   template is available, no additional coding is needed when
-   exporting new U-Boot functions. A pre-processor macro will be used
-   to automatically instantiate the stub definition for each exported
-   function.
-
-Note the following:
-
-- This approach uses a jump table with fixed slot allocation. That
-  said, to retain the ABI compatibility, no table reordering,
-  inserting new functions in the middle of the list or deleting
-  functions from the list is allowed. Any such action will break the
-  ABI compatibility.
-
-- The x86 architecture does not use a dedicated register to store the
-  pointer to the global_data structure. There are the following
-  approaches available:
-
-  * Pass the global_data pointer to the application in a register or
-    as an additional argument. This requires special machine-
-    dependent startup code to be compiled into the application.
-
-  * Make the x86 consistent with the rest of architectures and use a
-    dedicated register. This renders one register unusable in the
-    rest of the U-Boot code and thus increases the size of the U-Boot
-    binary and decreases it performance.
-
-The following changes will be made:
-
-- The syscall handling code will be removed.
-
-- The include/_exports.h file will be introduced, containing the list
-  of the exported functions in the following form:
+1. The functions are exported by U-Boot via a jump table. The jump
+   table is allocated and initialized in the jumptable_init() routine
+   (common/exports.c). Other routines may also modify the jump table,
+   however. The jump table can be accessed as the 'jt' field of the
+   'global_data' structure. The slot numbers for the jump table are
+   defined in the <include/exports.h> header. E.g., to substitute the
+   malloc() and free() functions that will be available to standalone
+   applications, one should do the following:
+
+	DECLARE_GLOBAL_DATA_PTR;
+
+	gd->jt[XF_malloc]	= my_malloc;
+	gd->jt[XF_free]		= my_free;
+
+   Note that the pointers to the functions all have 'void *' type and
+   thus the compiler cannot perform type checks on these assignments.
+
+2. The pointer to the jump table is passed to the application in a
+   machine-dependent way. PowerPC, ARM and MIPS architectures use a
+   dedicated register to hold the pointer to the 'global_data'
+   structure: r29 on PowerPC, r8 on ARM and k0 on MIPS. The x86
+   architecture does not use such a register; instead, the pointer to
+   the 'global_data' structure is passed as 'argv[-1]' pointer.
+
+   The application can access the 'global_data' structure in the same
+   way as U-Boot does:
+
+	DECLARE_GLOBAL_DATA_PTR;
+
+	printf("U-Boot relocation offset: %x\n", gd->reloc_off);
+
+3. The application should call the app_startup() function before any
+   call to the exported functions. Also, implementor of the
+   application may want to check the version of the ABI provided by
+   U-Boot. To facilitate this, a get_version() function is exported
+   that returns the ABI version of the running U-Boot. I.e., a
+   typical application startup may look like this:
+
+	int my_app (int argc, char *argv[])
+	{
+		app_startup (argv);
+		if (get_version () != XF_VERSION)
+			return 1;
+	}
+
+4. The default load and start addresses of the applications are as
+   follows:
+
+		Load address	Start address
+	x86	0x00040000	0x00040000
+	PowerPC	0x00040000	0x00040004
+	ARM	0x0c100000	0x0c100000
+	MIPS	0x80200000	0x80200000
+
+   For example, the "hello world" application may be loaded and
+   executed on a PowerPC board with the following commands:
+
+   => tftp 0x40000 hello_world.bin
+   => go 0x40004
 
-  EXPORT_FUNC(getc)
-  EXPORT_FUNC(tstc)
-  ...
+5. To export some additional function foobar(), the following steps
+   should be undertaken:
 
-  This list will be used to assign the slot numbers in the jump
-  table, to determine the size of the jump table and to generate the
-  code for the stub functions.
+   - Append the following line at the end of the include/_exports.h
+     file:
 
-- The include/exports.h file will be introduced, containing the
-  prototypes of the exported functions and the assigned slot numbers.
+	EXPORT_FUNC(foobar)
 
-- The examples/stubs.c file will be introduced, containing the code
-  for the jump stubs for each of the exported functions.
+   - Add the prototype for this function to the include/exports.h
+     file:
 
-Implementation Notes on Exporting U-Boot Functions:
-===================================================
+	void foobar(void);
 
-1. The patch was applied against TOT as of 7/24 12:50 MEST; the
-   resulting images were tested on the following boards:
+   - Add the initialization of the jump table slot wherever
+     appropriate (most likely, to the jumptable_init() function):
 
-   * lwmon (PowerPC)
-   * trab  (ARM)
-   * inca  (MIPS)
+	gd->jt[XF_foobar] = foobar;
 
-   The hello_world application was loaded and executed then:
+   - Increase the XF_VERSION value by one in the include/exports.h
+     file
 
-   [lwmon]
-   => tftp 0x40000 /tftpboot/LWMON/hello_world.bin-avn
-   => go 0x40004
+6. The code for exporting the U-Boot functions to applications is
+   mostly machine-independent. The only places written in assembly
+   language are stub functions that perform the jump through the jump
+   table. That said, to port this code to a new architecture, the
+   only thing to be provided is the code in the examples/stubs.c
+   file. If this architecture, however, uses some uncommon method of
+   passing the 'global_data' pointer (like x86 does), one should add
+   the respective code to the app_startup() function in that file.
 
-   [trab]
-   TRAB # tftp 0xc100000 /tftpboot/TRAB/hello_world.bin-avn
-   TRAB # go 0xc100000
-
-   [inca]
-   INCA-IP # tftp 0x80200000 /tftpboot/INCA/hello_world.bin-avn
-   INCA-IP # go 0x80200000
-
-2. As neither of supported x86 boards can be built from the TOT
-   sources currently, the patch build was verified by manually
-   running the following command in the U-Boot top directory:
-
-   > make -C examples TOPDIR=`pwd` ARCH=i386 CROSS_COMPILE=
-
-   The rest of the code is mostly machine-independent and was not
-   verified.
-
-3. To test the x86 assembly code, a small standalone application was
-   written. It was built and run on the RedHat Linux 8.0 (x86). The
-   application performs a jump using a pointer to jump table and a
-   function's index in it.
-
-4. For the MIPS architecture, the linker script is also provided for
-   linking applications. The default linker script places the .text
-   and .data sections too far from each other so that the resulting
-   .bin files span about 256Mb in size.
-
-5. Several example applications required updating for the new API.
-   These applications relied upon the bd_t pointer being passed as
-   the 1st argument to the main function; this had changed when the
-   system calls were introduced, but apparently, these applications
-   weren't fixed at that moment. This is fixed now.
-
-6. GCC issues warnings for the 'sched' application. Since now the
-   mon_printf() function is renamed to printf(), GCC applies its
-   knowledge of the format specifiers to check the arguments,
-   complaining about ints passed as longs and vice versa. This is not
-   fixed yet.
-
-7. Only the hello_world example application was modified to make use
-   of the newly supplied get_version() function. The application now
-   prints two ABI versions, the one that the application was compiled
-   for and the other, actual ABI version.
-
-8. The following new files were added:
-   common/exports.c
-   examples/mips.lds
-   examples/stubs.c
-   include/_exports.h
-   include/exports.h
-   doc/README.standalone
-
-   The following files are no longer used and will be removed:
-   examples/syscall.S
-   include/syscall.h
+   Note that these functions may only use call-clobbered registers;
+   those registers that are used to pass the function's arguments,
+   the stack contents and the return address should be left intact.