move board.dox to Documentation and update it

Signed-off-by: Jean-Christophe PLAGNIOL-VILLARD <plagnioj@jcrosoft.com>

2 files changed, 97 insertions, 2 deletions

diff --git a/Documentation/board.dox b/Documentation/board.dox
new file mode 100644
index 0000000000..07425e4ea9
--- /dev/null
+++ b/Documentation/board.dox
@@ -0,0 +1,95 @@
+/** @page dev_board Adapting a new Board
+
+To add a new board to @a barebox a few steps must be done, to extend and modify
+the @a barebox source tree.
+
+@section board_add_files Files/Directories to be added
+
+ - arch/\<architecture\>/boards/\<boardname\>
+ - arch/\<architecture\>/boards/\<boardname\>/Makefile
+ - arch/\<architecture\>/boards/\<boardname\>/\<boardname\>.c
+ - arch/\<architecture\>/boards/\<boardname\>/\<boardname\>.dox
+ - include/configs/\<boardname\>.h
+ - arch/\<architecture\>/configs/\<boardname\>_defconfig
+
+@subsection board_makefile arch/\<architecture\>/boards/\<boardname\>Makefile
+
+@verbatim
+	obj-y += all files that builds the BSP (Assembler and/or C files)
+@endverbatim
+
+@subsection board_basefile arch/\<architecture\>/boards/\<boardname\>\<boardname\>.c
+
+TBD
+
+@subsection board_doxygen arch/\<architecture\>/boards/\<boardname\>/\<boardname\>.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 <boardname> <Manufacturer> <Board's Name>
+
+This board uses an <architecture> 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 ("<boardname>" in the
+template above) into Documentation/boards.dox as:
+
+@verbatim
+ ...
+ @subpage <boardname>
+ ...
+@endverbatim
+
+at the right architecture.
+
+@note Consider to use an unique page lable.
+
+@subsection board_lscript arch/\<architecture\>/boards/\<boardname\>/barebox.lds.S
+
+If your board needs a special binary @a barebox 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 += <board_linker_script>
+@endverbatim
+
+in your local \b Makefile to the list of files, forwarded to the last linking step.
+
+@section board_defconfig arch/\<architecture\>/configs/\<boardname\>_defconfig
+
+TBD
+
+@section board_mod_files These files needs to be modified:
+
+ - modify Documentation/board.dox
+ - modify arch/\<architecture\>/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/\<architecture\>/Makefile:
+  - add board-$(MACH_*) = \<your board_dir\>
+
+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/Documentation/manual_org.dox b/Documentation/manual_org.dox
index 6f3b157876..17238f0847 100644
--- a/Documentation/manual_org.dox
+++ b/Documentation/manual_org.dox
@@ -10,7 +10,7 @@ than listed here. But these files are the main control files:
    - Documentation/users_manual.dox
     - Documentation/commands.dox
    - Documentation/developers_manual.dox
-    - board/board.dox
+    - Documentation/board.dox
     - arch/architecture.dox
      - arch/arm/mach-arm.dox
      - arch/blackfin/mach-bf.dox
@@ -24,4 +24,4 @@ their pages should be listed in this file.
 
 New boards should forward their content to Documentation/boards.dox, so
 their pages should be listed in this file.
-*/
\ No newline at end of file
+*/