Merge branch 'docu_update' of octopus:/home/jbe/work/u-boot-v2 into jbe

15 files changed, 279 insertions, 130 deletions

diff --git a/Documentation/boards.dox b/Documentation/boards.dox
index b42365187b..c4d05d69af 100644
--- a/Documentation/boards.dox
+++ b/Documentation/boards.dox
@@ -4,30 +4,35 @@ This is a list of boards that are currently supported by U-Boot-v2.
 
 PowerPC type:
 
-- @subpage pcm030
+@li @subpage pcm030
 
 ARM type:
 
-- @subpage pcm037
-- @subpage pcm038
-- @subpage pcm043
-- @subpage imx21ads
-- @subpage imx27ads
-- @subpage the3stack
-- @subpage scb9328
-- @subpage netx
-- @subpage dev_omap_arch
+@li @subpage pcm037
+@li @subpage pcm038
+@li @subpage pcm043
+@li @subpage imx21ads
+@li @subpage imx27ads
+@li @subpage the3stack
+@li @subpage scb9328
+@li @subpage netx
+@li @subpage dev_omap_arch
+@li @subpage a9m2440
+@li @subpage a9m2410
+@li @subpage eukrea_cpuimx27
 
 Blackfin type:
 
-- @subpage ipe337
+@li @subpage ipe337
 
 x86 type:
 
+@li nothing yet
+
 coldfire/m68k type:
 
-- @subpage phycore_mcf54xx
-- @subpage kp_ukd_r1
+@li @subpage phycore_mcf54xx
+@li @subpage kp_ukd_r1
 
 */
 
diff --git a/Documentation/commands.dox b/Documentation/commands.dox
index fe539e5427..4c14a8855e 100644
--- a/Documentation/commands.dox
+++ b/Documentation/commands.dox
@@ -1,24 +1,24 @@
 /**
  * @page command_reference Supported Shell Commands
 
- - @subpage addpart_command
- - @subpage cat_command
- - @subpage cd_command
- - @subpage cp_command
- - @subpage delpart_command
- - @subpage devinfo_command
- - @subpage edit_command
- - @subpage erase_command
- - @subpage export_command
- - @subpage tftp_command
- - @subpage loadenv_command
- - @subpage mount_command
- - @subpage printenv_command
- - @subpage protect_command
- - @subpage rarp_command
- - @subpage saveenv_command
- - @subpage setenv_command
- - @subpage sh_command
- - @subpage unprotect_command
+@li @subpage addpart_command
+@li @subpage cat_command
+@li @subpage cd_command
+@li @subpage cp_command
+@li @subpage delpart_command
+@li @subpage devinfo_command
+@li @subpage edit_command
+@li @subpage erase_command
+@li @subpage export_command
+@li @subpage tftp_command
+@li @subpage loadenv_command
+@li @subpage mount_command
+@li @subpage printenv_command
+@li @subpage protect_command
+@li @subpage rarp_command
+@li @subpage saveenv_command
+@li @subpage setenv_command
+@li @subpage sh_command
+@li @subpage unprotect_command
 
 */
diff --git a/Documentation/developers_manual.dox b/Documentation/developers_manual.dox
index fc8d4596fa..80f07f2eb5 100644
--- a/Documentation/developers_manual.dox
+++ b/Documentation/developers_manual.dox
@@ -1,22 +1,23 @@
 /** @page developers_manual Developer's Manual
 
-This part of the documentation is intended for developers.
+This part of the documentation is intended for developers of U-Boot-v2.
 
-Some background knowledge for some frameworks in U-Boot v2
+@section devel_backgrounds Some background knowledge for some frameworks U-Boot-v2
 
- - @subpage driver_model
+@li @subpage driver_model
+@li @subpage dev_params
 
-Hints and tips for simply adapting U-Boot v2
+@section devel_hints Hints and tips for simply adapting U-Boot-v2
 
- - @subpage dev_architecture
- - @subpage dev_cpu
- - @subpage dev_board
- - @subpage dev_params
+@li @subpage dev_architecture
+@li @subpage dev_cpu
+@li @subpage dev_board
 
-Various themes:
+@section devel_themes Various themes about U-Boot-v2
 
- - @subpage how_mount_works
- - @subpage boot_preparation
- - @subpage uboot_simul
+@li @subpage how_mount_works
+@li @subpage boot_preparation
+@li @subpage uboot_simul
+@li @subpage io_access_functions
 
 */
