[[PageOutline]]

[=#bootloader]
= Newport U-Boot Bootloader
Gateworks supports the U-Boot Bootloader for the Newport product family. We provide pre-built firmware images (see [wiki:newport#firmware here]) as well as source for building and/or modifying it yourself.

One of the primary features of the Bootloader is to provide access to the {{{hwconfig}}} environment variable that the firmware uses for initial board configuration on power-up.

see [wiki:uboot] for more info on U-Boot

== Pre-Built U-Boot Firmware

Pre-Built U-Boot is contained inside of the Gateworks Newport boot firmware artifact here: [http://dev.gateworks.com/newport/boot_firmware/]

== Version

The U-Boot version used on the Newport boards is v2019.10
Source code is located here: [https://github.com/Gateworks/uboot-newport]

[=#default]
== Restoring defaults 
The Newport boot firmware has a copy of the original U-Boot env that was created during build time.

To restore default bootloader environment variables:

- At the "Hit any key to stop autoboot:" prompt press any key.

- Execute the following command:
{{{
run restore_env && reset
}}}

[=#hwconfig]
== hwconfig
The U-Boot Bootloader by convention provides a {{{hwconfig}}} environment variable which is used by the boot firmware (before U-Boot is loaded and executed) to configure board options at power-up. These options can include things such as:
 * miniPCIe socket functions (ie PCIe vs mSATA vs USB3.0)
 * serial configuration (ie RS232 vs RS485)

[=#socketconfig]
=== hwconfig: miniPCIe Socket Configuration
Newport board model socket options:
 * GW640x:
   - J9: USB2 and PCI (for build option for Mezzanine connector contact sales@gateworks.com)
   - J10: PCI or SATA and optional USB2 **(USB2 option removes it from top front panel USB connector)**
   - J11: USB2 and PCI
   - J12: USB2 and USB3
 * GW630x:
   - J9: USB2 and PCI (for build option for Mezzanine connector contact sales@gateworks.com)
   - J10: USB2 and PCI or SATA
   - J11: USB2 and PCI or USB3
 * GW620x:
   - J6: USB2 and PCI or USB3
   - J8: USB2 and PCI or SATA
 * GW610x:
   - J6: USB2 and PCI or SATA or USB3

Note that as PCIe, USB3.0 SS, and SATA share signals so if multiple options exist you must choose between them on those sockets using the {{{hwconfig}}} bootloader env variable.

If a socket is not specified in {{{hwconfig}}} then the PCI option will be the default.

You can get/set the {{{hwconfig}}} variable within the U-Boot bootloader but you must reboot the board for it to take effect as the variable is acted upon in the Secondary Program Loader (SPL).

Examples:
* GW620x:
  - J6 USB3 (removes PCI)
{{{#!bash
setenv hwconfig 'j6:usb3'; saveenv
}}}
  - J6 PCIe and USB2 (removes USB3)
{{{#!bash
setenv hwconfig ; saveenv
}}}
 * GW640x:
  - J10 SATA
{{{#!bash
setenv hwconfig 'j10:sata'; saveenv
}}}
  - J10 PCIe and USB2 (removes USB2 from top front panel USB connector)
{{{#!bash
setenv hwconfig 'j10:pci,usb2'; saveenv
}}}
 * GW630x:
  - J10 PCIe, J11 PCIe (default)
{{{#!bash
setenv hwconfig 'j10:pci;j11:pci'; saveenv
}}}
  - J10 mSATA, J11 USB3.0
{{{#!bash
setenv hwconfig 'j10:sata;j11:usb3'; saveenv
}}}
  - J9/J10 disabled, J11 PCIe
{{{#!bash
setenv hwconfig 'j9:disabled;j10:disabled;j11:pci'; saveenv
}}}

You can see that the {{{hwconfig}}} configuration took place by watching the output of the BDK during boot. For example:
{{{#!bash
Gateworks Newport SPL (3442703 Wed Jun 6 20:26:30 UTC 2018)

GSC     : v52 0xbf2d WDT:disabled board temp:38C
RTC     : 506646
Model   : GW6304-C
MFGDate : 03-28-2018
Serial  : 776375
DTB     : gw6304.dtb
SoC     : CN8030-1500BG676-SCP-P12-G 1024KB 1500/550MHz 0xa2 Pass 1.2
MMC0    : eMMC
MMC1    : not detected
Boot    : eMMC non-trusted
DRAM    : 2048 MB, 1333 MT/s, DDR4 UDIMM
J9      : PCI
J10     : SATA
J11     : USB3
QLM0    : PCIE_1X1@5000MHz
QLM1    : SGMII_1X1@1250MHz
QLM2    : DISABLED@5000MHz
QLM3    : SATA_2X1@6000MHz
Serial  : 2x RS232 without flow control
...
Hit any key to stop autoboot:  0
GW6304-C> print hwconfig
hwconfig=j10:sata;j11:usb3
}}}
 * The above shows that J9 is configured for PCI, J10 for SATA, and J11 for USB3

'''Note that {{{hwconfig}}} is also used for serial configuration so care should be taken to preserve that configuration if used''' 

[=#serialconfig]
=== hwconfig: serial Configuration
Many boards in the Newport product family provide a 5-pin off-board serial connector that provides the following options:
- 1x RS485 FD (UART2)
- 1x RS485 HD (UART2)
- 1x RS232 w/ hardware flow control (UART2)
- 2x RS232 w/o hardware flow control (UART2/UART3)

By default 2x RS232 with no flow control is enabled. To configure a different option use the {{{hwconfig}}} U-Boot env variable. The {{{mode}}} property of the {{{serial}}} option defines the initial configuration of the serial port(s). If RS485 is selected by the {{{mode}}} property the {{{term}}} property will select whether or not on-board termination is enabled.

The {{{mode}}} property can have the following values:
 * rs232 - 2x RS232 (UART2/UART3) without hardware flow control (default if not specified)
 * rs232_dtr - RS232 (UART2) with hardware flow control
 * rs485_hd - RS485 half-duplex
 * rs485_fd - RS485 full-duplex

Examples:
 * '''Note that setting {{{hwconfig}}} currently requires saveenv to be ran twice'''
 * Enable RS485 half duplex no on-board termination
{{{#!bash
setenv hwconfig "serial:mode=rs485_hd,term=no"; saveenv
}}}
 * Enable RS485 full duplex with on-board termination
{{{#!bash
setenv hwconfig "serial:mode=rs485_fd,term=yes"; saveenv
}}}
* Enable RS232 with hardware flow-control:
{{{#!bash
setenv hwconfig "serial:mode=rs232_dtr"; saveenv
}}}


'''Note that {{{hwconfig}}} is also used for pcie configuration so care should be taken to preserve that configuration if used''' 

= Editing the environment

If you would like to add your own arguments to the U-boot environment changes can be made to this file:
https://github.com/Gateworks/bsp-venice/blob/master/venice.env