[PATCH 0/3] add at91 documentation

[PATCH 0/3] add at91 documentation

[Sam Ravnborg]

While working on at91sam9263-ek I started to take a few notes.
And missing a place to put these notes I ended up adding
files for the most relevant at91 based boards.
Following the barebox principle I added one file per board,
even though most files just list the defconfig file.

The idea is the it is now easier to add some documentation
for an existing baord or a new board.
I also added my ramling for at91sam9263 - so it is saved
somewhere and maybe useful for someone else in the future.

Sphinx did not report any warnings - and it looked as expected.

	Sam

Signed-off-by: Sam Ravnborg <sam@ravnborg.org>

Sam Ravnborg (3):
      doc: add at91 documentation
      doc: add additional at91 boards
      doc: at91sam9263-ek: add notes

 Documentation/boards/at91.rst                      |  51 ++++++++
 .../boards/at91/microchip-at91rm9200-ek.rst        |   8 ++
 .../boards/at91/microchip-at91sam9260-ek.rst       |   8 ++
 .../boards/at91/microchip-at91sam9261-ek.rst       |  18 +++
 .../boards/at91/microchip-at91sam9263-ek.rst       | 132 +++++++++++++++++++++
 .../boards/at91/microchip-at91sam9g10-ek.rst       |   8 ++
 .../boards/at91/microchip-at91sam9g20-ek.rst       |   8 ++
 .../boards/at91/microchip-at91sam9m10g45-ek.rst    |   8 ++
 .../boards/at91/microchip-at91sam9n12-ek.rst       |   8 ++
 .../boards/at91/microchip-at91sam9x5-ek.rst        |  10 ++
 .../boards/at91/microchip-ksz9477-evb.rst          |  11 ++
 .../boards/at91/microchip-sama5d3-xplained.rst     |   8 ++
 .../boards/at91/microchip-sama5d3x-ek.rst          |   8 ++
 .../boards/at91/microchip-sama5d4-xplained.rst     |   8 ++
 Documentation/boards/at91/somfy-animeo-ip.rst      |   4 +
 Documentation/boards/at91/telit-evk-pro3.rst       |   9 ++
 16 files changed, 307 insertions(+)


_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox

[PATCH v1 1/3] doc: add at91 documentation

[Sam Ravnborg]

Add at91 specific documentation.

Add files for the Atmel evaluations kits.
This is mostly placeholders with some trivial information,
but we now have files to add more information.

Signed-off-by: Sam Ravnborg <sam@ravnborg.org>
---
 Documentation/boards/at91.rst                      | 51 ++++++++++++++++++++++
 .../boards/at91/microchip-at91rm9200-ek.rst        |  8 ++++
 .../boards/at91/microchip-at91sam9260-ek.rst       |  8 ++++
 .../boards/at91/microchip-at91sam9261-ek.rst       | 18 ++++++++
 .../boards/at91/microchip-at91sam9263-ek.rst       | 10 +++++
 .../boards/at91/microchip-at91sam9g10-ek.rst       |  8 ++++
 .../boards/at91/microchip-at91sam9g20-ek.rst       |  8 ++++
 .../boards/at91/microchip-at91sam9m10g45-ek.rst    |  8 ++++
 .../boards/at91/microchip-at91sam9n12-ek.rst       |  8 ++++
 .../boards/at91/microchip-at91sam9x5-ek.rst        | 10 +++++
 10 files changed, 137 insertions(+)
 create mode 100644 Documentation/boards/at91.rst
 create mode 100644 Documentation/boards/at91/microchip-at91rm9200-ek.rst
 create mode 100644 Documentation/boards/at91/microchip-at91sam9260-ek.rst
 create mode 100644 Documentation/boards/at91/microchip-at91sam9261-ek.rst
 create mode 100644 Documentation/boards/at91/microchip-at91sam9263-ek.rst
 create mode 100644 Documentation/boards/at91/microchip-at91sam9g10-ek.rst
 create mode 100644 Documentation/boards/at91/microchip-at91sam9g20-ek.rst
 create mode 100644 Documentation/boards/at91/microchip-at91sam9m10g45-ek.rst
 create mode 100644 Documentation/boards/at91/microchip-at91sam9n12-ek.rst
 create mode 100644 Documentation/boards/at91/microchip-at91sam9x5-ek.rst