diff --git a/Documentation/parameters.txt b/Documentation/parameters.txt
deleted file mode 100644
index 9381cd2d3e..0000000000
--- a/Documentation/parameters.txt
+++ /dev/null
@@ -1,52 +0,0 @@
----------- Device parameters --------------
-
-Devices have several parameters. In case of a network device this may be the
-ip address, networking mask or similar and users need access to these
-parameters. in U-Boot this is solved with device paramters. Device parameters
-are always strings, although there are functions to interpret them as
-something else. hush users can access parameters as a local variable which
-have a dot (.) in them. So setting the ip address of the first ethernet
-device is a matter of typing 'eth0.ip=192.168.0.7' on the console and can
-then be read back with 'echo $eth0.ip'. The devinfo command shows a summary
-about all devices currently present. If called with a device id as parameter
-it shows the parameters available for a device.
-
-Device parameters programming API
----------------------------------
-
-struct param_d {
-	char* (*get)(struct device_d *, struct param_d *param);
-	int (*set)(struct device_d *, struct param_d *param, const char *val);
-	ulong flags;
-	char *name;
-	struct param_d *next;
-	char *value;
-};
-
-int dev_add_param(struct device_d *dev, struct param_d *par);
-
-This function adds a new parameter to a device. At least the name field in
-the new parameter struct has to be initialized. The 'get' and 'set' fields
-can be set to NULL in which case the framework handles them. It is also
-allowed to implement only one of the get/set functions. Care must be taken
-with the initial value of the parameter. If the framework handles the set
-function it will try to free the value of the parameter. If this is a
-static array bad things will happen. A parameter can have the flag
-PARAM_FLAG_RO which means that the parameter is readonly. It is perfectly ok
-then to point the value to a static array.
-
-const char *dev_get_param(struct device_d *dev, const char *name);
-
-This function returns a pointer to the value of the parameter specified
-with dev and name.
-If the framework handles the get/set functions the parameter value strings
-are alloceted with malloc and freed with free when another value is set for
-this parameter. Drivers implementing set/get themselves are allowed to
-return values in static arrays. This means that the pointers returned from
-dev_get_param() are only valid until the next call to dev_get_param. If this
-is not long enough strdup() or similar must be used.
-
-int dev_set_param(struct device_d *dev, const char *name, const char *val);
-
-Set the value of a parameter.
-
diff --git a/Documentation/users_manual.dox b/Documentation/users_manual.dox
index e346a12ee7..e4ba9d00e3 100644
--- a/Documentation/users_manual.dox
+++ b/Documentation/users_manual.dox
@@ -6,9 +6,9 @@ Mostly everyone. The user needs it to find help for his daily work to manage
 his targets. The developer to find out all the new features that make his
 work easier.
 
- - @subpage shell_notes
- - @subpage readline_parser
- - @subpage command_reference
- - @subpage partitions
+@li @subpage shell_notes
+@li @subpage readline_parser
+@li @subpage command_reference
+@li @subpage partitions
 
-*/
\ No newline at end of file
+*/
diff --git a/arch/architecture.dox b/arch/architecture.dox
index 9013bae1b2..6ef5ba928d 100644
--- a/arch/architecture.dox
+++ b/arch/architecture.dox
@@ -84,10 +84,90 @@ Note: U-Boot-v2 expects an upward counting counter!
 
 TODO
 
- - @subpage dev_arm_mach
- - @subpage dev_bf_mach
- - @subpage dev_ppc_mach
+@li @subpage dev_arm_mach
+@li @subpage dev_bf_mach
+@li @subpage dev_ppc_mach
 
 */
 
