Changes between Initial Version and Version 1 of uboot

Timestamp:

05/01/2023 09:42:53 PM (13 months ago)

Author:

Tim Harvey

Comment:

initial page

uboot

@@ +1 @@
+[[PageOutline]]
+
+= U-Boot Bootloader
+Gateworks uses U-Boot (the Universal Boot Loader) as a primary bootloader for all current product families. In some cases U-Boot is used as the 'secondary program loader' as well as the 'primary program loader'.
+
+The purpose of a bootloader is to load the Operating System (OS) and execute it. In terms of a Linux based OS this means loading the kernel image, device-tree blobs (optional), and initial ramdisk images (optional) into DRAM and executing the kernel with any necessary kernel arguments. Often this is done in an OS specific fashion via a U-Boot bootscript stored along-side the kernel Image.
+
+== Features and Peripheral support
+U-Boot has many features and peripheral support but it is not intended to be a full OS so some features do not work as well as they would on a Linux based OS for example. The intention of U-Boot is to provide enough support to load and execute the kernel therefore support for things like USB peripherals and high performance networking and I/O is not a priority and should not be expected.
+
+Many features can be enabled by re-building and re-installing U-Boot. For more information on building U-Boot see the product specific BSP pages.
+
+== Product Family specific notes
+
+[=#malibu]
+=== Malibu
+The Marvell CN913x based Malibu product family boots via a BOOT ROM internal to the CN913x which loads ARM Trusted Firmware (ATF) which contains a U-Boot payload image. In this case initial SoC chip and DRAM configuration is done by components in the ARM Trusted firmware
+
+see also [wiki:malibu/boot#u-boot]
+
+[=#venice]
+=== Venice
+The NXP i.MX 8M !Mini/Nano/Plus based Venice product family boots via a BOOT ROM internal to the i.MX8M which loads U-Boot SPL (Secondary Program Loader) which then loads U-Boot proper. In this case initial SoC chip and DRAM configuration is done by U-Boot SPL.
+
+see also [wiki:ventana/bootloader]
+
+
+[=#newport]
+=== Newport
+The Marvell CN803x based Newport product family boots via a BOOT ROM internal to the CN803 which loads Marvell's 'Board Disagnostics Kit' (BDK) (which we call the SPL) which in turn loads the ATF and U-Boot from a payload inside the ATF. In this case initial SoC chip and DRAM configuration is done by the Marvell BDK software.
+
+see also [wiki:newport/boot#u-boot]
+
+
+[=#ventana]
+=== Ventana
+The NXP i.MX 6Q/DL based Ventana product family boots via a BOOT ROM internal to the i.MX6 which loads U-Boot SPL (Secondary Program Loader) which then loads U-Boot proper. In this case initial SoC chip and DRAM configuration is done by U-Boot SPL.
+
+Ventana U-Boot enables and supports PCI and the PCI based i210 NIC found on several of the Ventana boards.
+ 
+see also [wiki:ventana/bootloader]
+
+
+[=#env]
+== Environment variables and scripts
+U-Boot uses environment variables to configure much of its functionality. U-Boot environment variables can also be treated as scripts and therefore the environment dictates how U-Boot achieves its goal of loading and executing the OS.
+
+You can use {{{env}}} commands to get or set env vars. For example:
+ * Get a var:
+{{{#!bash
+env print model
+}}}
+ * Set a var:
+{{{#!bash
+env set quiet 1
+}}}
+ * Load default values (does not save):
+{{{#!bash
+env default -f -a
+}}}
+ * Save current env:
+{{{#!bash
+env save
+}}}
+
+If you want to erase the env:
+{{{#!bash
+env erase
+}}}
+
+Some notable env variables used in U-Boot:
+||= Category =||= Name    =||= Purpose  =||
+|| boot || preboot   || script executed before 'Hit any key to abort' if CONFIG_USE_PREBOOT=y ||
+|| boot || bootcmd   || script executed at boot ||
+|| boot || bootdelay || number of seconds to wait for a key to abort automatic boot (if 0 will not wait) ||
+|| ||
+|| console || baudrate  || baudrate of serial console ||
+|| console || device of serial console ||
+|| ||
+|| network || ethprime  || primary ethernet device (used at boot) ||
+|| network || ethaddr   || mac addr of first eth interface ||
+|| network || eth1addr  || mac addr of second eth interface ||
+|| network || ethact    || active ethernet device (current) ||
+|| network || ipaddr    || local ip address ||
+|| network || serverip  || ip address of server for tftp commands ||
+|| network || netmask   || netmask address (optional) ||
+|| network || gatewayip || ip address of gateway (optional) ||
+|| network || ethrotate || if set to 'no' will not automatically rotate through network devices on network operations ||
+|| network || dhcp      || issue a DHCP request for network configuration (set 'autoload=no' to disable attempting to load an image) 
+|| ||
+|| distro config || boot_targets || ordered list of boot targets (ie 'mmc1 mmc2 usb0 usb1') ||
+|| distro config || boot_prefixes || ordered list of prefixes of boot scripts (ie '/ /boot') ||
+|| distro config || boot_scripts || ordered list of boot script names (ie 'boot.scr') ||
+|| ||
+|| automatic || board || board model (automatically set during boot) ||
+|| automatic || serial# || board serial number (automatically set during boot) || 
+
+=== U-Boot env location, format, and accessing outside of U-Boot
+There are several U-Boot config items (CONFIG_ENV_*) that specify where and how the U-Boot env is stored. Typically Gateworks configures 32KiB redundant env located at the end of the boot firmware. This means that U-Boot flips back and forth between the two env areas so that if a power-cut occurs during a 'saveenv' command it will default to the previous env saved.
+
+There are several applications built by U-Boot that facilitate accessing U-Boot env outside of U-Boot:
+ * fw_printenv / fw_setenv - uses a config file to allow env get/set from Linux
+ * mkenvimage - creates a binary image from a source file in the format of name=value
+
+The Ubuntu u-boot-tools package provides {{{fw_printenv}}} and {{{fw_setenv}}} but a config file must exist in {{{/etc/fw_env.config}}} (or specified via the -c parameter) which describe the env location and size:
+ * Malibu:
+{{{#!bash
+# Device               offset          Env. size
+/dev/mmcblk0boot0      0x3f0000        0x8000
+/dev/mmcblk0boot0      0x3f8000        0x8000
+}}}
+ * Venice:
+{{{#!bash
+# Device               offset          Env. size
+/dev/mmcblk2           0xff0000        0x8000
+/dev/mmcblk2           0xff8000        0x8000
+}}}
+ * Newport:
+{{{#!bash
+# Device               offset          Env. size
+/dev/mmcblk0           0xff0000        0x8000
+/dev/mmcblk0           0xff8000        0x8000
+}}}
+ * Ventana (NAND boot device):
+  - cat /proc/mtd
+{{{#!bash
+dev:    size   erasesize  name
+mtd0: 01000000 00040000 "uboot"
+mtd1: 00100000 00040000 "env"
+mtd2: 7ef00000 00040000 "rootfs"
+}}}
+  - cat /etc/fw_env.config
+{{{#!bash
+# device  offset size erasesize
+/dev/mtd1 0x0 0x20000 0x40000
+/dev/mtd1 0x80000 0x20000 0x40000
+}}}
+  * make sure /dev/mtd1 is your env partition 
+ * Ventana (MMC boot device)
+{{{#!bash
+# device  offset size erasesize
+/dev/mmcblk0 0xb1400 0x20000 0x20000
+/dev/mmcblk0 0xd1400 0x20000 0x20000
+}}}
+
+This will define the device being used, offset according to flash layout, size from flash map, and size of erase block (unless the device is a file). Ventana U-boot environment is redundant hence two entries, both locations need their variables updated.  
+
+Note that in certain circumstances the Linux representation of the boot device can change - please ensure that the devices specified do indeed point to your boot device.
+
+It is important to understand the meaning of the '''Warning: Bad CRC, using default environment''' message. This means that the non-volatile env area specified by the config file is empty or corrupt and that the built-in env within U-Boot will be used which is not appropriate. Note that Gateworks Ventana boards ship with an empty env area and use built-in defaults so if you wish to use the u-boot-tools to access the env from Linux first do a 'saveenv' from U-Boot to provide a valid default env.
+
+If you use {{{fw_setenv}}} on an environment in this state it will properly set the variable you specify and all other variables will continue to use their built-in default values within U-Boot. Essentially you are 'overriding' the defaults as you would expect.
+
+
+Example usage:
+{{{#!bash
+# display environment 
+fw_printenv -c fw_env.config 
+# set environment variable 
+fw_setenv  -c fw_env.config foo bar #foo being variable name bar being value variable will be set to
+#second example 
+fw_setenv  -c fw_env.config ipaddr 192.168.1.10
+#print single environment variable
+fw_printenv  -c fw_env.config foo
+#second example
+fw_printenv ipaddr
+}}}
+
+[=#bootflow]
+== Boot Flow
+Boot flow in U-Boot refers to how specifically U-Boot loads and passed control to the OS.
+
+After U-Boot initializes it does the following
+ * executes contents of 'preboot' env variable (if configured with CONFIG_USE_PREBOOT)
+ * based on the contents of 'bootdelay' env variable it prints 'Hit any key to stop autoboot:' and counts down the number of seconds specified (if set to 0 it will skip this and not allow you to stop execution manually)
+ * executes contents of 'bootcmd' env variable
+
+
+[=#distroconfig]
+=== Distro Config
+A set of scripts referred to as 'distro config' can be used to scan bootable partitions on a set of specified devices for boot scripts and execute the first one it finds.
+
+'''This configuration is used on Newport, Venice, and Malibu product families (not Ventana which pre-dated this concept)'''
+
+This feature provides a well defined U-Boot env intended to make it easier for distro maintainers to develop compatible bootscripts. This primarily entails a set of 'boot scripts' and variables that control them.
+
+Ultimately this U-Boot environment is looking for a U-Boot boot script on a 'bootable' partition (partitions with the 'boot' flag enabled). It searches in this order with these rules:
+ - **boot_targets** - list of target device type/nums to search: defaults to mmc1 mmc0 usb0 usb1 pxe dhcp
+ - **devplist** - ''dynamically created'' list of all partitions flagged as 'bootable'
+ - **boot_prefixes** - list of directories within a partition searched for bootscripts
+ - **boot_scripts** - list of boot script names searched for
+
+The boot device order is specified by the {{{boot_targets}}} env variable which typically defaults to something like {{{mmc1 mmc0 usb0 usb1 pxe dhcp}}}. For example, to limit OS booting to only mmc device 2 you would 'setenv boot_targets mmc 2; saveenv'.
+
+The Distro-Config environment supports legacy uImage scripts (it does not support FIT images with scripts).
+
+
+[=#bootscript]
+=== Boot script
+A boot script is a U-Boot specific set of commands wrapped inside a U-Boot binary header which can be loaded from a device or filesystem and executed via the 'source <address>' command.
+
+You can create these with the {{{mkimage}}} tool from U-Boot as such:
+{{{#!bash
+mkimage -A arm64 -T script -C none -d boot.txt boot.scr
+}}}
+
+The bootscript can be updated at runtime on the Linux target. For example:
+{{{#!bash
+mkimage -A arm64 -T script -C none -d boot.txt /boot/boot.scr
+}}}
+
+
+When writing bootscripts compatible with Generic Distro Config you can assume the following env variables:
+ - **devtype** - the device type the script was loaded from (mmc|usb|sata)
+ - **devnum** - the device number the script was loaded from (ie 0 for mmc0, 1 for mmc1, etc)
+ - **distro_bootpart** - the partition number the script was loaded from (ie 0, 1, etc)
+ - **fdtcontroladdr** - the address the device-tree is at (Note that the Malibu bootloader contains a static version of the board device-tree)
+ - **kernel_addr_r** - address where kernel can be loaded
+ - **bootargs** - default bootargs to pass to the kernel - you probably want to add to this and not overwrite it
+ - **console** - the serial console device to pass to the kernel
+
+Additionally you should note the following:
+ - use load/ls/save commands which support FAT/ext filesystem types automatically instead of the fs specific commands
+ - if using a root filesystem that is not supported by the bootloader (ie F2FS or BTRFS) you can place your bootscript and kernel image in the FAT12 filesystem on partition 1 of the boot device. This filesystem is part of the 16MB 'Boot Firmware' image. If doing so you will need to compress the kernel and package it into a [#fit FIT image] in order to fit it in the available space.
+
+
+[=#fit]
+== Flattened Image Tree (FIT) images
+The U-Boot bootloader supports Flattened Image Tree (FIT) images which expand greatly on the legacy U-Boot image (uImage) format by allowing multiple binary blobs within an image. These blobs can be kernel images, ramdisk images, device-tree blobs, and bootloader scripts. Each image can also be optionally compressed (meaning U-Boot will decompress it) and check-sumed with a variety of hash mechanisms (meaning U-Boot will verify the image before using it).
+
+Quick summary of FIT Images:
+ * introduced to resolve limitations with original single-image formats and follow-on multi-image format supported by UBoot bootm (boot memory)
+ * uses power of the Device-Tree-Compiler (DTC)
+ * FIT .itb files can be created with mkimage by passing in a .its file which in device-tree notation describes the images
+ * U-Boot supports FIT with several commands:
+  - {{{source <addr>:<name>}}} # source a script by name from FIT image in memory
+  - {{{iminfo <fitaddress>}}} # print all the info contained in a FIT image in memory and verify (just not boot it)
+  - {{{imextract <fitaddress> <item> <addr>}}} # extract item (ie kernel@1) to addr
+  - {{{bootm <fitaddress>[#conf] - $fdtcontroladdr}}} # boot default or 'conf' configuration (ie #config@1)
+  - {{{bootm start <fitaddress>[#conf] - $fdtcontroladdr}}} # boot from memory a specific configuration (or default configuration) from FIT image
+
+Example:
+ * kernel.its with a single compressed kernel for ARM64 
+{{{#!bash
+/dts-v1/;
+/ {
+        description = "Simple image with single Linux kernel";
+        #address-cells = <1>;
+        images {
+                kernel@1 {
+                        description = "Linux kernel";
+                        data = /incbin/("./Image.gz");
+                        type = "kernel";
+                        arch = "arm64";
+                        os = "linux";
+                        compression = "gzip";
+                        load = <0x40200000>;
+                        entry = <0x40200000>;
+                        hash@1 {
+                                algo = "sha256";
+                        };
+                };
+        };
+
+        configurations {
+                default = "conf@1";
+                conf@1 {
+                        description = "Boot Linux kernel";
+                        kernel = "kernel@1";
+                };
+        };
+};
+}}}
+ * create image:
+{{{#!bash
+cp arch/arm64/boot/Image .
+gzip Image
+mkimage -f kernel.its /tftpboot/kernel.itb
+}}}
+ * boot the default configuration from U-Boot:
+{{{#!bash
+tftpboot $loadaddr kernel.itb && bootm $loadaddr - $fdtcontroladdr
+}}}
+
+References:
+ * [http://git.denx.de/?p=u-boot.git;a=tree;f=doc/uImage.FIT doc/uImage.FIT]
+ * http://www.denx.de/wiki/pub/U-Boot/Documentation/multi_image_booting_scenarios.pdf
+ * http://elinux.org/images/f/f4/Elc2013_Fernandes.pdf
+
+
+
+[=#gpio]
+== General Purpose I/O (GPIO)
+The {{{gpio}}} command provides the ability to list and configure board-specific GPIO's.
+
+Examples:
+ * List GPIO's:
+{{{#!bash
+u-boot=> gpio status
+Bank GPIO1_:
+GPIO1_0: output: 0 [x] rs485_term.gpio-hog
+GPIO1_1: input: 0 [x] mipi_gpio4.gpio-hog
+GPIO1_5: output: 0 [x] regulator-wifi-en.gpio
+GPIO1_6: output: 0 [x] pci_usb_sel.gpio-hog
+GPIO1_7: input: 1 [x] dio0.gpio-hog
+GPIO1_8: output: 0 [x] regulator-usb-otg2.gpio
+GPIO1_9: input: 1 [x] dio1.gpio-hog
+GPIO1_12: output: 0 [x] regulator-usb-otg1.gpio
+
+Bank GPIO2_:
+GPIO2_12: input: 1 [x] mmc@30b50000.cd-gpios
+
+Bank GPIO3_:
+GPIO3_0: output: 0 [x] ethernet@30be0000.phy-reset-gpios
+
+Bank GPIO4_:
+GPIO4_0: output: 0 [x] rs485_en.gpio-hog
+GPIO4_1: input: 0 [x] mipi_gpio3.gpio-hog
+GPIO4_2: output: 0 [x] rs485_hd.gpio-hog
+GPIO4_3: input: 0 [x] mipi_gpio2.gpio-hog
+GPIO4_4: input: 0 [x] mipi_gpio1.gpio-hog
+GPIO4_7: output: 1 [x] pci_wdis#.gpio-hog
+
+Bank GPIO5_:
+GPIO5_4: output: 0 [x] led-1.gpios
+GPIO5_5: output: 0 [x] led-0.gpios
+}}}
+ * set GPIO named DIO1 to logic 1:
+{{{#!bash
+u-boot=> gpio set dio1
+gpio: pin dio1 (gpio 9) value is 1
+}}}
+ * set GPIO named DIO1 to logic 0:
+{{{#!bash
+u-boot=> gpio clr dio1
+gpio: pin dio1 (gpio 9) value is 0
+}}}
+ * read GPIO DIO1 logic level:
+{{{#!bash
+u-boot=> gpio input dio1
+gpio: pin dio1 (gpio 9) value is 0
+}}}
+
+
+
+[=#led]
+== LED support
+If LED support is enabled you can configure board LED's via U-Boot:
+ * List LED's:
+{{{#!bash
+u-boot=> led list
+led-0           off
+led-1           off
+}}}
+ * turn an LED on:
+{{{#!bash
+u-boot=> led led-0 on
+}}}
+ * turn an LED off:
+{{{#!bash
+u-boot=> led led-0 off
+}}}
+
+Note that many Gateworks boards have a front-panel bi-color LED which is supported by two distinct LED's for 'red' and 'green'. In this case you must enable one and disable the other (setting both 'on' is the same as setting both 'off').
+
+
+[=#gsc]
+== GSC support ==
+The {{{gsc}}} command that will let you interact with the Gateworks System controller on Gateworks boards.
+
+Examples:
+ * see basic info
+{{{#!bash
+u-boot=> gsc  
+GSCv3   : v61 0x1d6f RST:VIN Thermal protection:enabled at 96C 
+RTC     : 1970-01-05  22:36:56 UTC
+Model   : GW7301-01-CF
+Serial  : 928012
+MFGDate : 01-09-2023
+SOM     : GW7001-F 928012 01-09-2023
+BASE    : GW7301-C 878707 05-04-2022
+}}}
+ * disable primary power supply for 5 seconds
+{{{#!bash
+u-boot=> gsc sleep 5
+GSC Sleeping for 5 seconds
+}}}
+ * Show hardware monitor values:
+{{{#!bash
+u-boot=> gsc hwmon
+temp    : 47.9C
+vdd_bat : 3.216V
+vdd_vin : 16.724V
+vdd_adc1: 0.000V
+vdd_adc2: 0.000V
+vdd_dram: 1.119V
+vdd_1p2 : 1.192V
+vdd_1p0 : 0.000V
+vdd_2p5 : 0.000V
+vdd_3p3 : 3.272V
+vdd_0p95: 0.938V
+vdd_1p8 : 1.793V
+vdd_gsc : 2.950V
+}}}
+  - Note that the voltage rails connected to the GSC hardware monitor vary per board 
+
+
+[=#net]
+== Network
+U-Boot network support exists for the network controllers found within the SoC of the board. If PCI is supported by the product family there are a few PCI based network controller drivers as well.
+
+Because U-Boot is not a full OS and does not support background drivers network operations occur based on various network commands such as 'tftpboot', 'dhcp'. The network interface used for these commands is specified by the 'ethact' env variable. The 'net list' command available in newer versions of U-Boot can help identify the names of the network interface that can be used.
+
+To see a table showing the physical network interface mapping to U-Boot devices refer to:
+ * [wiki:malibu/ethernet Malibu Ethernet page]
+ * [wiki:venice/ethernet Venice Ethernet page]
+ * [wiki:newport/ethernet Newport Ethernet page]
+ * [wiki:ventana/ethernet Ventana Ethernet page]
+
+The following U-Boot environment variables are used with networking:
+ * {{{ipaddr}}} - local IP address
+ * {{{serverip}}} - TFTP server IP
+ * {{{netmask}}} - Netmask
+ * {{{gatewayip}}} - Gateway IP if needed
+ * {{{ethact}}} - controls which interface is currently active
+ * {{{ethprime}}} - controls which interface is used first
+ * {{{ethrotate}}} - when set to 'no' uboot does not go through all available network interfaces and instead just stays at the currently selected interface (ethact)
+ * {{{filesize}}} - gets set to the size of data transferred
+ * {{{netretry}}} - when set to 'no' each network operation will either success or fail without retrying. When set to 'once' the operation will fail only when all available network interfaces have been tried once without success.
+ * {{{tftpsrcport}}} - UDP source port (if not set uses default)
+ * {{{tftpdstport}}} - UDP dest port (if not set uses well known port 69)
+ * {{{tftpblocksize}}} - if not set will use TFTP server's default block size
+ * {{{tftptimeout}}} - retransmission timeout for TFTP packets in ms (min value is 1000, default is 5000)
+ * {{{dhcp}}} - Use DHCP to configure networking env
+
+
+[=#filesystem]
+== Generic File System and File Management support for Block storage devices
+For modern versions of U-Boot there are several commands that work with files which support multiple file systems and device interfaces eliminating the need for you to know what filesystem is used and avoid using the deprecated filesystem specific commands. For these commands you specify the interface name (ie mmc,usb,sata) , a device number and optionally a partition.
+ * load <interface> [<dev[:part]> [<addr> [<filename> [bytes [pos]]]]] - load a file to memory
+ * save <interface> [<dev[:part]> <addr> <filename> bytes [pos] - save a file from memory
+ * ls <interface> [<dev[:part]> [directory]] - list files on a device/directory
+ * ln <interface> <dev[:part]> target linkname - create a symlink
+ * size <interface> <dev[:part] <filename> - determine size of a file (saved in 'filesize' env variable)
+
+The 'part' command can be used to work with partition tables (both GPT and MBR if enabled):
+ * part uuid <interface> <dev>:<part> - print partition UUID
+ * part uuid <interface> <dev>:<part> <varname> - set varname to partition UUID
+ * part list <interface> <dev> - print partition table
+ * help part - see more options
+
+Note that for the usb interface you must start the interface first with a 'usb start' operation. USB bus enumeration does not happen in the background.
+
+
+[=#mmc]
+== MMC (eMMC and microSD)
+The 'mmc' command supports various low level operations on !MultiMediaCard bus devices such as eMMC and microSD when not working at the [#filesystem fileystem layer]. When working at this level you must set the current mmc device manually.
+ 
+Examples:
+ * mmc list - list available device numbers
+{{{#!bash
+u-boot=> mmc list
+FSL_SDHC: 0
+FSL_SDHC: 1
+FSL_SDHC: 2 (eMMC)
+}}}
+ * mmc dev [dev] [part] [mode] - show or set the current mmc device
+{{{#!bash
+u-boot=> mmc dev 2
+switch to partitions #0, OK
+mmc2(part 0) is current device
+u-boot=> mmc dev
+switch to partitions #0, OK
+mmc2(part 0) is current device
+}}}
+ * mmc info - show info for currently selected device:
+{{{#!bash
+u-boot=> mmc info
+Device: FSL_SDHC
+Manufacturer ID: 70
+OEM: 0
+Name: IB2964
+Bus Speed: 200000000
+Mode: HS400 (200MHz)
+Rd Block Len: 512
+MMC version 5.1
+High Capacity: Yes
+Capacity: 58.4 GiB
+Bus Width: 8-bit DDR
+Erase Group Size: 512 KiB
+HC WP Group Size: 8 MiB
+User Capacity: 58.4 GiB
+Boot Capacity: 4 MiB ENH
+RPMB Capacity: 4 MiB ENH
+Boot area 0 is not write protected
+Boot area 1 is not write protected
+}}}
+ * mmc help - show more options
+
+
+[=#usb]
+== USB
+The 'usb' command supports various low level operations on Universal Serial Bus hosts and devices when not working at the [#filesystem fileystem layer]. When working at this level you must set the current usb device manually. Additionally you must use the 'usb start' command to initialize the USB subsystem and enumerate the bus. USB bus enumeration does not happen in the background.
+ 
+Examples:
+ * usb start - start and scan the USB controllers
+ * usb tree - show a tree view of USB enumerated devices
+ * help usb - more USB commands and options
+
+Example Usage:
+{{{#!bash
+u-boot=> usb start && usb tree
+starting USB...
+Bus usb@32e40000: Bus usb@32e50000: USB EHCI 1.00
+scanning bus usb@32e40000 for devices... 1 USB Device(s) found
+scanning bus usb@32e50000 for devices... 4 USB Device(s) found
+       scanning usb for storage devices... 1 Storage Device(s) found
+USB device tree:
+  1  Hub (480 Mb/s, 0mA)
+     u-boot EHCI Host Controller 
+   
+  1  Hub (480 Mb/s, 0mA)
+  |  u-boot EHCI Host Controller 
+  |
+  +-2  Hub (480 Mb/s, 0mA)
+    |  Microchip Tech USB2744 
+    |
+    +-3  Mass Storage (480 Mb/s, 100mA)
+    |     CENTON USB 52D0CE92
+    |  
+    +-4  Vendor specific (480 Mb/s, 0mA)
+         Microchip Tech Hub Controller 
+
+}}}
+
+
+=== USB Device support (via USB Host mode)
+A very small set of USB devices are supported in U-Boot depending on the version and configuration. Typically the following devices are used during development:
+ * USB Network Adapters
+ * USB Mass Storage
+
+
+[=#usbnet]
+==== USB Network Adapters
+A very small set of USB network adapters are supported in U-Boot depending on the version and configuration:
+ * ASIX AX8817X - (ie [http://plugable.com/products/usb2-e100 Plugable USB2-E100 10/100mbps)
+  * network device: asx0
+ * SMSC LAN95xx
+  * network device: sms0
+
+Depending on the version of U-Boot more devices may be available
+
+To use these use the following U-Boot configuration:
+ 1. scan USB bus for supported devices:
+{{{#!bash
+usb start
+}}}
+  * If you have a supported USB device attached you will see a message to that effect
+ 2. set active ethernet device (use 'net list' to see a list of device names)
+{{{#!bash
+setenv ethact asx0
+}}}
+ 3. Use networking as needed:
+{{{#!bash
+ping 192.168.1.254
+tftp ${loadaddr} ${file}
+}}}
+
+
+[=#ums]
+==== USB Mass Storage (UMS) Device
+USB Mass Storage (UMS) device support is not as robust as it is on Linux. Specifically some older devices that have support for various quirks in Linux may not work in U-Boot.
+
+Older UMS devices sometimes fail to enumerate on the bus. If you encounter this you can try the following:
+ - see if it enumerates on a different port (sometimes enumerating through an on-board USB HUB can be problematic). If your board has a USB OTG or Type-C connector those interfaces do not go through a USB HUB so try your UMS device there
+ - try setting the 'usb_pgood_delay' env variable to something like 2000 before you do your 'usb start'. This represents a millisecond delay between enabling the VBUS regulator and enumerating the bus
+
+Example:
+{{{#!bash
+u-boot=> usb start && usb tree
+starting USB...
+Bus usb@32e40000: Bus usb@32e50000: USB EHCI 1.00
+scanning bus usb@32e40000 for devices... 1 USB Device(s) found
+scanning bus usb@32e50000 for devices... 4 USB Device(s) found
+       scanning usb for storage devices... 1 Storage Device(s) found
+USB device tree:
+  1  Hub (480 Mb/s, 0mA)
+     u-boot EHCI Host Controller 
+   
+  1  Hub (480 Mb/s, 0mA)
+  |  u-boot EHCI Host Controller 
+  |
+  +-2  Hub (480 Mb/s, 0mA)
+    |  Microchip Tech USB2744 
+    |
+    +-3  Mass Storage (480 Mb/s, 100mA)
+    |     CENTON USB 52D0CE92
+    |  
+    +-4  Vendor specific (480 Mb/s, 0mA)
+         Microchip Tech Hub Controller 
+       
+u-boot=> usb storage
+  Device 0: Vendor: CENTON   Rev: 8.07 Prod:                 
+            Type: Removable Hard Disk
+            Capacity: 61500.0 MB = 60.0 GB (125952000 x 512)
+u-boot=> ls usb 0:1 boot
+<DIR>       4096 .
+<DIR>       4096 ..
+             860 boot.scr
+        10407524 Image
+}}}
+
+
+[=#gadget]
+=== USB Device Gadget support
+Very limited support for USB device/gadget mode exists
+
+
+[=#gadgetums]
+==== USB Mass Storage (UMS) Gadget
+The 'ums' command can be used to allow a host PC to access (slowly!) a block storage device on your target board.
+
+On boards that support this with a USB OTG or Type-C connector cabled to a PC USB host you can use:
+ * ums <usb_controller> [<devtype>] <dev[:part]> - usb controller is the number of the usb controller (ie 0 or 1) to present the interface on while devtype, dev, and part specify the interface (devtype), device number (dev), and optional partition to expose via the USB Mass Storage device class
+
+Examples:
+ * expose mmc device 0 on USB host controller 0 as a USB Mass Storage device:
+{{{#!bash
+usb start && ums 0 mmc 0
+}}}
+
+
+[=#pci]
+== PCI
+PCI bus support is enabled on the Ventana family due to the fact that at least one Ventana board model has only PCI based network interfaces.
+
+
+
+[=#netconsole]
+== !NetConsole (access U-Boot console from network)
+U-Boot does not contain any TCP implementation and as such there is no 'telnet server' or 'telnetd' support. There is however something similar called '!NetConsole' which will allow stdin/stdout/stderr to be directed to a UDP network port. If you set this up you can use the Linux 'nc' or 'netcat' tool or use the the 'netconsole' shell script provided in tools/netconsole (which uses these tools) to talk to U-Boot's interpreter from a Linux host.
+
+Using !NetConsole, the paradigm is reversed from the telnet/ssh perspective a bit such that you need to configure U-Boot to listen to a specifc IP address of a server.
+
+To enable !NetConsole you must do the following:
+ - U-Boot:
+  * configure networking: For example have a network interface supported by U-boot, set {{{ipaddr}}} env variable and {{{serverip}}} env variable (make sure you can {{{ping $serverip}}}):
+{{{
+setenv ipaddr 192.168.1.1 # local ip
+setenv serverip 192.168.1.146 # host ip running netcat/netconsole
+}}}
+  * set the {{{ncip}}} address to your server:
+{{{
+setenv ncip ${serverip}
+}}}
+  * set stdin/stdout/stderr as desired to {{{nc}}}:
+{{{
+setenv stdin nc; setenv stdout nc; setenv stderr nc
+}}}
+  * (optional) if you want these changed persistent, do a {{{saveenv}}}:
+{{{
+saveenv
+}}}
+ - Linux host:
+  * make sure you have netcat (either {{{nc}}} or {{{netcat}}} applications)
+  * grab the {{{netconsole}}} shell script from U-Boot's tools directory:
+{{{#!bash
+wget https://raw.githubusercontent.com/Gateworks/u-boot-imx6/gateworks_v2015.04/tools/netconsole
+chmod +x netconsole
+}}}
+  * use {{{netconsole}}} to listen to your target IP address for input/output:
+{{{#!bash
+netconsole 192.168.1.1
+}}}
+   - Note that netconsole remaps the interrupt from Cntl-C to Cntl-T so that you can use Cntl-C over the network console
+
+
+For a bootloader configuration that sits waiting for network commands from a specific host but with a timeout you can use the preboot env variable to execute a script prior to bootcmd such as:
+{{{
+setenv serverip 192.168.1.146 # your server ip
+setenv ipaddr 192.168.1.1 # your local ip
+setenv netretry no
+setenv preboot 'echo "Looking for server at $serverip..."; \
+ if ping $serverip; then setenv ncip ${serverip}; setenv bootdelay 10; \
+ echo "Starting NetConsole to ${ncip} and waiting for ${bootdelay} seconds..."; \
+ setenv stdin nc; setenv stdout nc; setenv stderr nc; \
+ fi'
+saveenv
+}}}
+ * Note that we set {{{netretry}}} to 'no' which causes network operations to not retry (otherwise the ping will go forever). This could also be set to 'once' if you wish to cycle through all available network interfaces (such as on-board NIC's as well as USB nics) instead of just 'ethprime'.
+
+This only pertains to input/output of the U-Boot environment. Once the bootloader jumps to the kernel, the kernel is in charge of what to do about its input/output, which is controlled via the 'console' kernel cmdline. Note that there is a CONFIG_NETCONSOLE option in the kernel that uses a 'netconsole' kernel cmdline however that option is not enabled in the Gateworks kernels by default
+
+References:
+ * https://github.com/Gateworks/u-boot-imx6/blob/gateworks_v2015.04/doc/README.NetConsole