diff --git a/Documentation/boards/at91.rst b/Documentation/boards/at91.rst
new file mode 100644
index 000000000..f25cb01bb
--- /dev/null
+++ b/Documentation/boards/at91.rst
@@ -0,0 +1,51 @@
+Microchip (Atmel) AT91
+======================
+
+The Microchip (former Atmel) AT91 architecure has very good support within
+barebox.
+Most boards today have their description in their board files, but
+boards are slowly migrating to use DT.
+Likewise most boards are not yet migrated to multi image support, but
+this is also ongoing.
+
+The boot process of the AT91 CPU's is a two step process.
+The first step is named the bootstrap and at91bootstrap
+is often used (https://github.com/linux4sam/at91bootstrap).
+barebox supports bootstrapping some at91 boards as documented
+in the following.
+
+The bootstrap program are loaded by a boot program and can be loaded
+from DataFlash, NAND Flash, SD Card or via USB.
+The bootstrap program do the low-level configuration of the
+processor and then load and execute barebox.
+
+AT91 boards
+-----------
+The majority of the supported boards have a short entry here.
+For each board defconfig file(s) are noted but barebox may include additional
+defconfig files and may also include boards not included in the following.
+
+.. toctree::
+  :glob:
+  :maxdepth: 1
+
+  at91/*
+
+TODO
+----
+This is a list of AT91 specific TODO items, listed in no particular order.
+
+* fix prototype for barebox_arm_reset_vector. Introduce the prototype:
+
+.. code-block:: c
+
+  void __naked __bare_init barebox_arm_reset_vector(uint32_t r0, uint32_t r1, uint32_t r2)
+
+
+This will unify the prototype for the reset vector for multi image and standalone images
+
+* Update remaining boards to DT
+* Update remaing boards to support multi image boot
+* Get bootstrap working in combination with multi image
+* Introduce defaultenv2 for all boards
+* Add pwm driver (required to support backlight)
diff --git a/Documentation/boards/at91/microchip-at91rm9200-ek.rst b/Documentation/boards/at91/microchip-at91rm9200-ek.rst
new file mode 100644
index 000000000..2eecf4827
--- /dev/null
+++ b/Documentation/boards/at91/microchip-at91rm9200-ek.rst
@@ -0,0 +1,8 @@
+Atmel AT91RM9200-EK Evaluation Kit
+==================================
+
+Building barebox:
+
+.. code-block:: sh
+
+  make ARCH=arm at91rm9200ek_defconfig
diff --git a/Documentation/boards/at91/microchip-at91sam9260-ek.rst b/Documentation/boards/at91/microchip-at91sam9260-ek.rst
new file mode 100644
index 000000000..c54c26251
--- /dev/null
+++ b/Documentation/boards/at91/microchip-at91sam9260-ek.rst
@@ -0,0 +1,8 @@
+Atmel AT91SAM9260-EK Evaluation Kit
+===================================
+
+Building barebox:
+
+.. code-block:: sh
+
+  make ARCH=arm at91sam9260ek_defconfig
diff --git a/Documentation/boards/at91/microchip-at91sam9261-ek.rst b/Documentation/boards/at91/microchip-at91sam9261-ek.rst
new file mode 100644
index 000000000..df8828295
--- /dev/null
+++ b/Documentation/boards/at91/microchip-at91sam9261-ek.rst
@@ -0,0 +1,18 @@
+Atmel AT91SAM9261-EK Evaluation Kit
+===================================
+
+For AT91SAM9261-EK there are three defconfigs.
+
+The two defconfigs listed below are almost identical.
+The one named _first_stage_ can be used for FLASH as it allows the first part to be loaded to SRAM.
+
+.. code-block:: sh
+
+  make ARCH=arm at91sam9261ek_defconfig
+  make ARCH=arm at91sam9261ek_first_stage_defconfig
+
+The following defconfig can be used to build a bootstrap variant of barebox
+
+.. code-block:: sh
+
+  make ARCH=arm at91sam9261ek_bootstrap_defconfig
diff --git a/Documentation/boards/at91/microchip-at91sam9263-ek.rst b/Documentation/boards/at91/microchip-at91sam9263-ek.rst
new file mode 100644
index 000000000..74ddb3cdb
--- /dev/null
+++ b/Documentation/boards/at91/microchip-at91sam9263-ek.rst
@@ -0,0 +1,10 @@
+Atmel AT91SAM9263-EK Evaluation Kit
+===================================
+
+The AT91SAM9263-EK evaluation kit supports Device Tree and Multi Images.
+
+Building barebox:
+
+.. code-block:: sh
+
+  make ARCH=arm at91sam9263ek_defconfig
diff --git a/Documentation/boards/at91/microchip-at91sam9g10-ek.rst b/Documentation/boards/at91/microchip-at91sam9g10-ek.rst
new file mode 100644
index 000000000..f8f7d561a
--- /dev/null
+++ b/Documentation/boards/at91/microchip-at91sam9g10-ek.rst
@@ -0,0 +1,8 @@
+Atmel AT91SAM9G10-EK Evaluation Kit
+===================================
+
+Building barebox:
+
+.. code-block:: sh
+
+  make ARCH=arm at91sam9g10ek_defconfig
diff --git a/Documentation/boards/at91/microchip-at91sam9g20-ek.rst b/Documentation/boards/at91/microchip-at91sam9g20-ek.rst
new file mode 100644
index 000000000..b641e0a38
--- /dev/null
+++ b/Documentation/boards/at91/microchip-at91sam9g20-ek.rst
@@ -0,0 +1,8 @@
+Atmel AT91SAM9G20-EK Evaluation Kit
+===================================
+
+Building barebox:
+
+.. code-block:: sh
+
+  make ARCH=arm at91sam9g20ek_defconfig
diff --git a/Documentation/boards/at91/microchip-at91sam9m10g45-ek.rst b/Documentation/boards/at91/microchip-at91sam9m10g45-ek.rst
new file mode 100644
index 000000000..ac54ed7c5
--- /dev/null
+++ b/Documentation/boards/at91/microchip-at91sam9m10g45-ek.rst
@@ -0,0 +1,8 @@
+Atmel AT91SAM9M10G45-EK Evaluation Kit
+======================================
+
+Building barebox:
+
+.. code-block:: sh
+
+  make ARCH=arm at91sam9m10g45ek_defconfig
diff --git a/Documentation/boards/at91/microchip-at91sam9n12-ek.rst b/Documentation/boards/at91/microchip-at91sam9n12-ek.rst
new file mode 100644
index 000000000..8aeba53f1
--- /dev/null
+++ b/Documentation/boards/at91/microchip-at91sam9n12-ek.rst
@@ -0,0 +1,8 @@
+Atmel AT91SAM9N12-EK Evaluation Kit
+===================================
+
+Building barebox:
+
+.. code-block:: sh
+
+  make ARCH=arm at91sam9n12ek_defconfig
diff --git a/Documentation/boards/at91/microchip-at91sam9x5-ek.rst b/Documentation/boards/at91/microchip-at91sam9x5-ek.rst
new file mode 100644
index 000000000..4c7b0cf3d
--- /dev/null
+++ b/Documentation/boards/at91/microchip-at91sam9x5-ek.rst
@@ -0,0 +1,10 @@
+Atmel AT91SAM9X5-EK Evaluation Kit
+===================================
+
+The AT91SAM9X5-EK kit supports Device Tree and Multi Images.
+
+Building barebox:
+
+.. code-block:: sh
+
+  make ARCH=arm at91sam9x5ek_defconfig
-- 
2.12.0


_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox

[PATCH v1 2/3] doc: add additional at91 boards

[Sam Ravnborg]

Simple files that makes it simple to add further documentation later

Signed-off-by: Sam Ravnborg <sam@ravnborg.org>
---
 Documentation/boards/at91/microchip-ksz9477-evb.rst      | 11 +++++++++++
 Documentation/boards/at91/microchip-sama5d3-xplained.rst |  8 ++++++++
 Documentation/boards/at91/microchip-sama5d3x-ek.rst      |  8 ++++++++
 Documentation/boards/at91/microchip-sama5d4-xplained.rst |  8 ++++++++
 Documentation/boards/at91/somfy-animeo-ip.rst            |  4 ++++
 Documentation/boards/at91/telit-evk-pro3.rst             |  9 +++++++++
 6 files changed, 48 insertions(+)
 create mode 100644 Documentation/boards/at91/microchip-ksz9477-evb.rst
 create mode 100644 Documentation/boards/at91/microchip-sama5d3-xplained.rst
 create mode 100644 Documentation/boards/at91/microchip-sama5d3x-ek.rst
 create mode 100644 Documentation/boards/at91/microchip-sama5d4-xplained.rst
 create mode 100644 Documentation/boards/at91/somfy-animeo-ip.rst
 create mode 100644 Documentation/boards/at91/telit-evk-pro3.rst

diff --git a/Documentation/boards/at91/microchip-ksz9477-evb.rst b/Documentation/boards/at91/microchip-ksz9477-evb.rst
new file mode 100644
index 000000000..4c4c4aecb
--- /dev/null
+++ b/Documentation/boards/at91/microchip-ksz9477-evb.rst
@@ -0,0 +1,11 @@
+Microchip KSZ 9477 Evaluation board
+===================================
+
+This is an evaluation board for a switch that uses the at91sam9x5 CPU.
+The board uses Device Tree and supports multi image.
+
+Building barebox:
+
+.. code-block:: sh
+
+  make ARCH=arm microchip_ksz9477_evb_defconfig
diff --git a/Documentation/boards/at91/microchip-sama5d3-xplained.rst b/Documentation/boards/at91/microchip-sama5d3-xplained.rst
new file mode 100644
index 000000000..e96111af7
--- /dev/null
+++ b/Documentation/boards/at91/microchip-sama5d3-xplained.rst
@@ -0,0 +1,8 @@
+Atmel SAMA5D3_XPLAINED Evaluation Kit
+=====================================
+
+Building barebox:
+
+.. code-block:: sh
+
+  make ARCH=arm sama5d3_xplained_defconfig
diff --git a/Documentation/boards/at91/microchip-sama5d3x-ek.rst b/Documentation/boards/at91/microchip-sama5d3x-ek.rst
new file mode 100644
index 000000000..10bf2e611
--- /dev/null
+++ b/Documentation/boards/at91/microchip-sama5d3x-ek.rst
@@ -0,0 +1,8 @@
+Atmel SAMA5D3X Evaluation Kit
+=============================
+
+Building barebox:
+
+.. code-block:: sh
+
+  make ARCH=arm sama5d3xek_defconfig
diff --git a/Documentation/boards/at91/microchip-sama5d4-xplained.rst b/Documentation/boards/at91/microchip-sama5d4-xplained.rst
new file mode 100644
index 000000000..d8615e4af
--- /dev/null
+++ b/Documentation/boards/at91/microchip-sama5d4-xplained.rst
@@ -0,0 +1,8 @@
+Atmel SAMA5D4 XPLAINED ULTRA Evaluation Kit
+===========================================
+
+Building barebox:
+
+.. code-block:: sh
+
+  make ARCH=arm sama5d4_xplained_defconfig
diff --git a/Documentation/boards/at91/somfy-animeo-ip.rst b/Documentation/boards/at91/somfy-animeo-ip.rst
new file mode 100644
index 000000000..a87179469
--- /dev/null
+++ b/Documentation/boards/at91/somfy-animeo-ip.rst
@@ -0,0 +1,4 @@
+Somfy Animeo IP
+===============
+
+No defconfig provided to build barebox
diff --git a/Documentation/boards/at91/telit-evk-pro3.rst b/Documentation/boards/at91/telit-evk-pro3.rst
new file mode 100644
index 000000000..ea0b070fd
--- /dev/null
+++ b/Documentation/boards/at91/telit-evk-pro3.rst
@@ -0,0 +1,9 @@
+Atmel Telit EVK-PRO3
+====================
+
+Telit EVK-PRO3 with GE863-PRO3
+Building barebox:
+
+.. code-block:: sh
+
+  make ARCH=arm telit_evk_pro3_defconfig
-- 
2.12.0


_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox

[PATCH v1 3/3] doc: at91sam9263-ek: add notes

[Sam Ravnborg]

Add notes from working on bootstrap support

Signed-off-by: Sam Ravnborg <sam@ravnborg.org>
---
 .../boards/at91/microchip-at91sam9263-ek.rst       | 122 +++++++++++++++++++++
 1 file changed, 122 insertions(+)

diff --git a/Documentation/boards/at91/microchip-at91sam9263-ek.rst b/Documentation/boards/at91/microchip-at91sam9263-ek.rst
index 74ddb3cdb..8022cdd67 100644
--- a/Documentation/boards/at91/microchip-at91sam9263-ek.rst
+++ b/Documentation/boards/at91/microchip-at91sam9263-ek.rst
@@ -8,3 +8,125 @@ Building barebox:
 .. code-block:: sh
 
   make ARCH=arm at91sam9263ek_defconfig
+
+Notes while working on at91sam9263ek bootstrap support
+
+The at91sam9263 have support for a boot program,
+like the other members in the Atmel at91 series.
+
+The boot program (ROMBOOT) will try to load the
+boot program from DataFlash, SD Card, NAND Flash and USB
+
+SD Card is the first to try.
+It looks for a file named BOOT.BIN in the first
+partition in a FAT16/32 filesystem.
+
+To generate the SD Card image I used genimage:
+(https://github.com/pengutronix/genimage)
+Onle 2 GB SD card works, 4 GB did not work. ROMBOOT do not
+support high capacity SD cards.
+
+Configuration file:
+
+.. code-block:: none
+
+  image boot.vfat {
+	name = "boot"
+	vfat {
+		/*
+		 * RomBOOT in the at91sam9263 does not recognize
+		 * the default FAT partition created by mkdosfs.
+		 * -n BOOT - Set volume label to "BOOT"
+		 * -F 16   - Force the partition to FAT 16
+		 * -D 0    - Set drive number to 0
+		 * -R 1 -a - Reserve only one sector
+		 * The combination of "-D 0" AND "-R 1 -a"
+		 * is required with mkdosfs version 4.1
+		 */
+		extraargs = "-n BOOT -F 16 -D 0 -R 1 -a"
+		file BOOT.BIN    { image = "barebox.bin" } // barebox.bin from root of barebox dir 
+		file barebox.bin { image = "barebox-at91sam9263ek.img" }
+		file zImage      { image = "zImage" }
+	}
+
+	size = 16M
+  }
+
+  image rootfs.ext4 {
+	ext4 {
+		label = "root"
+	}
+	mountpoint = "/"
+	size = 1500M
+  }
+
+  image SD {
+	hdimage {}
+
+	partition boot {
+		partition-type = 0xc
+		bootable = "true"
+		image = "boot.vfat"
+	}
+
+	partition root {
+		image = "rootfs.ext4"
+		partition-type = 0x83
+	}
+
+  }
+
+ROMBOOT will load the BOOT.BIN file to internal SRAM that
+starts at 0x300000. Maximum size 0x12000 (72 KiB).
+When loaded ROMBOOT will remap like this:
+
+.. code-block:: none
+
+  0x00000000           0x00000000
+    Internal ROM   =>     Internal SRAM
+
+  0x00300000          0x00400000
+    Internal SRAM  =>     Internal ROM
+
+It is not documented but assumed that ROMBOOT uses the
+MMU to remap the addresses.
+There seems not to be a dedicated remapping feature that is used.
+
+Note: For DataFlash and NAND Flash the image is validated.
+The first 28 bytes must be valid load PC or PC relative addressing.
+Vector 0x6 must include the size of the image (in bytes).
+This validation is (according to datasheet) not done for SD Card boots.
+
+barebox related notes when trying to make it work with PBL enabled
+
+To let barebox detect the SD card early use: CONFIG_MCI_STARTUP=y
+
+When PBL (and MULTI_IMAGE) are enabled then barebox creates
+a binary with the following structure:
+
+.. code-block:: none
+
+  +----------------------+
+  | PBL (PreBootLoader)  |
+  +----------------------+
+  | piggy.o              |
+  |+--------------------+|
+  ||barebox second stage||
+  |+--------------------+|
+  +----------------------+
+
+The PBL contains code from the sections .text_head_entry*, .text_bare_init* and .text*
+
+``.text_head_entry*:``
+This is the reset vector and exception vectors. Must be the very first in the file
+
+``.text_bare_init*:``
+Everything in this section, and , is checked at link time.
+Size most be less than BAREBOX_MAX_BARE_INIT_SIZE / ARCH_BAREBOX_MAX_BARE_INIT_SIZE
+
+at91 specify the size of the two sections in exception vector 6 (see above),
+if CONFIG_AT91_LOAD_BAREBOX_SRAM is defined.
+I think this is because some at91 variants have only very limited SRAM size,
+and we copy only a minimal part to the SRAM. The remaining part is then
+executed in-place.
+For at91sam9263 we have a large SRAM so there is room for the full bootstrap binary.
-- 
2.12.0