+/** @page io_access_functions I/O access functions
 
+List of functions to be used for hardware register access (I/O).
+
+@section native_access Native IN/OUT access
+
+@note Native means: It uses the same endianess than the CPU.
+
+@subsection single_native_access Single access of various width
+
+The following functions are intended to be used for a single I/O access.
+
+To read a byte (8 bit) from a specific I/O address:
+@code
+uint8_t readb(unsigned long)
+@endcode
+
+To read a word (16 bit) from a specific I/O address:
+@code
+uint16_t readw(unsigned long)
+@endcode
+
+To read a long word (32 bit) from a specific I/O address:
+@code
+uint32_t readl(unsigned long)
+@endcode
+
+To write a byte (8 bit) into a specific I/O address:
+@code
+void writeb(uint8_t val, unsigned long)
+@endcode
+
+To write a word (16 bit) into a specific I/O address:
+@code
+void writew(uint16_t val, unsigned long)
+@endcode
+
+To write a long word (32 bit) into a specific I/O address:
+@code
+void writel(uint32_t val, unsigned long)
+@endcode
+
+@subsection string_native_access String native access of various width
+
+The following functions are intended to be used for string based I/O access.
+
+To read a string of bytes (8 bit) from one specific I/O address:
+@code
+void readsb(const void __iomem *addr, void *mem_buffer, int byte_count);
+@endcode
+
+To read a string of words (16 bit) from one specific I/O address:
+@code
+void readsw(const void __iomem *addr, void *mem_buffer, int word_count);
+@endcode
+
+To read a string of long words (32 bit) from one specific I/O address:
+@code
+void readsl(const void __iomem *addr, void *mem_buffer, int long_count);
+@endcode
+
+To write a string of bytes (8 bit) to one specific I/O address:
+@code
+void writesb(void __iomem *addr, const void *mem_buffer, int byte_count);
+@endcode
+
+To write a string of words (16 bit) to one specific I/O address:
+@code
+void writesw(void __iomem *addr, const void *mem_buffer, int word_count);
+@endcode
+
+To write a string of long words (32 bit) to one specific I/O address:
+@code
+void writesl(void __iomem *addr, const void *mem_buffer, int long_count);
+@endcode
+
+@section special_access Special IN/OUT access
+
+TBD
+
+*/
diff --git a/arch/arm/lib/findbit.S b/arch/arm/lib/findbit.S
index 30c8a1a62a..7fa93a5d0a 100644
--- a/arch/arm/lib/findbit.S
+++ b/arch/arm/lib/findbit.S
@@ -1,7 +1,3 @@
-/**
- * @file
- * @brief common bitops
- */
 /*
  * Originally from Linux kernel
  *  arch/arm/lib/findbit.S
diff --git a/arch/arm/mach-arm.dox b/arch/arm/mach-arm.dox
index 412ce3840f..106aa39df9 100644
--- a/arch/arm/mach-arm.dox
+++ b/arch/arm/mach-arm.dox
@@ -6,7 +6,7 @@
 
 FIXME
 
-@par What's happens when the reset signal is gone
+@section mach_arm_reset What's happens when the reset signal is gone
 
 @note Code running immediately after reset runs at an address it is not linked
       to: "runtime address != link address". You should only use branches and
@@ -22,29 +22,44 @@ After handling some MMU related things \<board_init_lowlevel\> can be called (if
 not disabled). This is a board specific function for SDRAM setup for example.
 As its board specific, your can do whatever you need to bring your board up.
 
+In the case the boot happens from NAND flash memory, further steps are required.
+Most of the known processor devices are reading the first few blocks from the
+NAND flash memory into some kind of internal SRAM. This small part must be able
+to initialize the SDRAM controller and to read the remaining rest of the
+U-Boot-v2 binary from the NAND flash memory prior returning from \<board_init_lowlevel\>.
+
 When \<board_init_lowlevel\> returns it will be assumed there is now a working
 RAM that can be used for all further steps.
 
-Next step is relocation of U-Boot itself. It gets copied to RAM and the last
-assembler instruction is a jump into \<start_uboot\>. This target address is
-the first C instruction in U-Boot. At this point of time:\n
+Next step is relocation of U-Boot itself (if not already done). It gets copied
+to RAM and the last assembler instruction is a jump into start_uboot(). This
+target address is the first C instruction in U-Boot. At this point of time:\n
 "runtime address == link address".
 
-@par Architectures using ARM processors
-For details on specific architectures:
- - @subpage dev_omap_arch
-
 @section mach_arm_files List of changes
 
 Lets call the new MACH new_cpu.
 
  - create a new subdirectory in /arch/arm/new_cpu
+ - create a new subdirectory in /include/asm-arm/new_cpu
+ - add CPU specific definitions into /include/asm-arm/new_cpu/
  - add /arch/arm/new_cpu/Kconfig
  - add /arch/arm/new_cpu/Makfile
  - add other CPU specific code into /arch/arm/new_cpu/
  - modify /arch/arm/Kconfig
  - modify /arch/arm/Makfile
 
+@section mach_arm_architecures Architectures using ARM processors
+For details on specific architectures:
+
+@subsection mach_arm_omap_info OMAP CPUs
+
+@li @subpage dev_omap_arch
+
+@subsection mach_arm_s3c24xx_info S3C24XX CPUs
+
+@li @subpage dev_s3c24xx_arch
+
 TODO add more details
 
 */
