DHCOM Update Mechanism: Difference between revisions

From Wiki-DB
Jump to navigationJump to search
 
(34 intermediate revisions by 2 users not shown)
Line 1: Line 1:
The DHCOM Update Mechanism for the i.MX6 Module can be used to flash a complete system image or to replace on some parts (e.g. linux kernel) of the system. It is not necessary to have a running os. The only requirement is a running bootloader.  
This version of the DHCOM Update Mechanism is available for our DHCOM i.MX6, DHCOM i.MX6ULL and DHCOM AM335x and can be used to flash a complete system image or to replace on some parts (e.g. linux kernel) of the system. It is not necessary to have a running os. The only requirement is a running bootloader.
 
If you are working with DHCOM AM35x or DHCOM i.MX25 please have a look at [[DHCOM_Flash_Update|DHCOM Flash Update]].


__TOC__
__TOC__
= Overview =
= Overview =
The following updates and commands are supported by the mechanism:
The following updates and commands are supported by the mechanism:
:{| class="wikitable" | style="width: 50%; color: #000000; background: #f3f3f3;" valign="top" |
:::{| class="wikitable" | style="width: 50%; color: #000000; background: #f3f3f3;" valign="top" |
|-
|-
| style="background: #076b8d;" | '''''command'''''  
| style="background: #076b8d;" | '''''command'''''  
Line 10: Line 12:
|-
|-
|| <tt>bootloader</tt> || update the bootloader
|| <tt>bootloader</tt> || update the bootloader
|-
|| <tt>script</tt> ||  bootloader executes the provided bootloader script e.g. to customize bootloader environment variables
|-
|-
|| <tt>splash</tt> || write a new *.bmp to display a bootloader splashscreen
|| <tt>splash</tt> || write a new *.bmp to display a bootloader splashscreen
Line 30: Line 34:
|}
|}


= How does it work =
= How does it work? =
* The update mechanism has to be started with the bootloader command "'''''<tt>update</tt>'''''".
* The updates "'''''<tt>bootloader</tt>'''''", "'''''<tt>script</tt>'''''", and "'''''<tt>eeprom</tt>'''''" are processed by the bootloader. They can be started directly with "'''''<tt>update <command> <imagefile></tt>'''''" for example "'''''<tt>update bootloader u-boot_imx6dl-dhcom2_1G.imx</tt>'''''"
* For the remaining updates you need a "'''''update kernel'''''". The "'''''update kernel'''''" is a file which contains the linux kernel binary (zImage), a busybox rootfilesystem with shell scripts (*.cpio), and a devicetree blob (*.dtb). This implies that the update kernel has to match your board configuration like the bootloader, linux kernel, and devicetree concerning '''CPU Type''', '''CPU Cores''', '''RAM''' and '''NAND''' or '''eMMC''' memory.
* To control the processing of the updates you need to provide a "'''''DHupdate.ini'''''" file to the update kernel.
* For further Details see the following chapters.


