[PATCH 2/2] BBB: Add sd_setup.sh to create a bootable SD and README to document SD and UART booting

Wed Jul 8 21:28:42 UTC 2015

sd_setup.sh is a script that automates the process of setting up
an SD card with the appropriate uMon image to boot using either
"raw" or FAT mode.

README currently documents the steps required to boot the
Beaglebone Black from an SD card or via UART.
---
 ports/beagleboneblack/README      | 218 ++++++++++++++++++++++++++++++++++++++
 ports/beagleboneblack/sd_setup.sh |  62 +++++++++++
 2 files changed, 280 insertions(+)
 create mode 100644 ports/beagleboneblack/README
 create mode 100755 ports/beagleboneblack/sd_setup.sh

diff --git a/ports/beagleboneblack/README b/ports/beagleboneblack/README
new file mode 100644
index 0000000..6ce6217
--- /dev/null
+++ b/ports/beagleboneblack/README
@@ -0,0 +1,218 @@
+Getting Started with uMon for the Beaglebone Black
+
+=======================================================================
+Booting:
+=======================================================================
+
+-----------------------------------------------------------------------
+SD Card:
+-----------------------------------------------------------------------
+The Beaglebone Black can boot uMon from an SD card using two different
+boot modes.  The first boot mode is to boot using "raw" mode.  The
+second boot mode is to boot from a FAT primary partition marked as
+bootable.  The details and the steps required to set up the SD card
+for each of the boot modes are elaborated in the following two sections
+on SD card booting.  For more information on "raw" mode and FAT mode,
+please refer to the AM335s TRM Sections 26.1.7.5.5 "MMC/SD Read Sector
+Procedure in Raw Mode" and 26.1.7.5.6 "MMC/SD Read Sector Procedure
+in FAT Mode" respectively.
+
+In order to boot uMon from an SD card using FAT mode, a GP Header must
+be prepended to the uMon image.  In the case of booting uMon using
+"raw" mode, both a Configuration Header TOC Structure followed by a
+GP Header must be prepended to the uMon image.
+
+The GP Header is 8 bytes long where the first 4 bytes specify the size
+of the uMon image that will be transferred while the last 4 bytes
+specify both the destination address where the uMon image will be
+transferred to and the entry point.
+
+For information on the layout of the Configuration Header TOC Structure
+required for "raw" mode booting, please refer to the AM335x TRM
+Section 26.1.7.5.5.1 "Configuration Header".
+
+One thing worth mentioning is that the Beaglebone Black is connected to
+the SD card using MMC0 and as a result the size of the SD card must not
+be greater than 4GB.  This is indicated in the AM335x TRM Section
+26.1.7.5.2 "System Interconnection".
+
+In order to configure the Beaglebone Black to boot from an SD card,
+a uSD must be inserted and the boot switch held down while the board
+is powered up.  Once the board is powered on, the boot switch can
+be released.  If the attempt to boot from the uSD fails, the
+Beaglebone Black will fall back and attempt to boot using UART.
+As a result, this will provide a way to determine whether the boot
+from SD has succeeded or not.
+
+Before starting, it is recommended that the device that will be
+manipulated is verified to be the right device.  An approach to
+determine the right device name assigned to the SD card is by
+observing the output of
+
+	cat /proc/partitions
+
+before and after inserting the SD card.
+
+
+RAW MODE:
+
+In order to boot from an SD card using "raw" mode, the uMon image
+must be prepended with a Configuration Header TOC Structure and a
+GP Header.  The GP Header is placed right after the Configuration
+Header TOC Structure.
+
+When uMon is built, a uMon image containing the necessary headers
+is already created and is located under ./build_BEAGLEBONEBLACK.
+
+The next step is to setup the SD card.  Fortunately, the script
+./sd_setup.sh can be used to automate the process of setting up
+an SD card for "raw" mode booting.  To do so, invoke the script as
+
+	./sd_setup.sh RAW <device>
+
+<device> shown above and for the remainder of this document will
+refer to the SD card.
+
+The following information specify how to manually set up the SD
+card.
+
+With the proper headers prepended, the image is ready to be booted.
+In order for the Beaglebone Black/AM335x to boot the image, the
+image must be placed at one of the offsets
+0x00000/0x20000/0x40000/0x60000.
+
+As an example, to place the uMon image at the first offset
+
+	# Get the size of the uMon image to transfer into the SD card
+	export UMON_IMG_SIZE=`wc --bytes <uMon image> | cut -f 1 -d ' '`
+
+	# Transfer the uMon image at offset 0x00000
+	dd if=<uMon image> bs=1 count=$UMON_IMG_SIZE of=/dev/<device>
+
+where <uMon image> is the path to the uMon image prepended with a
+Configuration Header TOC Structure and a GP Header.
+
+
+FAT MODE:
+
+In FAT Mode, an "MLO" file is searched for in the root directory of
+a primary partition formatted as FAT12/FAT16 or FAT32 and marked
+bootable.  This "MLO" file must contain a GP Header followed by the
+uMon image.  When uMon is built, an "MLO" file is already created and
+is located in ./build_BEAGLEBONEBLACK.
+
+For convenience, preparing the SD card for FAT Mode booting has
+been automated through the use of the same aforementioned script,
+./sd_setup.sh.
+
+Invoking the script in order to create an SD card for FAT mode booting
+is as follows:
+
+	./sd_setup.sh FAT <device>
+
+The script simply sets up a primary partition on the SD card, marks
+it as bootable, formats it as FAT16 and then transfers the MLO file
+under ./build_BEAGLEBONEBLACK to the root directory of the primary
+partition on the SD card.
+
+The following elaborates the sequence of steps on how exactly an SD
+card is prepared for FAT Mode booting for the Beaglebone Black
+to boot from.
+
+Assuming that the SD card has not been formatted yet...
+
+Just to be safe, clear out the partition table at the base of the SD
+card to start fresh.
+
+	dd if=/dev/zero of=<device> bs=1M count=1
+
+The next step is to create a primary partition with the filesystem
+type set to FAT16.  This primary partition will be placed as an entry
+in an MBR located in the first sector of the SD card.  Fortunately,
+these intial steps are taken care of by the fdisk utility.
+
+To allocate a partition that will be formatted as FAT16 and to create
+an entry for the partition in the MBR,
+
+	fdisk <device>
+
+Suppose the SD card is registered under /dev as "sdc", this would be
+
+	fdisk /dev/sdc
+
+fdisk will then present a command-line dialog.
+
+From here, a new partition must be created using 'n'.  This partition
+must have a type of 0x06 for FAT16 which is set with 't' and with the
+size allocated to the partition to be at least 3MB.  This size is the
+minimum size required and is more than enough to hold a uMon image and
+to allow for future expansion.  It is recommended that not all of the
+sectors of the SD card are allocated to the FAT16 primary partition
+in order to provide room for the possibility of storing user data or
+perhaps a kernel.
+
+Once that is done, the next step is to mark the primary partition as
+bootable.  This is done using the 'a' option.
+
+With all that in place, the partition can be verified before writing
+it to the SD card with 'p'.  Once the partition has been verified,
+it can be written to the SD card using 'w'.
+
+After using fdisk to set up the partition, the new partition can be
+viewed under /dev.  So for example, if the base of the SD card is given
+as /dev/sdc, then the newly created FAT16 partition will be given as
+/dev/sdc1.
+
+The next step is to format this partition as FAT16:
+
+	mkfs.fat -f 2 -F 16 -M 0xF8 -s 1 -S 512 <device>
+
+with <device> set to the primary partition of the SD card.
+
+The final step is to place the "MLO" file in the root directory
+of the FAT16 primary partition.
+
+	cd ~
+	mkdir mnt
+	mount <device> mnt
+	cp <path_to_umon>/ports/beagleboneblack/build_BEAGLEBONEBLACK/MLO mnt
+	umount mnt
+	rmdir mnt
+
+In the previous set of commands, <device> is set to the primary
+partition of the SD card that was recently formatted as FAT16.
+
+The SD card is now ready.
+
+
+-----------------------------------------------------------------------
+UART:
+-----------------------------------------------------------------------
+Unlike booting from SD, booting via UART does not require any GP
+Header, Configuration Header TOC Structure, or both to be prepended to
+the uMon image.  The uMon image that will be booted using UART is
+boot.bin which is located in ./build_BEAGLEBONEBLACK.
+
+In order to boot from UART, a 3.3V USB-to-Serial cable is required,
+e.g. the FTDI USB TTL Serial cable is a possible option.
+
+The last requirement is to have a terminal emulator
+(e.g. minicom/picocom/etc.) set up to perform XMODEM transfers using
+1K packets and 16-bit CRC.
+
+To initiate the UART booting procedure on the Beaglebone Black, ensure
+that there is no uSD card inserted and then hold the boot switch down
+while powering up the board.  Once the board is powered on, the boot
+switch can be released.
+
+If a terminal emulator is set up already and connected to the serial
+port of the Beaglebone Black, the character 'C' will be outputted
+continuously.  This indicates that the UART booting procedure has
+initiated and is waiting for an image to be transferred via UART.
+
+From here, the uMon image can now be transferred using the terminal
+emulator.
+
+For more information on the UART boot procedure, please refer to the
+AM335x TRM Section 26.1.8.5 "UART Boot Procedure".
+=======================================================================
diff --git a/ports/beagleboneblack/sd_setup.sh b/ports/beagleboneblack/sd_setup.sh
new file mode 100755
index 0000000..a90059f
--- /dev/null
+++ b/ports/beagleboneblack/sd_setup.sh
@@ -0,0 +1,62 @@
+#!/usr/bin/bash
+#
+# This script automates the process of setting up an SD card for
+# either "raw" or FAT mode booting for the Beaglebone Black.
+
+if [ $# -ne 2 ]; then
+	echo -e  "Please specify both the boot mode and the SD card to set up\n"
+	echo -e "Usage: ./sd_setup.sh <boot mode> /dev/<device>\n"
+	echo -e "where <boot mode> is either RAW or FAT and <device> is the SD card"
+	exit 1
+fi
+
+BOOTMODE=$1
+SDDEV=$2
+
+case $1 in
+RAW)
+	if [ ! -e ./build_BEAGLEBONEBLACK/rawboot.bin ]; then
+		echo -e "rawboot.bin does not exist in ./build_BEAGLEBONEBLACK\n"
+		echo -e "Please build uMon before proceeding"
+		exit 1
+	fi
+
+	# Clear all offsets where a vaild uMon image for "raw" mode booting can exist
+	dd if=/dev/zero of=${SDDEV} bs=1M count=1
+
+	# Get the size of the uMon image to transfer into the SD card.
+	UMON_IMG_SIZE=`wc --bytes ./build_BEAGLEBONEBLACK/rawboot.bin | cut -f 1 -d ' '`
+
+	# Store the uMon image at offset 0x00000 by default
+	dd if=./build_BEAGLEBONEBLACK/rawboot.bin of=${SDDEV} bs=1 count=${UMON_IMG_SIZE}
+	;;
+FAT)
+	if [ ! -e ./build_BEAGLEBONEBLACK/MLO ]; then
+		echo -e "MLO does not exist in ./build_BEAGLEBONEBLACK\n"
+		echo -e "Please build uMon before proceeding"
+		exit 1
+	fi
+
+	# Clear the partition table at the base of the SD card
+	dd if=/dev/zero of=${SDDEV} bs=1M count=1
+
+	# Create the FAT16 primary partition and mark it bootable
+	echo -e "n\np\n1\n\n+3M\nt\n6\na\nw\n" | fdisk ${SDDEV}
+
+	# Wait for some time to allow the partition to register under /dev
+	sleep 1
+
+	mkfs.fat -v -f 2 -F 16 -M 0xF8 -s 1 -S 512 ${SDDEV}1
+
+	mkdir mnt
+	mount ${SDDEV}1 mnt
+	cp ./build_BEAGLEBONEBLACK/MLO mnt
+	umount mnt
+	rm -rf mnt
+	;;
+*)
+	echo -e "Invalid boot mode specified.  Valid boot modes are RAW/FAT."
+	exit 1
+	;;
+esac
+
-- 
2.3.4


