[people/ms/u-boot.git] / board / Barix / ipam390 / README.ipam390

Summary
=======
The README is for the boot procedure on the ipam390 board

In the context of U-Boot, the board is booted in three stages. The initial
bootloader which executes upon reset is the ROM Boot Loader (RBL) and sits
in the internal ROM. The RBL initializes the internal memory and then
depending on the exact board and pin configurations will initialize another
controller (such as NAND) to continue the boot process by loading
the secondary program loader (SPL). The SPL will initialize the system
further (some clocks, SDRAM). As on this board is used the falcon boot
mode, now 2 ways are possible depending on the GPIO 7_14 input pin,
connected with the "soft reset switch"

If this pin is logical 1 (high level):
spl code starts the kernel image without delay

If this pin is logical 0 (low level):
spl code starts the u-boot image

AIS is an image format defined by TI for the images that are to be loaded
to memory by the RBL. The image is divided into a series of sections and
the image's entry point is specified. Each section comes with meta data
like the target address the section is to be copied to and the size of the
section, which is used by the RBL to load the image. At the end of the
image the RBL jumps to the image entry point.  The AIS format allows for
other things such as programming the clocks and SDRAM if the header is
programmed for it.  We do not take advantage of this and instead use SPL as
it allows for additional flexibility (run-time detect of board revision,
loading the next image from a different media, etc).

Compilation
===========
run "tools/buildman/buildman -k ipam390" in the u-boot source tree.
Once this build completes you will have a ../current/ipam390/u-boot.ais file
that needs to be written to the nand flash.

Flashing the images to NAND
==========================
The AIS image can be written to NAND flash using the following commands.
Assuming that the network is configured and enabled and the u-boot.ais file
is tftp'able.

U-Boot > print upd_uboot
upd_uboot=tftp c0000000 ${u-boot};nand erase.part u-boot;nand write c0000000 20000 ${filesize}
U-Boot >
U-Boot > run upd_uboot
Using DaVinci-EMAC device
TFTP from server 192.168.1.1; our IP address is 192.168.20.71
Filename '/tftpboot/ipam390/u-boot.ais'.
Load address: 0xc0000000
Loading: ##################################
	 1.5 MiB/s
done
Bytes transferred = 493716 (78894 hex)

NAND erase.part: device 0 offset 0x20000, size 0x160000
Erasing at 0x160000 -- 100% complete.
OK

NAND write: device 0 offset 0x20000, size 0x78894
 493716 bytes written: OK
U-Boot >

Recovery
========

In the case of a "bricked" board, you need to use the TI tools found
here[1] to create an uboot-uart-ais.bin file

- cd to the u-boot source tree

- compile the u-boot for the ipam390 board:
$ tools/buildman/buildman -k ipam390

  -> Now we shall have u-boot.bin

- Create u-boot-uart-ais.bin
$ mono HexAIS_OMAP-L138.exe -entrypoint 0xC1080000 -ini ipam390-ais-uart.cfg \
	-o ../current/ipam390/uboot-uart-ais.bin ./u-boot.bin@0xC1080000;

Note: The ipam390-ais-uart.cfg is found in the board directory
for the ipam390 board, u-boot:/board/Barix/ipam390/ipam390-ais-uart.cfg

- We can now run bootloader on IPAM390 via UART using the command below:

