diff --git a/Documentation/commands.dox b/Documentation/commands.dox index 50e383f..fe539e5 100644 --- a/Documentation/commands.dox +++ b/Documentation/commands.dox @@ -1,15 +1,24 @@ /** * @page command_reference Supported Shell Commands - - @subpage sh_command + - @subpage addpart_command - @subpage cat_command - @subpage cd_command - @subpage cp_command - - @subpage printenv_command - - @subpage saveenv_command - - @subpage loadenv_command - - @subpage setenv_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 */ diff --git a/Documentation/developers_manual.dox b/Documentation/developers_manual.dox index 3163c94..59723ef 100644 --- a/Documentation/developers_manual.dox +++ b/Documentation/developers_manual.dox @@ -16,5 +16,7 @@ Various themes: - @subpage how_mount_works + - @subpage boot_preparation + - @subpage uboot_simul */ \ No newline at end of file diff --git a/Documentation/users_manual.dox b/Documentation/users_manual.dox index 1decdc0..e346a12 100644 --- a/Documentation/users_manual.dox +++ b/Documentation/users_manual.dox @@ -1,7 +1,10 @@ /** @page users_manual User's Manual -FIXME: Hints and tips for simply using U-Boot v2 +Who should read this part? +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 diff --git a/Doxyfile b/Doxyfile index 5d68f78..38b4011 100644 --- a/Doxyfile +++ b/Doxyfile @@ -418,7 +418,7 @@ # for undocumented members. If EXTRACT_ALL is set to YES then this flag will # automatically be disabled. -WARN_IF_UNDOCUMENTED = YES +WARN_IF_UNDOCUMENTED = NO # If WARN_IF_DOC_ERROR is set to YES, doxygen will generate warnings for # potential errors in the documentation, such as not documenting some diff --git a/arch/architecture.dox b/arch/architecture.dox index 85cff53..3f94b3c 100644 --- a/arch/architecture.dox +++ b/arch/architecture.dox @@ -1,6 +1,33 @@ /** @page dev_architecture Integrate a new architecture (ARCH) -Friesel +@section linker_scripts Rules for the generic Linker Script File + +Never include an object file by name directly! Linker Script Files defines the +layout, not the content. Content is defined in objecfiles instead. + +Don't rely on the given object file order to create your binary U-Boot v2! This +may work, but is not relyable in all cases (and its a very bad style)! + +For the special case some layout contraints exists, use specific section +naming instead. Refer @ref reset_code how to define this specific section. + +@section reset_code Bring it up: The Reset Code + +The way a CPU wakes up after reset is very specific to its architecture. + +For example the ARM architecture starts its reset code at address 0x0000000, +the x86 architecture at 0x000FFFF0, PowerPC at 0x00000100 or 0xFFFFF100. + +So for the special reset code on all architectures it must be located at +architecture specific locations within the binary U-Boot image. + +All reset code uses section ".text_entry" for its localisation within the +binary U-Boot image. Its up to the linker script file to use this section name +to find the right place in whatever environment and U-Boot sizes. + +@code + .section ".text_entry","ax" +@endcode */ diff --git a/arch/arm/cpu/cpu.c b/arch/arm/cpu/cpu.c index e2b31ed..d79d4ce 100644 --- a/arch/arm/cpu/cpu.c +++ b/arch/arm/cpu/cpu.c @@ -1,7 +1,37 @@ +/* + * cpu.c - A few helper functions for ARM + * + * Copyright (c) 2007 Sascha Hauer , Pengutronix + * + * See file CREDITS for list of people who contributed to this + * project. + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License version 2 + * as published by the Free Software Foundation. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + */ + +/** + * @file + * @brief A few helper functions for ARM + */ + #include #include -/* read co-processor 15, register #1 (control register) */ +/** + * Read special processor register + * @return co-processor 15, register #1 (control register) + */ static unsigned long read_p15_c1 (void) { unsigned long value; @@ -18,7 +48,12 @@ return value; } -/* write to co-processor 15, register #1 (control register) */ +/** + * + * Write special processor register + * @param[in] value to write + * @return to co-processor 15, register #1 (control register) + */ static void write_p15_c1 (unsigned long value) { #ifdef MMU_DEBUG @@ -33,23 +68,38 @@ read_p15_c1 (); } +/** + * Wait for co prozessor (waste time) + * Co processor seems to need some delay between accesses + */ static void cp_delay (void) { volatile int i; - /* copro seems to need some delay between reading and writing */ - for (i = 0; i < 100; i++); + for (i = 0; i < 100; i++) /* FIXME does it work as expected?? */ + ; } -#define C1_MMU (1<<0) /* mmu off/on */ -#define C1_ALIGN (1<<1) /* alignment faults off/on */ -#define C1_DC (1<<2) /* dcache off/on */ -#define C1_BIG_ENDIAN (1<<7) /* big endian off/on */ -#define C1_SYS_PROT (1<<8) /* system protection */ -#define C1_ROM_PROT (1<<9) /* ROM protection */ -#define C1_IC (1<<12) /* icache off/on */ -#define C1_HIGH_VECTORS (1<<13) /* location of vectors: low/high addresses */ +/** mmu off/on */ +#define C1_MMU (1<<0) +/** alignment faults off/on */ +#define C1_ALIGN (1<<1) +/** dcache off/on */ +#define C1_DC (1<<2) +/** big endian off/on */ +#define C1_BIG_ENDIAN (1<<7) +/** system protection */ +#define C1_SYS_PROT (1<<8) +/** ROM protection */ +#define C1_ROM_PROT (1<<9) +/** icache off/on */ +#define C1_IC (1<<12) +/** location of vectors: low/high addresses */ +#define C1_HIGH_VECTORS (1<<13) +/** + * Enable processor's instruction cache + */ void icache_enable (void) { ulong reg; @@ -59,6 +109,9 @@ write_p15_c1 (reg | C1_IC); } +/** + * Disable processor's instruction cache + */ void icache_disable (void) { ulong reg; @@ -68,30 +121,39 @@ write_p15_c1 (reg & ~C1_IC); } +/** + * Detect processor's current instruction cache status + * @return 0=disabled, 1=enabled + */ int icache_status (void) { return (read_p15_c1 () & C1_IC) != 0; } -/* - * this function is called just before we call linux - * it prepares the processor for linux +/** + * Prepare a "clean" CPU for Linux to run + * @return 0 (always) + * + * This function is called by the generic U-Boot part just before we call + * Linux. It prepares the processor for Linux. */ int cleanup_before_linux (void) { int i; - /* - * we never enable dcache so we do not need to disable - * it. Linux can be called with icache enabled, so just - * do nothing here - */ - /* flush I/D-cache */ i = 0; asm ("mcr p15, 0, %0, c7, c7, 0": :"r" (i)); return (0); } +/** + * @page arm_boot_preparation Linux Preparation on ARM + * + * For ARM we never enable data cache so we do not need to disable it again. + * Linux can be called with instruction cache enabled. As this is the + * default setting we are running in U-Boot, there's no special preparation + * required. + */ #ifdef CONFIG_USE_IRQ static int cpu_init (void) @@ -106,3 +168,9 @@ core_initcall(cpu_init); #endif + +/** + * @page arm_for_linux Preparing for Linux to run + * + * What's to do on ARM to run Linux after U-Boot did its job? + */ \ No newline at end of file diff --git a/arch/arm/cpu/interrupts.c b/arch/arm/cpu/interrupts.c index 23f8b3f..418da18 100644 --- a/arch/arm/cpu/interrupts.c +++ b/arch/arm/cpu/interrupts.c @@ -1,3 +1,30 @@ +/* + * interrupts.c - Interrupt Support Routines + * + * Copyright (c) 2007 Sascha Hauer , Pengutronix + * + * See file CREDITS for list of people who contributed to this + * project. + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License version 2 + * as published by the Free Software Foundation. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + */ + +/** + * @file + * @brief Interrupt Support Routines + */ + #include #include @@ -32,12 +59,19 @@ } #endif +/** + * FIXME + */ void bad_mode (void) { panic ("Resetting CPU ...\n"); reset_cpu (0); } +/** + * Display current register set content + * @param[in] regs Guess what + */ void show_regs (struct pt_regs *regs) { unsigned long flags; @@ -75,6 +109,10 @@ thumb_mode (regs) ? " (T)" : ""); } +/** + * The CPU runs into an undefined instruction. That really should not happen! + * @param[in] pt_regs Register set content when the accident happens + */ void do_undefined_instruction (struct pt_regs *pt_regs) { printf ("undefined instruction\n"); @@ -82,6 +120,13 @@ bad_mode (); } +/** + * The CPU catches a software interrupt + * @param[in] pt_regs Register set content when the interrupt happens + * + * There is not functione behind this feature. So what to do else than + * a reset? + */ void do_software_interrupt (struct pt_regs *pt_regs) { printf ("software interrupt\n"); @@ -89,6 +134,12 @@ bad_mode (); } +/** + * The CPU catches a prefetch abort. That really should not happen! + * @param[in] pt_regs Register set content when the accident happens + * + * FIXME: What does it mean, why is reset the only solution? + */ void do_prefetch_abort (struct pt_regs *pt_regs) { printf ("prefetch abort\n"); @@ -96,6 +147,12 @@ bad_mode (); } +/** + * The CPU catches a data abort. That really should not happen! + * @param[in] pt_regs Register set content when the accident happens + * + * FIXME: What does it mean, why is reset the only solution? + */ void do_data_abort (struct pt_regs *pt_regs) { printf ("data abort\n"); @@ -103,6 +160,12 @@ bad_mode (); } +/** + * The CPU catches a not-used(?) abort. + * @param[in] pt_regs Register set content when the accident happens + * + * FIXME: What does it mean, why is reset the only solution? + */ void do_not_used (struct pt_regs *pt_regs) { printf ("not used\n"); @@ -110,6 +173,12 @@ bad_mode (); } +/** + * The CPU catches a fast interrupt request. + * @param[in] pt_regs Register set content when the interrupt happens + * + * FIXME: What does it mean, why is reset the only solution? + */ void do_fiq (struct pt_regs *pt_regs) { printf ("fast interrupt request\n"); @@ -117,9 +186,21 @@ bad_mode (); } +/** + * The CPU catches a regular interrupt. + * @param[in] pt_regs Register set content when the interrupt happens + * + * FIXME: What does it mean, why is reset the only solution? + */ void do_irq (struct pt_regs *pt_regs) { printf ("interrupt request\n"); show_regs (pt_regs); bad_mode (); } + +/** + * @page arm_interrupts Interrupt handling on ARM + * + * Why U-boot doesn't use interrupts? + */ diff --git a/arch/arm/cpu/start-arm920t.S b/arch/arm/cpu/start-arm920t.S index eed1364..db52ad9 100644 --- a/arch/arm/cpu/start-arm920t.S +++ b/arch/arm/cpu/start-arm920t.S @@ -24,13 +24,18 @@ * MA 02111-1307 USA */ -/* - * Note: - * This file can be used for at least: - * - ARM920T - * - i.MX1 - * - i.MX27 - * - i.MX31 +/** + * @file + * @brief The very basic beginning of each CPU after reset + * + * @note + * This reset code can be used at least for: + * - ARM920T + * - i.MX1 + * - i.MX27 + * - i.MX31 + * + * FIXME: Stop doxygen from parsing the text below */ .section ".text_entry","ax" diff --git a/arch/arm/mach-arm.dox b/arch/arm/mach-arm.dox index 8443b73..862b339 100644 --- a/arch/arm/mach-arm.dox +++ b/arch/arm/mach-arm.dox @@ -12,22 +12,22 @@ to: "runtime address != link address". You should only use branches and do not refer to fixed data. This implies the use of assembler code only. -The ARM CPU starts at lable in one of the corresponding start-*.S +The ARM CPU starts at lable \ in one of the corresponding start-*.S files. After some basic hardware setup it can call a function - if not disabled. This call is intended to give all +\ if not disabled. This call is intended to give all developers a chance to use a standard reset vector file, but also do some special things required only on their specific CPU. -After handling some MMU related things can be called (if +After handling some MMU related things \ 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. -When returns it will be assumed there is now a working +When \ 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 . This target address is -the first C instruction in U-Boot. At this point of time: +assembler instruction is a jump into \. This target address is +the first C instruction in U-Boot. At this point of time:\n "runtime address == link address". */ diff --git a/arch/sandbox/lib/common.c b/arch/sandbox/lib/common.c index 6416a54..0db4403 100644 --- a/arch/sandbox/lib/common.c +++ b/arch/sandbox/lib/common.c @@ -20,6 +20,10 @@ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */ +/** + * @file + * @brief Common wrapper functions between U-Boot and the host + */ /* * These are host includes. Never include any U-Boot header * files here... @@ -249,26 +253,7 @@ return -1; } -static void print_usage(const char *prgname) -{ - printf( -"Usage: %s [OPTIONS]\n" -"Start U-Boot.\n" -"Options:\n" -" -i Map a file to U-Boot. This option can be given multiple\n" -" times. The files will show up as /dev/fd0 ... /dev/fdx\n" -" under U-Boot.\n" -" -e Map a file to U-Boot. With this option files are mapped as\n" -" /dev/env0 ... /dev/envx and thus are used as default\n" -" environment. An empty file generated with dd will do to get\n" -" started wth an empty environment\n" -" -O Register file as a console capable of doing stdout. File can\n" -" be a regular file or a fifo.\n" -" -I Register file as a console capable of doing stdin. File can\n" -" be a regular file or a fifo.\n", - prgname - ); -} +static void print_usage(const char*); int main(int argc, char *argv[]) { @@ -337,3 +322,62 @@ return 0; } +static void print_usage(const char *prgname) +{ + printf( +"Usage: %s [OPTIONS]\n" +"Start U-Boot.\n" +"Options:\n" +" -i Map a file to U-Boot. This option can be given multiple\n" +" times. The files will show up as /dev/fd0 ... /dev/fdx\n" +" under U-Boot.\n" +" -e Map a file to U-Boot. With this option files are mapped as\n" +" /dev/env0 ... /dev/envx and thus are used as default\n" +" environment. An empty file generated with dd will do to get\n" +" started wth an empty environment\n" +" -O Register file as a console capable of doing stdout. File can\n" +" be a regular file or a fifo.\n" +" -I Register file as a console capable of doing stdin. File can\n" +" be a regular file or a fifo.\n", + prgname + ); +} + +/** + * @page uboot_simul U-Boot Simulator + * + * U-Boot can be run as a simulator on your host to check and debug new non + * hardware related features. + * + * @section simu_build How to build U-Boot for simulation + * + * @section simu_run How to run U-Boot simulator + * + * $ uboot [] + * + * Options can be: + * + * -i + * + * Map a to U-Boot. This option can be given multiple times. The s + * will show up as /dev/fd0 ... /dev/fdx in the U-Boot simulator. + * + * -e + * + * Map to U-Boot. With this option s are mapped as /dev/env0 ... + * /dev/envx and thus are used as default environment. A clean file generated + * with dd will do to get started with an empty environment + * + * -O + * + * Register as a console capable of doing stdout. can be a + * regular file or a fifo. + * + * -I + * + * Register as a console capable of doing stdin. can be a regular + * file or a fifo. + * + * @section simu_dbg How to debug U-Boot simulator + * + */ \ No newline at end of file diff --git a/arch/sandbox/lib/tap.c b/arch/sandbox/lib/tap.c index b620612..ebd828b 100644 --- a/arch/sandbox/lib/tap.c +++ b/arch/sandbox/lib/tap.c @@ -61,3 +61,8 @@ strcpy(dev, ifr.ifr_name); return fd; } + +/** + * @file + * @brief Host side functions for tap driver + */ diff --git a/board/board.dox b/board/board.dox index 390a6c2..a4c6dc5 100644 --- a/board/board.dox +++ b/board/board.dox @@ -1,5 +1,91 @@ -/** @page dev_board Integrating a new Board +/** @page dev_board Adapting a new Board -Blablubb +To add a new board to U-Boot a few steps must be done, to extend and modify +the U-Boot source tree. + +@section board_add_files Files/Directories to be added + + - board/\ + - board/\/Makefile + - board/\/\.c + - board/\/\.dox + - include/configs/\.h + - arch/\/configs/\_defconfig + +@subsection board_makefile board/\Makefile + +@verbatim + obj-y += all files that builds the BSP (Assembler and/or C files) +@endverbatim + +@subsection board_basefile board/\\.c + +TBD + +@subsection board_doxygen board/\/\.dox + +This file should describe in short words your new board, what CPU +it uses, what resources are provided and features it supports. + +Use the doxygen style for this kind of documentation. Below you find a +template for this kind of file: + +@verbatim +/** @page + +This board uses an based CPU. The board is shipped with: + +- many MiB NOR type Flash Memory +- many MiB SDRAM +- a very special network controller + +and so on. + +*/ +@endverbatim + +To make your new shiny file visible in the automatically generated +documentation you must sort in the used page lable ("" in the +template above) into Documentation/boards.dox as: + +@verbatim + ... + @subpage + ... +@endverbatim + +at the right architecture. + +@note Consider to use an unique page lable. + +@subsection board_lscript board/\/u-boot.ld.S + +If your board needs a special binary U-Boot layout, you can provide a local +board linker script file. This will replace the generic one provided by your +architecture or CPU support. + +Add this file with + +@verbatim + extra-y += +@endverbatim + +in your local \b Makefile to the list of files, forwarded to the last linking step. + +@section board_defconfig arch/\/configs/\_defconfig + +TBD + +@section board_mod_files These files needs to be modified: + + - modify board/board.doc + - modify arch/\/Kconfig + - add your board (MACH_*) to the list + - add your default text base address for this architecture (ARCH_TEXT_BASE) + - add BOARDINFO with valueable info for your board + - modify arch/\/Makefile: + - add board-$(MACH_*) = \ + +First, the new board should be visible in the menu. */ diff --git a/commands/bootm.c b/commands/bootm.c index e943934..755d3a9 100644 --- a/commands/bootm.c +++ b/commands/bootm.c @@ -853,3 +853,20 @@ } #endif /* CONFIG_LYNXKDI */ + +/** + * @file + * @brief Boot support for Linux + */ + +/** + * @page boot_preparation Preparing for Boot + * + * This chapter describes what's to be done to forward the control from + * U-Boot to Linux. This part describes the generic part, below you can find + * the architecture specific part. + * + * - @subpage arm_boot_preparation + * - @subpage ppc_boot_preparation + * - @subpage x86_boot_preparation + */ \ No newline at end of file diff --git a/commands/cat.c b/commands/cat.c index af33eca..6596612 100644 --- a/commands/cat.c +++ b/commands/cat.c @@ -97,7 +97,7 @@ /** * @page cat_command cat (concatenate) * - * Usage is: cat [ ...] + * Usage is: cat \ [\ ...] * * Concatenate files to stdout. Currently only printable characters * and \\n and \\t are printed, but this should be optional diff --git a/commands/cd.c b/commands/cd.c index 08c3a2d..5d5cacb 100644 --- a/commands/cd.c +++ b/commands/cd.c @@ -61,7 +61,8 @@ /** * @page cd_command cd (change working directory) * - * Usage is: cd [] + * Usage is: cd [\] * - * Change to . If called without argument, change to / (root) + * Change to \. If called without argument, change to \b / + * (root) */ diff --git a/commands/cp.c b/commands/cp.c index e26ff1f..a89bb97 100644 --- a/commands/cp.c +++ b/commands/cp.c @@ -151,7 +151,7 @@ /** * @page cp_command cp (copy) * - * Usage: cp [] + * Usage: cp \ [\] \ * * FIXME */ diff --git a/commands/edit.c b/commands/edit.c index 0795d88..3a685eb 100644 --- a/commands/edit.c +++ b/commands/edit.c @@ -1,6 +1,4 @@ /* - * edit.c - A tiny editor implementation - * * Copyright (c) 2007 Sascha Hauer , Pengutronix * * See file CREDITS for list of people who contributed to this @@ -20,6 +18,11 @@ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */ +/** + * @file + * @brief A tiny editor implementation + */ + #include #include #include @@ -398,6 +401,7 @@ return 1; } + /* check if we are called as "sedit" insted of "edit" */ if (*argv[0] == 's') smartscroll = 1; @@ -564,3 +568,18 @@ .usage = "edit a file", U_BOOT_CMD_HELP(cmd_edit_help) U_BOOT_CMD_END + + +/** + * @page edit_command edit (editor) + * + * Usage is: [s]edit \ + * + * This is a very small editor. It's only features are moving the cursor with + * the usual keys and typing characters. + * + * \b \ quits the editor without saving,\n + * \b \ quits the editor with saving the current file. + * + * If called as \c sedit the editor uses ansi codes to scroll the screen. + */ diff --git a/commands/environment.c b/commands/environment.c index b5517aa..01e7cfe 100644 --- a/commands/environment.c +++ b/commands/environment.c @@ -227,13 +227,13 @@ /** * @page saveenv_command saveenv * - * Usage: saveenv [] [] + * Usage: saveenv [\] [\] * - * Save the files in to the persistent storage device . - * is normally a block in flash, but could be any other file. + * Save the files in \ to the persistent storage device \. + * \ is normally a block in flash, but could be any other file. * - * If ommitted defaults to /env and defaults to - * /dev/env0. + * If ommitted \ defaults to \b /env and \ defaults to + * \b /dev/env0. * * @note envfs can only handle files. Directories are skipped silently. */ @@ -372,12 +372,12 @@ /** * @page loadenv_command loadenv * - * Usage: loadenv [] [] + * Usage: loadenv [\] [\] * - * Load the persistent storage contained in to the directory . + * Load the persistent storage contained in \ to the directory \. * - * If ommitted defaults to /env and defaults to - * /dev/env0. + * If ommitted \ defaults to /env and \ defaults to + * \b /dev/env0. * * @note envfs can only handle files. Directories are skipped silently. */ diff --git a/commands/flash.c b/commands/flash.c index 835663c..cfbf903 100644 --- a/commands/flash.c +++ b/commands/flash.c @@ -23,6 +23,11 @@ * MA 02111-1307 USA */ +/** + * @file + * @brief Flash memory support: erase, protect, unprotect + */ + #include #include #include @@ -92,6 +97,18 @@ U_BOOT_CMD_HELP(cmd_erase_help) U_BOOT_CMD_END +/** @page erase_command erase Erase flash memory + * + * Usage is: erase \ + * + * Erase the flash memory behind the device. It depends on the device given, + * what area will be erased. If the device represents the whole flash memory + * the whole memory will be erased. If the device represents a partition on + * a main flash memory, only this partition part will be erased. + * + * Refer \b addpart, \b delpart and \b devinfo for partition handling. + */ + static int do_protect (cmd_tbl_t *cmdtp, int argc, char *argv[]) { int fd; @@ -163,3 +180,26 @@ U_BOOT_CMD_HELP(cmd_protect_help) U_BOOT_CMD_END +/** @page protect_command protect Protect a flash memory + * + * Usage is: protect \ + * + * Protect the flash memory behind the device. It depends on the device given, + * what area will be protected. If the device represents the whole flash memory + * the whole memory will be protected. If the device represents a partition on + * a main flash memory, only this partition part will be protected. + * + * Refer \b addpart, \b delpart and \b devinfo for partition handling. + */ + +/** @page unprotect_command unprotect Unprotect a flash memory + * + * Usage is: unprotect \ + * + * Unprotect the flash memory behind the device. It depends on the device given, + * what area will be unprotected. If the device represents the whole flash memory + * the whole memory will be unprotected. If the device represents a partition + * on a main flash memory, only this partition part will be unprotected. + * + * Refer \b addpart, \b delpart and \b devinfo for partition handling. + */ diff --git a/commands/mount.c b/commands/mount.c index dd04bde..03b63f0 100644 --- a/commands/mount.c +++ b/commands/mount.c @@ -80,16 +80,16 @@ U_BOOT_CMD_END /** @page mount_command mount - * Usage: mount [ ] + * Usage: mount [\ \ \] * - * Mounts a filesystem of a given on a to a . - * can be one of /dev/ * or some arbitrary string if no + * Mounts a filesystem of a given \ on a \ to a \. + * \ can be one of /dev/ * or some arbitrary string if no * device is needed for this driver (for example ramfs). * - * is the filesystem driver to use. Try the 'devinfo' command + * \ is the filesystem driver to use. Try the 'devinfo' command * for a list of available drivers. * - * must be an empty directory descending directly from the + * \ must be an empty directory descending directly from the * root directory. */ diff --git a/commands/net.c b/commands/net.c index 25115e4..faf87d6 100644 --- a/commands/net.c +++ b/commands/net.c @@ -1,6 +1,4 @@ /* - * tftp, rarpboot, dhcp, nfs, cdp - Boot support - * * (C) Copyright 2000 * Wolfgang Denk, DENX Software Engineering, wd@denx.de. * @@ -23,6 +21,11 @@ * MA 02111-1307 USA */ +/** + * @file + * @brief tftp, rarpboot, dhcp, nfs, cdp - Boot support + */ + #include #include #include @@ -102,6 +105,22 @@ U_BOOT_CMD_HELP(cmd_tftp_help) U_BOOT_CMD_END +/** + * @page tftp_command tftp + * + * Usage is: tftp \ [\] + * + * Load a file via network using BootP/TFTP protocol. The loaded file you + * can find after download in you current ramdisk. Refer \b ls command. + * + * \ can be the local filename only, or also a device name. In the + * case of a device name, the will gets stored there. This works also for + * partitions of flash memory. Refer \b erase, \b unprotect for flash + * preparation. + * + * Note: This command is available only, if enabled in the menuconfig. + */ + #ifdef CONFIG_NET_RARP static int do_rarpb (cmd_tbl_t *cmdtp, int argc, char *argv[]) { @@ -116,6 +135,16 @@ U_BOOT_CMD_END #endif /* CONFIG_NET_RARP */ +/** + * @page rarp_command rarp + * + * Usage is: FIXME + * + * Load a file via network using rarp/tftp protocol. FIXME: Where to find it + * after loading? + * @note This command is available only, if enabled in the menuconfig. + */ + #ifdef CONFIG_NET_DHCP static int do_dhcp (cmd_tbl_t *cmdtp, int argc, char *argv[]) { diff --git a/commands/partition.c b/commands/partition.c index f2b795b..886339c 100644 --- a/commands/partition.c +++ b/commands/partition.c @@ -21,6 +21,11 @@ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */ +/** + * @file + * @brief partition handling and addpart and delpart command + */ + #ifdef CONFIG_ENABLE_PARTITION_NOISE # define DEBUG #endif @@ -199,6 +204,26 @@ U_BOOT_CMD_HELP(cmd_addpart_help) U_BOOT_CMD_END +/** @page addpart_command addpart Add a partition to a device + * + * Usage is: addpart \ \ + * + * Adds a partition description to a device. The partition description has the + * form + * + * size1(name1)[ro],size2(name2)[ro],... + * + * \ is the device name under. Sizes can be given in decimal or - if + * prefixed with 0x - in hex. Sizes can have an optional suffix K,M,G. The + * size of the last partition can be specified as '-' for the remaining space + * of the device. + * + * @note The format is the same as used in the Linux kernel for cmdline mtd + * partitions. + * + * @note This command has to be reworked and will probably change it's API. + */ + static int do_delpart(cmd_tbl_t * cmdtp, int argc, char *argv[]) { struct device_d *dev; @@ -230,3 +255,9 @@ U_BOOT_CMD_HELP(cmd_delpart_help) U_BOOT_CMD_END +/** @page delpart_command delpart Delete a partition + * + * Usage is: delpart \ + * + * Delete a partition previously added to a device with addpart. + */ diff --git a/common/env.c b/common/env.c index c8cb29a..96a8ed0 100644 --- a/common/env.c +++ b/common/env.c @@ -61,7 +61,7 @@ /** * Remove a list of environment variables - * @param[inout] v Variable anchor to remove + * @param[in] v Variable anchor to remove */ static void free_variables(struct variable_d *v) { @@ -306,12 +306,12 @@ /** * @page printenv_command printenv * - * Usage: printenv [] + * Usage: printenv [\] * * Print environment variables. - * If was given, it prints out its content if the environment variable - * exists. - * Without the argument all current environment variables are printed. + * If \ was given, it prints out its content if the environment variable + * \ exists. + * Without the \ argument all current environment variables are printed. */ #ifdef CONFIG_SIMPLE_PARSER @@ -342,14 +342,14 @@ /** * @page setenv_command setenv * - * Usage: setenv [] + * Usage: setenv \ [\] * - * Set environment variable to - * If no was given, the variable will be removed. + * Set environment variable \ to \ + * If no \ was given, the variable \ will be removed. * * This command can be replaced by using the simpler form in the hush: * - * = + * \ = \ * * @note This command is only required if the simple * parser (not the hush) is in use. @@ -394,7 +394,7 @@ /** * @page export_command export * - * Usage: export [=value]... + * Usage: export \[=value]... * * Export an environment variable to subsequently executed scripts */ diff --git a/common/hush.c b/common/hush.c index d85f857..c05b564 100644 --- a/common/hush.c +++ b/common/hush.c @@ -1574,15 +1574,15 @@ /** @page sh_command Starting shell * - * Usage: sh [] + * Usage: sh \ [\] * - * Execute a shell script named and forward (if given) - * to it. + * Execute a shell script named \ and forward (if given) + * \ to it. * - * Usage: . [] - * or source [] + * Usage: . \ [\] + * or source \ [\] * - * Read and execute commands from in the current shell environment, - * forward (if given) to it and return the exit status of the last + * Read and execute commands from \ in the current shell environment, + * forward (if given) \ to it and return the exit status of the last * command executed from filename. */ diff --git a/common/partition.c b/common/partition.c index bb4006e..4942ffd 100644 --- a/common/partition.c +++ b/common/partition.c @@ -230,18 +230,18 @@ What we want: -@code +@verbatim device nor0 |--- partition 0 |--- partition 1 |--- partition 2 |--- partition 3 `--- partition 4 -@endcode +@endverbatim How to get: -@code +@verbatim $ addpart /dev/nor0 256k(uboot),128k(env),256k(bla),1024k(blubb),2048k(friesel) $ devinfo |---nor0.uboot @@ -249,7 +249,7 @@ |---nor0.bla |---nor0.blubb |---nor0.friesel -@endcode +@endverbatim @par Partitions with sub partitions: @@ -258,7 +258,7 @@ What we want: -@code +@verbatim device nor0 |--- partition 0 |--- partition 1 @@ -267,11 +267,11 @@ `--- partition 4 |--- partition 0 `--- partition 1 -@endcode +@endverbatim How to get: -@code +@verbatim $ addpart /dev/nor0 256k(uboot),128k(env),256k(bla),1M(blubb),2048k(friesel) $ devinfo |---nor0.uboot @@ -289,15 +289,15 @@ |---nor0.friesel |---nor0.friesel.fussel `---nor0.friesel.boerks -@endcode +@endverbatim @par Forwarding partitions to the kernel: -@code +@verbatim $ device="nor0" $ partitions="256k(uboot),128k(env),256k(bla),1024k(blubb),2048k(friesel)" $ addpart /dev/$device:$partitions -@endcode +@endverbatim @par Removing partitions: diff --git a/drivers/cfi_flash.c b/drivers/cfi_flash.c index 773ee2b..a859741 100644 --- a/drivers/cfi_flash.c +++ b/drivers/cfi_flash.c @@ -31,8 +31,9 @@ * */ -/* The DEBUG define must be before common to enable debugging */ -/* #define DEBUG */ +#ifdef CONFIG_ENABLE_FLASH_NOISE +# define DEBUG +#endif #include #include @@ -42,22 +43,6 @@ #include #include -/* - * This file implements a Common Flash Interface (CFI) driver for U-Boot. - * The width of the port and the width of the chips are determined at initialization. - * These widths are used to calculate the address for access CFI data structures. - * - * References - * JEDEC Standard JESD68 - Common Flash Interface (CFI) - * JEDEC Standard JEP137-A Common Flash Interface (CFI) ID Codes - * Intel Application Note 646 Common Flash Interface (CFI) and Command Sets - * Intel 290667-008 3 Volt Intel StrataFlash Memory datasheet - * AMD CFI Specification, Release 2.0 December 1, 2001 - * AMD/Spansion Application Note: Migration from Single-byte to Three-byte - * Device IDs, Publication Number 25538 Revision A, November 8, 2001 - * - */ - #define FLASH_CMD_CFI 0x98 #define FLASH_CMD_READ_ID 0x90 #define FLASH_CMD_RESET 0xff @@ -326,16 +311,14 @@ dev->priv = (void *)info; - printf("cfi_probe: %s base: 0x%08x size: 0x%08x\n", dev->name, dev->map_base, dev->size); + debug ("cfi_probe: %s base: 0x%08x size: 0x%08x\n", dev->name, dev->map_base, dev->size); /* Init: no FLASHes known */ info->flash_id = FLASH_UNKNOWN; size += info->size = flash_get_size(info, dev->map_base); if (info->flash_id == FLASH_UNKNOWN) { -#ifndef CFG_FLASH_QUIET_TEST - printf ("## Unknown FLASH on Bank at 0x%08x - Size = 0x%08lx = %ld MB\n", + debug ("## Unknown FLASH on Bank at 0x%08x - Size = 0x%08lx = %ld MB\n", dev->map_base, info->size, info->size << 20); -#endif /* CFG_FLASH_QUIET_TEST */ } return 0; @@ -1495,3 +1478,22 @@ } #endif /* CONFIG_CFI_BUFFER_WRITE */ +/** + * @file + * @brief This file implements a Common Flash Interface (CFI) driver for U-Boot. + * + * This file implements a Common Flash Interface (CFI) driver for U-Boot. + * The width of the port and the width of the chips are determined at initialization. + * These widths are used to calculate the address for access CFI data structures. + * + * References + * + * - JEDEC Standard JESD68 - Common Flash Interface (CFI) + * - JEDEC Standard JEP137-A Common Flash Interface (CFI) ID Codes + * - Intel Application Note 646 Common Flash Interface (CFI) and Command Sets + * - Intel 290667-008 3 Volt Intel StrataFlash Memory datasheet + * - AMD CFI Specification, Release 2.0 December 1, 2001 + * - AMD/Spansion Application Note: Migration from Single-byte to Three-byte + * Device IDs, Publication Number 25538 Revision A, November 8, 2001 + * + */ diff --git a/lib/driver.c b/lib/driver.c index a356b4e..e7c98a4 100644 --- a/lib/driver.c +++ b/lib/driver.c @@ -20,6 +20,11 @@ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */ +/** + * @file + * @brief U-Boot's driver model, and devinfo command + */ + #include #include #include @@ -321,7 +326,7 @@ "Usage: devinfo [DEVICE]\n" "If called without arguments devinfo shows a summary about known devices and\n" "drivers. If called with a device path as argument devinfo shows more detailed\n" -"informations about this device and its parameters.\n"; +"information about this device and its parameters.\n"; U_BOOT_CMD_START(devinfo) .maxargs = 2, @@ -329,3 +334,30 @@ .usage = "display info about devices and drivers", U_BOOT_CMD_HELP(cmd_devinfo_help) U_BOOT_CMD_END + +/** + * @page devinfo_command devinfo + * + * Usage is: devinfo /dev/\ + * + * If called without arguments devinfo shows a summary about known devices and + * drivers. If called with a device path as argument devinfo shows more + * detailed information about this device and its parameters. + * + * Example from an MPC5200 based system: +@verbatim + uboot:/ devinfo /dev/eth0 + base : 0x1002b000 + size : 0x00000000 + driver: fec_mpc5xxx + + no info available for eth0 + Parameters: + ip = 192.168.23.197 + ethaddr = 80:81:82:83:84:86 + gateway = 192.168.23.1 + netmask = 255.255.255.0 + serverip = 192.168.23.2 +@endverbatim + * + */