:[[Image:Flash Update Overview.png|1020px]]
= Downloads =
For the "'''''update kernel'''''" please have a look at the [[COM_iMX6-D2#Downloads| i.MX6 Downloads]], [[COM_iMX6ULL-D2#Downloads| i.MX6ULL Downloads]] or [[COM_AM335-D2#Downloads| AM335x Downloads]] section.


= Modes =
= Execution Modes =
== Automatically Update =="
== Automatic Mode ==
:Is called after the start of the bootloader if the environment variable '''bootcmd''' contains "'''update auto'''". The functionality tries to update the flash content via the [[#DHupdate.ini file|'''DHupdate.ini file''']]. The update mechanism is searching for the update files on the specified storage devices. The update devices must be defined at the settings block (Please have a look at [[DHCOM Settings|'''DHCOM settings''']]). With the DHupdate.ini file you have the possibility to run more then one updates, e.g. OS image and settings block.
* To use the "'''''automatic mode'''''" the command "'''<tt>update auto</tt>'''" has to be called within the bootloader environment variable '''<tt>bootcmd</tt>'''. The functionality does search a [[#DHupdate.ini file|'''DHupdate.ini file''']] on the specified storage devices e. g. '''update devices'''. The update devices must be defined at the DHCOM settings block (Please have a look at [[DHCOM Settings|'''DHCOM settings''']]). The content of the DHupdate.ini file controls which updates have to be processed and which images have to be written to the storage device (eMMC or NAND) of the DHCOM computer on module system.


== Command line Update ==
== Commandline Mode ==
#Instruction: "'''update'''"  
*Instruction: "'''update'''"  
#:The functionality tries to update the flash content via the [[#DHupdate.ini file|'''DHupdate.ini file''']]. In contrast to Automatically Update (which you can start with "'''update auto'''") the update mechanism is searching on every available storage device for the update files.
*:The functionality tries to update the flash content via the [[#DHupdate.ini file|'''DHupdate.ini file''']]. In contrast to Automatically Update (which you can start with "'''update auto'''") the update mechanism is searching on every available storage device for the update files.
#Instruction: "'''update <type> [filename]'''"  
*Instruction: "'''update <command> [filename]'''"  
#:The functionality '''doesn't use the DHupdate.ini file'''. It allows only one update and the update mechanism is searching on every available storage device for the update files. With the <type> parameter you have to specify the update type.  
*:The functionality '''doesn't use the DHupdate.ini file'''. It allows only one update and the update mechanism is searching on every available storage device for the update files. With the <command> parameter you have to specify the update type. If no [filename] is passed, the default file name will be used.
#:The following <type> parameters are possible from command line:
::The following <command> parameters are possible from command line:
#::* bootloader = Bootloader update
:::{| class="wikitable" | style="width: 50%; color: #000000; background: #f3f3f3;" valign="top" |
#:::Note: The ENV in Flash memory is created on the first start of u-boot. If you run a bootloader update and the ENV at the new bootloader has changed, the ENV in Flash memory remains unchanged with the bootloader update. But you could delete the ENV block in flash memory before the update, then u-boot will create the new default ENV at the next start after the bootloader update.
|-
#::* eeprom = Display adaptor EEPROM update with DH settings
| style="background: #076b8d;" | '''''command'''''
#::* reset = Execute a reset after a successfull update. A reset can only be the last item in a DHupdate.ini file.  
| style="background: #076b8d;" | '''''description'''''
#::: Note:  Be careful with the reset command. You can easily build a endless update loop by mistake.
|-
#::* script = Run bootloader script.
|valign="top"| <tt>bootloader</tt> || update the bootloader
#:The [filename] parameter could be used to specify a non default filename. The default filenames are:
:Note: The ENV in Flash memory is created on the first start of u-boot. If you run a bootloader update and the ENV at the new bootloader has changed, the ENV in Flash memory remains unchanged with the bootloader update. But you could delete the ENV block in flash memory before the update, then u-boot will create the new default ENV at the next start after the bootloader update.
#::* bootloader = default file name u-boot.imx
Default file name = u-boot.imx (i.MX6) / u-boot-with-spl.imx (i.MX6 | i.MX6ULL) / u-boot.img (AM335x)
#::* eeprom = default file name eeprom.bin
|-
#::* reset = no file to specify
|| <tt>script</tt> ||  bootloader executes the provided bootloader script e.g. to customize bootloader environment variables
#::* script= default file name script.bin
default file name = script.bin
|-
|| <tt>eeprom</tt> || update the display timings stored in the display adapter EEPROM
default file name = eeprom.bin
|-
|| <tt>reset</tt> || reboot system after a successful update. A reset can only be the last item in a DHupdate.ini file.  
<font color="#C90646">Warning: Risk of a infinite update loop.</font>
|-
|}


= DHupdate.ini file =
= DHupdate.ini file =
:The DHupdate.ini file is a text file, which describes the user specified update mechanism.  
The DHupdate.ini file is a ASCII text file, which controls the update mechanism.  
== Syntax ==
:[[Image:DHupdate_file_layout.png|800px]]


:[[Image:DHupdate_file_layout.png|700px]]
:The <type> parameter could be specified as follows:
:::{| class="wikitable" | style="width: 50%; color: #000000; background: #f3f3f3;" valign="top" |
|-
| style="background: #076b8d;" | '''''<type>'''''
| style="background: #076b8d;" | '''''description'''''
|-
|| <tt>bootloader</tt> || update the bootloader
|-
|| <tt>script</tt> ||  bootloader executes the provided bootloader script e.g. to customize bootloader environment variables
|-
|| <tt>splash</tt> || write a new *.bmp to display a bootloader splashscreen
|-
|valign="top"| <tt>settings</tt> || DHCOM bootloader settings
: Note: Please have a look at [[DHCOM Settings|DHCOM settings]].
|-
|valign="top"| <tt>refresh</tt> || Set the new display settings for the current update process
|-
|| <tt>copy</tt> || copy a file e. g. uLinuxEnv.txt into the boot partition
|-
|| <tt>linux</tt> || update the linux kernel binary e. g. zImage
|-
|| <tt>devicetree</tt> || update the devicetree blob
|-
|valign="top"| <tt>rootfs</tt> || Create or replace the linux root-filesystem which is stored in the Flash. The rootfs update has to be the last item (or second to last item if you insert the <code>reset</code> command) in the DHupdate.ini file. For further Details: [[DHCOM Update: Linux Root Filesystem|DHCOM Update: Linux Root Filesystem]]
|-
|| <tt>finetuning</tt> || run a provided script to do some finetuning on our installation (warning: experts only)
|-
|| <tt>eeprom</tt> || update the display timings stored in the display adapter EEPROM
|-
|valign="top"| <tt>reset</tt> || reboot system after a successful update
: Note: If you update the DHCOM settings, it is possible to use the new settings for the update progress notifications on the display, by inserting the "refresh" command to the [update] section. The bootloader loads the new settings and calls the '''update kernel''' with the new parameters.
|}


:The <type> parameter could be specified as follows:
== Example ==
::* linux = Linux image update
##DHCOMupdate##
::* rootfs = Create or replace the linux root-filesystem which is stored in the Flash. The rootfs update has to be the last item (or second to last item if you insert the <code>reset</code> command) in the DHupdate.ini file. For further Details: [[DHCOM Update: Linux Root Filesystem|DHCOM Update: Linux Root Filesystem]]
[display]
::* bootloader = Bootloader update
800x480_progress.bmp
::* splash = Bootbitmap update
  800x480_done.bmp
::* settings = DHCOM Settings block update
800x480_error.bmp
::: Note: Please have a look at [[DHCOM Settings|DHCOM settings]].
[led]
::* eeprom = Display adaptor EEPROM update with DH settings
  GPIO_E high
::* reset = Execute a reset after a successfull update. A reset can only be the last item in a DHupdate.ini file.  
::: Note: Be careful with the reset command. You can easily build a endless update loop by mistake.
::* script = Run bootloader script file
::* refresh = Refresh Display parameter before display update bitmaps.
::: Note: If you update the DHCOM settings, it is possible to use the new settings for the update progress notifications on the display, by inserting the "refresh" command to the [update] section. The bootloader loads the new settings and calls the '''update kernel''' with the new parameters. The '''update kernel''' displays the bitmaps which are specified in the <code>display</code> section. Example:
  [update]
  [update]
  settings 00_PV.bin
  settings 13_DataImage_7inch_FG0700G3DSSW.bin
  refresh
  refresh
bootloader u-boot-nand.imx
  splash DH_800x480.bmp
  splash DH_800x480.bmp
  ...
  linux zImage
devicetree dtbs/imx6dl-dheva01.dtb
rootfs imx6_debian_rootfs.tar.bz2
  [end]
  [end]
:The following updates are done by the '''bootloader''':
::* bootloader (only in case of command line update)
::* eeprom
::* script
:The following updates are done by the '''update kernel''':
::For this updates u-boot loads a minimal linux kernel which does the work. We call this tiny kernel in the further description "Update Kernel". The update kernel is loaded via the env variable "'''load_update_kernel'''". These variable needs to be set before. This could be done with the update script functionality.
::Before the bootloader loads the update kernel the variables "'''dev'''" and "'''part'''" will be set with the current update medium. So this variable could be used in "load_update_kernel" as placeholder for loading the update kernel from the current update device.
::* bootloader (only in case of DHupdate.ini File update)
::* linux
::* rootfs
::* settings
::* splash
:The [filename] parameter could be used to specify a non default filename. The default filenames are:
::* wince = default file names nk.gz or nk.bin
::* linux = default file name uImage + default script file name uImage.env
::* rootfs = default file name fsroot.tar.gz
::* bootloader = default file name u-boot.bin
::* splash = default file name splash.bmp
::* settings = default file name settings.bin
::* eeprom = default file name eeprom.bin
::* reset = no file to specify
::* script = default file name script.bin


:For DHupdate.ini File Example, please have a look at the Please have a look at [[COM iMX25 Bootloader U-Boot#Downloads|Download area iMX25]] or [[COM AM35 Bootloader U-Boot#Downloads|Download area AM35x]].
'''Notes:'''
:'''Notes:'''
:*<font color="#C90646">It is necessary to use UNIX End Of Line conversion!!!</font>
:*It is necessary to use UNIX End Of Line conversion!!!
:*The order of the bitmap-filenames in the section <code>display</code> tells the system when to display which bitmap.
:*The order of the bitmap-filenames in the section <code>display</code> tells the system when to display which bitmap.
.*If you use "refresh" command, please ensure that settings bin update is listed in DHupdate.ini file before "refresh" command.
:*If you use "refresh" command, please ensure that settings bin update is listed in DHupdate.ini file before "refresh" command.
 
= Bootloader Handled Updates =
The following updates are done by the '''bootloader''':
:* bootloader (only in case of command line update)
:* refresh
:* eeprom
:* script
= "Update Kernel" Handled Updates =
The following updates are done by the '''update kernel''':
:* bootloader (only in case of DHupdate.ini File update)
:* copy
:* linux
:* devicetree
:* rootfs
:* settings
:* splash
:* finetuning
 
'''Note:''' The [filename] parameter '''has to''' be defined if you use the '''''update kernel'''''.
 
= Loading the "Update Kernel" =
If the bootloader detects updates which have to be handled from a "update kernel" it defines the bootloader variables '''<tt>src_intf=usb</tt>''' or '''<tt>src_intf=mmc</tt>''' and '''<tt>src_dev_part=0:1</tt>''' to specify the location of the DHupdate.ini file. Then the bootloader executes the environment variable '''<tt>load_update_kernel</tt>'''. Take care about the content of this variable for example with the <tt>update script scriptfile.bin</tt> functionality.
== Example ==
setenv console ttymxc0,115200
setenv setupdateargs 'setenv bootargs console=${console} src_intf=${src_intf} src_dev_part=${src_dev_part} dhcom=${dhcom} \ <br/>                      ${backlight} ${parallel_display} ${lvds_display0} ${lvds_display1} vt.global_cursor_default=0'
setenv load_update_kernel 'load ${src_intf} ${src_dev_part} ${loadaddr} zImage_${dhcom}.update; run setupdateargs; bootz ${loadaddr}'


:'''Update progress LED description''':
= Update progress LED description =
::The LED GPIO is activated as soon as update has started. This takes roughly 6 - 8 seconds. If the update was finished without an error, the LED GPIO is deactivated. If an error occurs during the update the LED GPIO begins blinking.
The LED GPIO is activated as soon as update has started. This takes roughly 6 - 8 seconds. If the update was finished without an error, the LED GPIO is deactivated. If an error occurs during the update the LED GPIO begins blinking.
::LED error code:
:LED error code:
::1 LED blinking interval = DHupdate.ini File error (Wrong file content or no valid file found)
::1 LED blinking interval = DHupdate.ini File error (Wrong file content or no valid file found)
::2 LED blinking interval = Necessary File for Update not found
::2 LED blinking interval = Necessary File for Update not found
Line 118: Line 170:
::5 LED blinking interval = Specified file not valid (e.g. linux *.env file)
::5 LED blinking interval = Specified file not valid (e.g. linux *.env file)
::6 LED blinking interval = Image file size is to large
::6 LED blinking interval = Image file size is to large
::7 LED blinking interval = Can't load update kernel
::7 LED blinking interval = Can't load update kernel / Internal ERROR
 
= Necessary Files =
The content of our update media e.g. usb flash memory device should look similar to this example here:
 
:[[Image:Updatemedea_filestruct_example.PNG |604px]]
 
= Flowchart of the Update Process =
 
:[[Image:Flash Update Overview.png|1750px]]

Latest revision as of 12:01, 3 March 2020

This version of the DHCOM Update Mechanism is available for our DHCOM i.MX6, DHCOM i.MX6ULL and DHCOM AM335x and can be used to flash a complete system image or to replace on some parts (e.g. linux kernel) of the system. It is not necessary to have a running os. The only requirement is a running bootloader.

If you are working with DHCOM AM35x or DHCOM i.MX25 please have a look at DHCOM Flash Update.

Overview

The following updates and commands are supported by the mechanism:

command description
bootloader update the bootloader
script bootloader executes the provided bootloader script e.g. to customize bootloader environment variables
splash write a new *.bmp to display a bootloader splashscreen
settings DHCOM bootloader settings
copy copy a file e. g. uLinuxEnv.txt into the boot partition
linux update the linux kernel binary e. g. zImage
devicetree update the devicetree blob
rootfs write a new rootfilesystem to the target
finetuning run a provided script to do some finetuning on our installation (warning: experts only)
eeprom update the display timings stored in the display adapter EEPROM
reset reboot system after a successful update (warning: risk of a infinite update loop)

How does it work?

  • The update mechanism has to be started with the bootloader command "update".
  • The updates "bootloader", "script", and "eeprom" are processed by the bootloader. They can be started directly with "update <command> <imagefile>" for example "update bootloader u-boot_imx6dl-dhcom2_1G.imx"
  • For the remaining updates you need a "update kernel". The "update kernel" is a file which contains the linux kernel binary (zImage), a busybox rootfilesystem with shell scripts (*.cpio), and a devicetree blob (*.dtb). This implies that the update kernel has to match your board configuration like the bootloader, linux kernel, and devicetree concerning CPU Type, CPU Cores, RAM and NAND or eMMC memory.
  • To control the processing of the updates you need to provide a "DHupdate.ini" file to the update kernel.
  • For further Details see the following chapters.

Downloads

For the "update kernel" please have a look at the i.MX6 Downloads, i.MX6ULL Downloads or AM335x Downloads section.

Execution Modes

Automatic Mode

  • To use the "automatic mode" the command "update auto" has to be called within the bootloader environment variable bootcmd. The functionality does search a DHupdate.ini file on the specified storage devices e. g. update devices. The update devices must be defined at the DHCOM settings block (Please have a look at DHCOM settings). The content of the DHupdate.ini file controls which updates have to be processed and which images have to be written to the storage device (eMMC or NAND) of the DHCOM computer on module system.

Commandline Mode

  • Instruction: "update"
    The functionality tries to update the flash content via the DHupdate.ini file. In contrast to Automatically Update (which you can start with "update auto") the update mechanism is searching on every available storage device for the update files.
  • Instruction: "update <command> [filename]"
    The functionality doesn't use the DHupdate.ini file. It allows only one update and the update mechanism is searching on every available storage device for the update files. With the <command> parameter you have to specify the update type. If no [filename] is passed, the default file name will be used.
The following <command> parameters are possible from command line:
command description
bootloader update the bootloader
Note: The ENV in Flash memory is created on the first start of u-boot. If you run a bootloader update and the ENV at the new bootloader has changed, the ENV in Flash memory remains unchanged with the bootloader update. But you could delete the ENV block in flash memory before the update, then u-boot will create the new default ENV at the next start after the bootloader update.

Default file name = u-boot.imx (i.MX6) / u-boot-with-spl.imx (i.MX6 | i.MX6ULL) / u-boot.img (AM335x)

script bootloader executes the provided bootloader script e.g. to customize bootloader environment variables

default file name = script.bin

eeprom update the display timings stored in the display adapter EEPROM

default file name = eeprom.bin

reset reboot system after a successful update. A reset can only be the last item in a DHupdate.ini file.

Warning: Risk of a infinite update loop.

DHupdate.ini file

The DHupdate.ini file is a ASCII text file, which controls the update mechanism.

Syntax

The <type> parameter could be specified as follows:
<type> description
bootloader update the bootloader
script bootloader executes the provided bootloader script e.g. to customize bootloader environment variables
splash write a new *.bmp to display a bootloader splashscreen
settings DHCOM bootloader settings
Note: Please have a look at DHCOM settings.
refresh Set the new display settings for the current update process
copy copy a file e. g. uLinuxEnv.txt into the boot partition
linux update the linux kernel binary e. g. zImage
devicetree update the devicetree blob
rootfs Create or replace the linux root-filesystem which is stored in the Flash. The rootfs update has to be the last item (or second to last item if you insert the reset command) in the DHupdate.ini file. For further Details: DHCOM Update: Linux Root Filesystem
finetuning run a provided script to do some finetuning on our installation (warning: experts only)
eeprom update the display timings stored in the display adapter EEPROM
reset reboot system after a successful update
Note: If you update the DHCOM settings, it is possible to use the new settings for the update progress notifications on the display, by inserting the "refresh" command to the [update] section. The bootloader loads the new settings and calls the update kernel with the new parameters.

Example

##DHCOMupdate##
[display]
800x480_progress.bmp
800x480_done.bmp
800x480_error.bmp
[led]
GPIO_E high
[update]
settings 13_DataImage_7inch_FG0700G3DSSW.bin
refresh
bootloader u-boot-nand.imx
splash DH_800x480.bmp
linux zImage
devicetree dtbs/imx6dl-dheva01.dtb
rootfs imx6_debian_rootfs.tar.bz2
[end]

Notes:

  • It is necessary to use UNIX End Of Line conversion!!!
  • The order of the bitmap-filenames in the section display tells the system when to display which bitmap.
  • If you use "refresh" command, please ensure that settings bin update is listed in DHupdate.ini file before "refresh" command.

Bootloader Handled Updates

The following updates are done by the bootloader:

  • bootloader (only in case of command line update)
  • refresh
  • eeprom
  • script

"Update Kernel" Handled Updates

The following updates are done by the update kernel:

  • bootloader (only in case of DHupdate.ini File update)
  • copy
  • linux
  • devicetree
  • rootfs
  • settings
  • splash
  • finetuning

Note: The [filename] parameter has to be defined if you use the update kernel.

Loading the "Update Kernel"

If the bootloader detects updates which have to be handled from a "update kernel" it defines the bootloader variables src_intf=usb or src_intf=mmc and src_dev_part=0:1 to specify the location of the DHupdate.ini file. Then the bootloader executes the environment variable load_update_kernel. Take care about the content of this variable for example with the update script scriptfile.bin functionality.

Example

setenv console ttymxc0,115200
setenv setupdateargs 'setenv bootargs console=${console} src_intf=${src_intf} src_dev_part=${src_dev_part} dhcom=${dhcom} \ 
${backlight} ${parallel_display} ${lvds_display0} ${lvds_display1} vt.global_cursor_default=0' setenv load_update_kernel 'load ${src_intf} ${src_dev_part} ${loadaddr} zImage_${dhcom}.update; run setupdateargs; bootz ${loadaddr}'

Update progress LED description

The LED GPIO is activated as soon as update has started. This takes roughly 6 - 8 seconds. If the update was finished without an error, the LED GPIO is deactivated. If an error occurs during the update the LED GPIO begins blinking.

LED error code:
1 LED blinking interval = DHupdate.ini File error (Wrong file content or no valid file found)
2 LED blinking interval = Necessary File for Update not found
3 LED blinking interval = Flash write or erase error
4 LED blinking interval = Wrong OS Image type (e.g. no WinCE *.gz or *.bin file)
5 LED blinking interval = Specified file not valid (e.g. linux *.env file)
6 LED blinking interval = Image file size is to large
7 LED blinking interval = Can't load update kernel / Internal ERROR

Necessary Files

The content of our update media e.g. usb flash memory device should look similar to this example here:

Flowchart of the Update Process