$ mono ./slh_OMAP-L138.exe -waitForDevice -v -p /dev/tty.UC-232AC uboot-uart-ais.bin
NOTE: Do not cancel the command execution! The command takes 20+ seconds
to upload u-boot over serial and run it!
Outcome:
Waiting for the OMAP-L138...
(AIS Parse): Read magic word 0x41504954.
(AIS Parse): Waiting for BOOTME... (power on or reset target now)
(AIS Parse): BOOTME received!
(AIS Parse): Performing Start-Word Sync...
(AIS Parse): Performing Ping Opcode Sync...
(AIS Parse): Processing command 0: 0x5853590D.
(AIS Parse): Performing Opcode Sync...
(AIS Parse): Executing function...
(AIS Parse): Processing command 1: 0x5853590D.
(AIS Parse): Performing Opcode Sync...
(AIS Parse): Executing function...
(AIS Parse): Processing command 2: 0x5853590D.
(AIS Parse): Performing Opcode Sync...
(AIS Parse): Executing function...
(AIS Parse): Processing command 3: 0x5853590D.
(AIS Parse): Performing Opcode Sync...
(AIS Parse): Executing function...
(AIS Parse): Processing command 4: 0x5853590D.
(AIS Parse): Performing Opcode Sync...
(AIS Parse): Executing function...
(AIS Parse): Processing command 5: 0x58535901.
(AIS Parse): Performing Opcode Sync...
(AIS Parse): Loading section...
(AIS Parse): Loaded 326516-Byte section to address 0xC1080000.
(AIS Parse): Processing command 6: 0x58535906.
(AIS Parse): Performing Opcode Sync...
(AIS Parse): Performing jump and close...
(AIS Parse): AIS complete. Jump to address 0xC1080000.
(AIS Parse): Waiting for DONE...
(AIS Parse): Boot completed successfully.

Operation completed successfully.

Falcon Bootmode (boot linux without booting U-Boot)
===================================================

The Falcon Mode extends this way allowing to start the Linux kernel directly
from SPL. A new command is added to U-Boot to prepare the parameters that SPL
must pass to the kernel, using ATAGS or Device Tree.

In normal mode, these parameters are generated each time before
loading the kernel, passing to Linux the address in memory where
the parameters can be read.
With Falcon Mode, this snapshot can be saved into persistent storage and SPL is
informed to load it before running the kernel.

To boot the kernel, these steps under a Falcon-aware U-Boot are required:

1. Boot the board into U-Boot.
Use the "spl export" command to generate the kernel parameters area or the DT.
U-Boot runs as when it boots the kernel, but stops before passing the control
to the kernel.

Here the command sequence for the ipam390 board:
- load the linux kernel image into ram:

U-Boot > nand read c0100000 2 200000 400000

NAND read: device 0 offset 0x200000, size 0x400000
 4194304 bytes read: OK

- generate the bootparms image:

U-Boot > spl export atags c0100000
## Booting kernel from Legacy Image at c0100000 ...
   Image Name:   Linux-3.5.1
   Image Type:   ARM Linux Kernel Image (uncompressed)
   Data Size:    2504280 Bytes = 2.4 MiB
   Load Address: c0008000
   Entry Point:  c0008000
   Verifying Checksum ... OK
   Loading Kernel Image ... OK
subcommand not supported
subcommand not supported
Argument image is now in RAM at: 0xc0000100

- copy the bootparms image into nand:

U-Boot > mtdparts

device nand0 <davinci_nand.0>, # parts = 6
 #: name		size		offset		mask_flags
 0: u-boot-env          0x00020000	0x00000000	0
 1: u-boot              0x00160000	0x00020000	0
 2: bootparms           0x00020000	0x00180000	0
 3: factory-info        0x00060000	0x001a0000	0
 4: kernel              0x00400000	0x00200000	0
 5: rootfs              0x07a00000	0x00600000	0

active partition: nand0,0 - (u-boot-env) 0x00020000 @ 0x00000000

defaults:
mtdids  : nand0=davinci_nand.0
mtdparts: mtdparts=davinci_nand.0:128k(u-boot-env),1408k(u-boot),128k(bootparms),384k(factory-info),4M(kernel),-(rootfs)
U-Boot > nand erase.part bootparms

NAND erase.part: device 0 offset 0x180000, size 0x20000
Erasing at 0x180000 -- 100% complete.
OK
U-Boot > nand write c0000100 180000 20000

NAND write: device 0 offset 0x180000, size 0x20000
 131072 bytes written: OK
U-Boot >