_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox

Re: [PATCH 0/3] add at91 documentation

[Sascha Hauer]

On Sun, Jan 06, 2019 at 07:18:05PM +0100, Sam Ravnborg wrote:
> While working on at91sam9263-ek I started to take a few notes.
> And missing a place to put these notes I ended up adding
> files for the most relevant at91 based boards.
> Following the barebox principle I added one file per board,
> even though most files just list the defconfig file.
> 
> The idea is the it is now easier to add some documentation
> for an existing baord or a new board.
> I also added my ramling for at91sam9263 - so it is saved
> somewhere and maybe useful for someone else in the future.
> 
> Sphinx did not report any warnings - and it looked as expected.
> 
> 	Sam
> 
> Signed-off-by: Sam Ravnborg <sam@ravnborg.org>
> 
> Sam Ravnborg (3):
>       doc: add at91 documentation
>       doc: add additional at91 boards
>       doc: at91sam9263-ek: add notes

Applied, thanks

Sascha

> 
>  Documentation/boards/at91.rst                      |  51 ++++++++
>  .../boards/at91/microchip-at91rm9200-ek.rst        |   8 ++
>  .../boards/at91/microchip-at91sam9260-ek.rst       |   8 ++
>  .../boards/at91/microchip-at91sam9261-ek.rst       |  18 +++
>  .../boards/at91/microchip-at91sam9263-ek.rst       | 132 +++++++++++++++++++++
>  .../boards/at91/microchip-at91sam9g10-ek.rst       |   8 ++
>  .../boards/at91/microchip-at91sam9g20-ek.rst       |   8 ++
>  .../boards/at91/microchip-at91sam9m10g45-ek.rst    |   8 ++
>  .../boards/at91/microchip-at91sam9n12-ek.rst       |   8 ++
>  .../boards/at91/microchip-at91sam9x5-ek.rst        |  10 ++
>  .../boards/at91/microchip-ksz9477-evb.rst          |  11 ++
>  .../boards/at91/microchip-sama5d3-xplained.rst     |   8 ++
>  .../boards/at91/microchip-sama5d3x-ek.rst          |   8 ++
>  .../boards/at91/microchip-sama5d4-xplained.rst     |   8 ++
>  Documentation/boards/at91/somfy-animeo-ip.rst      |   4 +
>  Documentation/boards/at91/telit-evk-pro3.rst       |   9 ++
>  16 files changed, 307 insertions(+)
> 
> 
> _______________________________________________
> barebox mailing list
> barebox@lists.infradead.org
> http://lists.infradead.org/mailman/listinfo/barebox
> 

-- 
Pengutronix e.K.                           |                             |
Industrial Linux Solutions                 | http://www.pengutronix.de/  |
Peiner Str. 6-8, 31137 Hildesheim, Germany | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686           | Fax:   +49-5121-206917-5555 |

_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox