k3-bootswitch/README.rst

   1 K3-bootswitch tool
   2 ==================
   3
   4 This tool allows to boot the board in any boot mode from command line.
   5 This is useful for controlling the board remotely for individual developers
   6 as well as test farm.
   7
   8 Hardware setup
   9 --------------
  10
  11 * USB cable should be connected from the board to the Linux PC
  12 * Note that on am65xx-evm, there is an adapter board for PCIe / USB.
  13   This should be used for connecting the USB cable.
  14   DFU boot is only supported from this port.
  15 * UART cable should be connected from the main_uart to Linux PC
  16 * Default switch settings should be for DFU boot mode
  17 * Power supply to the board should be connected via phidget USB relay
  18
  19
  20 Switch settings for DFU boot mode
  21 ---------------------------------
  22
  23 * j721e-evm settings  => SW8 = 1000 0000      SW9 = 0010 0000      SW3 = 0101 00 1010
  24 * am65xx-evm settings => SW2 = 0000 0000 00   SW3 = 0001 0000 00   SW4 = 11
  25
  26 Usage
  27 -----
  28
  29 * Install dfu-util package on the Linux PC with
  30     ``sudo apt-get install dfu-util``
  31 * To boot the j721e-evm board in MMC bootmode, run following
  32     ``sudo ./dfu-boot.sh --j721e-evm --bootmode mmc``
  33
  34   Currently supported bootmodes are: **mmc, emmc, ospi, uart, noboot**
  35
  36 * To mount the emmc from j721e-evm board to the Linux PC, run following
  37     ``sudo ./dfu-boot.sh --j721e-evm --mount 0``
  38 * To mount the SD card from am65xx-evm board to the Linux PC, run following
  39     ``sudo ./dfu-boot.sh --am65xx-evm --mount 1``
  40
  41
  42 Advantages
  43 ----------
  44
  45 * Allows to remotely control the board by eliminating need to physically
  46   change the switch settings
  47 * Can be used for regular development flow, where it removes the need
  48   to physically plug out the SD card for updating images.
  49 * Makes it very easy to partition, format and update contents of the
  50   eMMC device.
  51 * Can be used for factory flashing of the OSPI/eMMC images using
  52   automated scripts
  53
  54 How it works
  55 ------------
  56 The DFU bootmode allows to pass any custom bootloader to the board. By keeping
  57 the switch settings in DFU mode, board always waits for the Linux PC to send
  58 a bootloader. In Keystone3 SoC, the BOOTMODE and MCU_BOOTMODE registers reflect the
  59 values of the boot switches at the cold boot. This register can be modified and
  60 the values written are retained through the warm reset. These two features
  61 allows to set the bootmode from the command line PC tool.
  62
  63 In the **boot_select** directory of this tool, there are many files which act
  64 as the custom bootloader every time the board boots with DFU-boot mode.
  65 The custom bootloader does only two important things; First it overwrites the
  66 BOOTMODE and MCU_BOOTMODE registers to change to the desired boot mode and then
  67 it issues a soft reset to the SoC causing it to boot the second time with new
  68 bootmode.
  69
  70 All of this happens very fast when run from a script that it does not add
  71 considerable amount of time for developer bootflow.
  72
  73 The mount of SD card or eMMC is achieved using the u-boot's
  74 UMS (USB Mass Storage) feature. In this case, the tool sends a real R5 u-boot as
  75 bootloader, System firmware ITB, A72 u-boot images and then runs the ums command.
  76 Note that all the binaries are being sent from the Linux PC, so there is
  77 absolutely no dependency on the contents of SD card.
  78
  79
  80 Customization
  81 -------------
  82
  83 Default setup assumes most common setup for Keystone3 EVM. In case you are using
  84 differnent mechanism, update the **dfu-boot.sh** script with following:
  85
  86 * Update the **uart_dev** variable to reflect the correct tty device
  87   for main uart. (The one where all u-boot/SBL/kernel logs appear)
  88 * Update the **switch** variable to reflect the correct switch number  which
  89   controls the power via phidget
  90 * If you have a different mechanism to power the board, write your own implementation
  91   for **toggle_power** function instead of the default phidget commands
  92
  93
  94
  95 Limitatinos
  96 -----------
  97
  98 * Do not use this mechanism to measure any boot time numbers
  99 * The bootloader images are specific to TI EVMs. Different images are required
 100   to be able to mount the SD/eMMC from custom boards
 101 * The u-boot will try to import the environment from eMMC. If that is broken,
 102   it will cause issues in mounting the devices using UMS