You can use also the predefined U-Boot Environment variable "setbootparms",
which will do all the above steps in one command:

U-Boot > print setbootparms
setbootparms=nand read c0100000 200000 400000;spl export atags c0100000;nand erase.part bootparms;nand write c0000100 180000 20000
U-Boot > run setbootparms

NAND read: device 0 offset 0x200000, size 0x400000
 4194304 bytes read: OK
## Booting kernel from Legacy Image at c0100000 ...
   Image Name:   Linux-3.5.1
   Image Type:   ARM Linux Kernel Image (uncompressed)
   Data Size:    2504280 Bytes = 2.4 MiB
   Load Address: c0008000
   Entry Point:  c0008000
   Verifying Checksum ... OK
   Loading Kernel Image ... OK
subcommand not supported
subcommand not supported
Argument image is now in RAM at: 0xc0000100

NAND erase.part: device 0 offset 0x180000, size 0x20000
Erasing at 0x180000 -- 100% complete.
OK

NAND write: device 0 offset 0x180000, size 0x20000
 131072 bytes written: OK
U-Boot >

Links
=====
[1]
 http://sourceforge.net/projects/dvflashutils/files/OMAP-L138/
Commit	Line	Data
03efcb05 HS	1	Summary
	2	=======
	3	The README is for the boot procedure on the ipam390 board
	4
	5	In the context of U-Boot, the board is booted in three stages. The initial
	6	bootloader which executes upon reset is the ROM Boot Loader (RBL) and sits
	7	in the internal ROM. The RBL initializes the internal memory and then
	8	depending on the exact board and pin configurations will initialize another
	9	controller (such as NAND) to continue the boot process by loading
	10	the secondary program loader (SPL). The SPL will initialize the system
	11	further (some clocks, SDRAM). As on this board is used the falcon boot
	12	mode, now 2 ways are possible depending on the GPIO 7_14 input pin,
	13	connected with the "soft reset switch"
	14
	15	If this pin is logical 1 (high level):
	16	spl code starts the kernel image without delay
	17
	18	If this pin is logical 0 (low level):
	19	spl code starts the u-boot image
	20
	21	AIS is an image format defined by TI for the images that are to be loaded
	22	to memory by the RBL. The image is divided into a series of sections and
	23	the image's entry point is specified. Each section comes with meta data
	24	like the target address the section is to be copied to and the size of the
	25	section, which is used by the RBL to load the image. At the end of the
	26	image the RBL jumps to the image entry point. The AIS format allows for
	27	other things such as programming the clocks and SDRAM if the header is
	28	programmed for it. We do not take advantage of this and instead use SPL as
	29	it allows for additional flexibility (run-time detect of board revision,
	30	loading the next image from a different media, etc).
	31
	32	Compilation
	33	===========
6de80f21 SG	34	run "tools/buildman/buildman -k ipam390" in the u-boot source tree.
	35	Once this build completes you will have a ../current/ipam390/u-boot.ais file
	36	that needs to be written to the nand flash.
03efcb05 HS	37
	38	Flashing the images to NAND
	39	==========================
	40	The AIS image can be written to NAND flash using the following commands.
	41	Assuming that the network is configured and enabled and the u-boot.ais file
	42	is tftp'able.
	43
	44	U-Boot > print upd_uboot
	45	upd_uboot=tftp c0000000 ${u-boot};nand erase.part u-boot;nand write c0000000 20000 ${filesize}
	46	U-Boot >
	47	U-Boot > run upd_uboot
	48	Using DaVinci-EMAC device
	49	TFTP from server 192.168.1.1; our IP address is 192.168.20.71
	50	Filename '/tftpboot/ipam390/u-boot.ais'.
	51	Load address: 0xc0000000
	52	Loading: ##################################