diff --git a/arch/arm/mach-s3c24xx/lowlevel-init.S b/arch/arm/mach-s3c24xx/lowlevel-init.S
index 8c32f50508..d27cfa5dfb 100644
--- a/arch/arm/mach-s3c24xx/lowlevel-init.S
+++ b/arch/arm/mach-s3c24xx/lowlevel-init.S
@@ -162,8 +162,7 @@ Define in the machine specific config.h the following symbols:
 
 @note Valid values for the PLL settings can be found in the CPU manual.
 
-@par Background: PLL frequency calculation for the S3C2410 CPU (both PLLs)
-and S3C2440 (UPLL only)
+@par Background: PLL frequency calculation for the S3C2410 CPU (both PLLs) and S3C2440 (UPLL only)
 
 @f[
 	f_{PLL} = \frac{m * f_{Ref}}{p * 2^s}
diff --git a/board/a9m2410/a9m2410.c b/board/a9m2410/a9m2410.c
index bc10241fc6..8d41291b9c 100644
--- a/board/a9m2410/a9m2410.c
+++ b/board/a9m2410/a9m2410.c
@@ -258,4 +258,19 @@ This CPU card is based on a Samsung S3C2410 CPU. The card is shipped with:
 - SPI interface
 - JTAG interface
 
+How to get the binary image:
+
+Using the default configuration:
+
+@code
+make ARCH=arm a9m2410_defconfig
+@endcode
+
+Build the binary image:
+
+@code
+make ARCH=arm CROSS_COMPILE=armv4compiler
+@endcode
+
+@note replace the armv4compiler with your ARM v4 cross compiler.
 */
diff --git a/board/a9m2440/a9m2440.c b/board/a9m2440/a9m2440.c
index 43ec75b932..4f52a85b26 100644
--- a/board/a9m2440/a9m2440.c
+++ b/board/a9m2440/a9m2440.c
@@ -235,4 +235,20 @@ This CPU card is based on a Samsung S3C2440 CPU. The card is shipped with:
 - SPI interface
 - JTAG interface
 
+How to get the binary image:
+
+Using the default configuration:
+
+@code
+make ARCH=arm a9m2440_defconfig
+@endcode
+
+Build the binary image:
+
+@code
+make ARCH=arm CROSS_COMPILE=armv4compiler
+@endcode
+
+@note replace the armv4compiler with your ARM v4 cross compiler.
+
 */
diff --git a/board/board.dox b/board/board.dox
index cd683dd3e6..466fc591ed 100644
--- a/board/board.dox
+++ b/board/board.dox
@@ -88,4 +88,8 @@ TBD
 
 First, the new board should be visible in the menu.
 
+@section board_specific_cpu Porting hints for specific CPUs
+
+@li @subpage dev_s3c24xx_mach
+
 */
diff --git a/common/startup.c b/common/startup.c
index f0448e6f2b..e40759d2c6 100644
--- a/common/startup.c
+++ b/common/startup.c
@@ -25,6 +25,10 @@
  * MA 02111-1307 USA
  */
 
+/**
+ * @file
+ * @brief Main entry into the C part of U-Boot-v2
+ */
 #include <common.h>
 #include <init.h>
 #include <command.h>
diff --git a/drivers/serial/serial_ns16550.c b/drivers/serial/serial_ns16550.c
index 0dc389c5c6..524190dbc3 100644
--- a/drivers/serial/serial_ns16550.c
+++ b/drivers/serial/serial_ns16550.c
@@ -51,8 +51,8 @@
 /**
  * @brief ns16550_calc_divisor - compute the divisor for a baud rate
  *
- * @param[in] cdev - pointer to console device
- * @param[in] baudrate - baud rate
+ * @param[in] cdev pointer to console device
+ * @param[in] baudrate baud rate
  *
  * @return divisor to be set
  */
@@ -89,7 +89,7 @@ static unsigned int ns16550_calc_divisor(struct console_device *cdev,
 /**
  * @brief ns16550_serial_init_port - initialize the device
  *
- * @param cdev[in] - pointer to console device
+ * @param[in] cdev pointer to console device
  */
 static void ns16550_serial_init_port(struct console_device *cdev)
 {
@@ -122,8 +122,8 @@ static void ns16550_serial_init_port(struct console_device *cdev)
 /**
  * @brief ns16550_putc- put a character to the serial port
  *
- * @param cdev[in] - pointer to console device
- * @param c[in] - character to put
+ * @param[in] cdev pointer to console device
+ * @param[in] c character to put
  */
 static void ns16550_putc(struct console_device *cdev, char c)
 {
@@ -138,7 +138,7 @@ static void ns16550_putc(struct console_device *cdev, char c)
 /**
  * @brief ns16550_getc - retrieve a character from serial port
  *
- * @param cdev[in] - pointer to console device
+ * @param[in] cdev pointer to console device
  *
  * @return return the character read
  */
@@ -155,7 +155,7 @@ static int ns16550_getc(struct console_device *cdev)
 /**
  * @brief ns16550_tstc - test if character is available
  *
- * @param cdev[in] -pointer to console device
+ * @param[in] cdev pointer to console device
  *
  * @return  - status based on data availability
  */
@@ -170,8 +170,8 @@ static int ns16550_tstc(struct console_device *cdev)
 /**
  * @brief ns16550_setbaudrate - set the baudrate for the uart port
  *
- * @param cdev[in] - console device
- * @param baud_rate[in] - baud rate to set
+ * @param[in] cdev  console device
+ * @param[in] baud_rate baud rate to set
  *
  * @return  0-implied to support the baudrate
  */
@@ -192,10 +192,9 @@ static int ns16550_setbaudrate(struct console_device *cdev, int baud_rate)
 }
 
 /**
- * @brief ns16550_probe - Probe entry point -called on the first
- *			  match for device
+ * @brief ns16550_probe - Probe entry point -called on the first match for device
  *
- * @param dev[in]  - matched device
+ * @param[in] dev matched device
  *
  * @return EINVAL if platform_data is not populated,
  *	   ENOMEM if calloc failed
diff --git a/lib/parameter.c b/lib/parameter.c
index 6d8ac485b2..1f683b2684 100644
--- a/lib/parameter.c
+++ b/lib/parameter.c
@@ -20,6 +20,10 @@
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  */
 
+/**
+ * @file
+ * @brief Handling device specific parameters
+ */
 #include <common.h>
 #include <param.h>
 #include <errno.h>
@@ -125,3 +129,66 @@ int dev_add_param(struct device_d *dev, struct param_d *newparam)
 
 	return 0;
 }
+
+/** @page dev_params Device parameters
+
+@section params_devices Devices can have several parameters.
+
+In case of a network device this may be the IP address, networking mask or
+similar and users need access to these parameters. In U-Boot this is solved
+with device paramters. Device parameters are always strings, although there
+are functions to interpret them as something else. 'hush' users can access
+parameters as a local variable which have a dot (.) in them. So setting the
+IP address of the first ethernet device is a matter of typing
+'eth0.ip=192.168.0.7' on the console and can then be read back with
+'echo $eth0.ip'. The @ref devinfo_command command shows a summary about all
+devices currently present. If called with a device id as parameter it shows the
+parameters available for a device.
+
+@section params_programming Device parameters programming API
+
+@code
+struct param_d {
+	char* (*get)(struct device_d *, struct param_d *param);
+	int (*set)(struct device_d *, struct param_d *param, const char *val);
+	ulong flags;
+	char *name;
+	struct param_d *next;
+	char *value;
+};
+@endcode
+
+@code
+int dev_add_param(struct device_d *dev, struct param_d *newparam);
+@endcode
+
+This function adds a new parameter to a device. At least the name field in
+the new parameter struct has to be initialized. The 'get' and 'set' fields
+can be set to NULL in which case the framework handles them. It is also
+allowed to implement only one of the get/set functions. Care must be taken
+with the initial value of the parameter. If the framework handles the set
+function it will try to free the value of the parameter. If this is a
+static array bad things will happen. A parameter can have the flag
+PARAM_FLAG_RO which means that the parameter is readonly. It is perfectly ok
+then to point the value to a static array.
+
+@code
+const char *dev_get_param(struct device_d *dev, const char *name);
+@endcode
+
+This function returns a pointer to the value of the parameter specified
+with dev and name.
+If the framework handles the get/set functions the parameter value strings
+are alloceted with malloc and freed with free when another value is set for
+this parameter. Drivers implementing set/get themselves are allowed to
+return values in static arrays. This means that the pointers returned from
+dev_get_param() are only valid until the next call to dev_get_param. If this
+is not long enough strdup() or similar must be used.
+
+@code
+int dev_set_param(struct device_d *dev, const char *name, const char *val);
+@endcode
+
+Set the value of a parameter.
+
+*/