93e14596	53	1.5 MiB/s
03efcb05 HS	54	done
	55	Bytes transferred = 493716 (78894 hex)
	56
	57	NAND erase.part: device 0 offset 0x20000, size 0x160000
	58	Erasing at 0x160000 -- 100% complete.
	59	OK
	60
	61	NAND write: device 0 offset 0x20000, size 0x78894
	62	493716 bytes written: OK
	63	U-Boot >
	64
	65	Recovery
	66	========
	67
	68	In the case of a "bricked" board, you need to use the TI tools found
	69	here[1] to create an uboot-uart-ais.bin file
	70
	71	- cd to the u-boot source tree
	72
	73	- compile the u-boot for the ipam390 board:
6de80f21	74	$ tools/buildman/buildman -k ipam390
03efcb05 HS	75
	76	-> Now we shall have u-boot.bin
	77
	78	- Create u-boot-uart-ais.bin
6de80f21 SG	79	$ mono HexAIS_OMAP-L138.exe -entrypoint 0xC1080000 -ini ipam390-ais-uart.cfg \
6de80f21 SG	80	-o ../current/ipam390/uboot-uart-ais.bin ./u-boot.bin@0xC1080000;
03efcb05 HS	81
	82	Note: The ipam390-ais-uart.cfg is found in the board directory
	83	for the ipam390 board, u-boot:/board/Barix/ipam390/ipam390-ais-uart.cfg
	84
	85	- We can now run bootloader on IPAM390 via UART using the command below:
	86
	87	$ mono ./slh_OMAP-L138.exe -waitForDevice -v -p /dev/tty.UC-232AC uboot-uart-ais.bin
	88	NOTE: Do not cancel the command execution! The command takes 20+ seconds
	89	to upload u-boot over serial and run it!
	90	Outcome:
	91	Waiting for the OMAP-L138...
	92	(AIS Parse): Read magic word 0x41504954.
	93	(AIS Parse): Waiting for BOOTME... (power on or reset target now)
	94	(AIS Parse): BOOTME received!
	95	(AIS Parse): Performing Start-Word Sync...
	96	(AIS Parse): Performing Ping Opcode Sync...
	97	(AIS Parse): Processing command 0: 0x5853590D.
	98	(AIS Parse): Performing Opcode Sync...
	99	(AIS Parse): Executing function...
	100	(AIS Parse): Processing command 1: 0x5853590D.
	101	(AIS Parse): Performing Opcode Sync...
	102	(AIS Parse): Executing function...
	103	(AIS Parse): Processing command 2: 0x5853590D.
	104	(AIS Parse): Performing Opcode Sync...
	105	(AIS Parse): Executing function...
	106	(AIS Parse): Processing command 3: 0x5853590D.
	107	(AIS Parse): Performing Opcode Sync...
	108	(AIS Parse): Executing function...
	109	(AIS Parse): Processing command 4: 0x5853590D.
	110	(AIS Parse): Performing Opcode Sync...
	111	(AIS Parse): Executing function...
	112	(AIS Parse): Processing command 5: 0x58535901.
	113	(AIS Parse): Performing Opcode Sync...
	114	(AIS Parse): Loading section...
	115	(AIS Parse): Loaded 326516-Byte section to address 0xC1080000.
	116	(AIS Parse): Processing command 6: 0x58535906.
	117	(AIS Parse): Performing Opcode Sync...
	118	(AIS Parse): Performing jump and close...
	119	(AIS Parse): AIS complete. Jump to address 0xC1080000.
	120	(AIS Parse): Waiting for DONE...
	121	(AIS Parse): Boot completed successfully.
	122
	123	Operation completed successfully.
	124
	125	Falcon Bootmode (boot linux without booting U-Boot)
	126	===================================================
	127
	128	The Falcon Mode extends this way allowing to start the Linux kernel directly
	129	from SPL. A new command is added to U-Boot to prepare the parameters that SPL
	130	must pass to the kernel, using ATAGS or Device Tree.
	131
	132	In normal mode, these parameters are generated each time before
	133	loading the kernel, passing to Linux the address in memory where
	134	the parameters can be read.
	135	With Falcon Mode, this snapshot can be saved into persistent storage and SPL is
	136	informed to load it before running the kernel.
	137
	138	To boot the kernel, these steps under a Falcon-aware U-Boot are required:
	139
	140	1. Boot the board into U-Boot.
	141	Use the "spl export" command to generate the kernel parameters area or the DT.
	142	U-Boot runs as when it boots the kernel, but stops before passing the control
	143	to the kernel.
	144
145	Here the command sequence for the ipam390 board:
146	- load the linux kernel image into ram:
147
148	U-Boot > nand read c0100000 2 200000 400000
149
150	NAND read: device 0 offset 0x200000, size 0x400000
151	4194304 bytes read: OK
152
153	- generate the bootparms image:
154
155	U-Boot > spl export atags c0100000
156	## Booting kernel from Legacy Image at c0100000 ...
157	Image Name: Linux-3.5.1
158	Image Type: ARM Linux Kernel Image (uncompressed)
159	Data Size: 2504280 Bytes = 2.4 MiB
160	Load Address: c0008000
161	Entry Point: c0008000
162	Verifying Checksum ... OK
163	Loading Kernel Image ... OK
164	subcommand not supported
165	subcommand not supported
166	Argument image is now in RAM at: 0xc0000100
167
168	- copy the bootparms image into nand:
169
170	U-Boot > mtdparts
171
172	device nand0 <davinci_nand.0>, # parts = 6
173	#: name size offset mask_flags
174	0: u-boot-env 0x00020000 0x00000000 0
175	1: u-boot 0x00160000 0x00020000 0
176	2: bootparms 0x00020000 0x00180000 0
177	3: factory-info 0x00060000 0x001a0000 0
178	4: kernel 0x00400000 0x00200000 0
179	5: rootfs 0x07a00000 0x00600000 0
180
181	active partition: nand0,0 - (u-boot-env) 0x00020000 @ 0x00000000
182
183	defaults:
184	mtdids : nand0=davinci_nand.0
185	mtdparts: mtdparts=davinci_nand.0:128k(u-boot-env),1408k(u-boot),128k(bootparms),384k(factory-info),4M(kernel),-(rootfs)
186	U-Boot > nand erase.part bootparms
187
188	NAND erase.part: device 0 offset 0x180000, size 0x20000
189	Erasing at 0x180000 -- 100% complete.
190	OK
191	U-Boot > nand write c0000100 180000 20000
192
193	NAND write: device 0 offset 0x180000, size 0x20000
194	131072 bytes written: OK
195	U-Boot >
196
197	You can use also the predefined U-Boot Environment variable "setbootparms",
198	which will do all the above steps in one command:
199
200	U-Boot > print setbootparms
201	setbootparms=nand read c0100000 200000 400000;spl export atags c0100000;nand erase.part bootparms;nand write c0000100 180000 20000
202	U-Boot > run setbootparms
203
204	NAND read: device 0 offset 0x200000, size 0x400000
205	4194304 bytes read: OK
206	## Booting kernel from Legacy Image at c0100000 ...
207	Image Name: Linux-3.5.1
208	Image Type: ARM Linux Kernel Image (uncompressed)
209	Data Size: 2504280 Bytes = 2.4 MiB
210	Load Address: c0008000
211	Entry Point: c0008000
212	Verifying Checksum ... OK
213	Loading Kernel Image ... OK
214	subcommand not supported
215	subcommand not supported
216	Argument image is now in RAM at: 0xc0000100
217
218	NAND erase.part: device 0 offset 0x180000, size 0x20000
219	Erasing at 0x180000 -- 100% complete.
220	OK
221
222	NAND write: device 0 offset 0x180000, size 0x20000
223	131072 bytes written: OK
224	U-Boot >
225
226	Links
227	=====
228	[1]
229	http://sourceforge.net/projects/dvflashutils/files/OMAP-L138/