このブログ記事が廃れたです。BSP 5用のご参考ください。

本マニュアルについて

本マニュアルはトラデックスのCPUモジュールにOSイメージを書き込むために使用するTEZI(Toradex Easy Installer)の使用方法について記述しています。

本マニュアルに記載されていないTEZIに関する情報も多々あります。詳しくはToradexのWEBサイトをご参照ください。

参考：

• https://developer.toradex.com/software/toradex-easy-installer#os-and-demo-images
  
  

本マニュアルのPDFダウンロード

１．実行環境

２．注意点

TEZIについて

TEZI(Toradex Easy Installer)はToradexのSOMの内部ROMにOSイメージを書き込むためのツールです。TEZIはLinux + アプリケーションで出来ています。SOM上で動作するものですのでパソコンなどがなくてもモジュール単体で書き込むことが可能です。SDやUSBメモリなどに格納したOSイメージや任意のサーバーからダウンロードしたものを書き込むこともできます。

TEZIが起動するとGUIが立ち上がり数クリックするだけで書き込みできるため誰でも利用することができます。設定次第では電源を入れるだけで書き込みを自動で行うことも可能です。
SOMは出荷時にTEZIが書き込まれます。そのため量産工程で出荷時にインストールされているTEZIを利用して最終製品用のOSイメージを書き込みを行うこともできます。

TEZIの起動

TEZIを起動するには３つの方法があります。

１．TEZIがインストールされているモジュールを起動する。

２．リカバリーモードで起動。

３．Distro Bootで起動

TEZIとOSイメージの入手

OSを書き込むにはTEZIとOSイメージ(TEZIフォーマット)が必要です。

• TEZIの入手

• OSイメージの入手

OSイメージをToradexのサーバーから書き込む場合はダウンロード不要です。書き込み時に自動でダウンロードされます。自作カスタムOSを書き込む場合は作成したOSイメージを使用してください。

リカバリーモードでTEZIを使用する方法

OSイメージ解凍後をFAT32フォーマットのSDカードやUSBメモリに格納してください。
ルートディレクトリに任意の名前でディレクトリを作成してその中に格納してください。ディレクトリを分けて複数のOSイメージを格納することもできます。例えばSDカードがFドライブであれば F:¥v286、F:¥v304配下など。
ToradexのサーバーからOSイメージを書き込む場合はSDカードは準備不要です。

ハードウェアの準備

以下を行います。

リカバリーモードで起動

Recovery Modeボタン(SW9)を押しながら電源ボタン(SW7)を押してください。
電源ボタンを離した後少しおいてRecovery Modeボタンを離してください。リカバリーモードで起動します。

Colibri-i.MX7以外のモジュールのリカバリーモードへの遷移方法は下記をご参照ください。
https://developer.toradex.com/knowledge-base/imx-recovery-mode#Enter_Recovery_Mode

リカバリーモードで起動するとブートローダーが動作しないためteratermなどに起動ログが出力されません。
リカバリモードに入ったかどうかを確認する場合はWindows PCのデバイスマネージャを見ます。
下記のようなベンダーID,プロダクトIDのHID準拠デバイスが追加されています。

VMWAREが起動している場合が下記のようなアイコンが増えるのでそれで確認することも可能です。

リカバリーモードで起動したらTEZIを起動します。ダウンロードしたTEZIの中にあるrecovery-windows.batを実行します。
下記のようなログが出るとTEZIの起動成功です。

ディスプレイに下記のような画面が表示されます。SDカードに入れたOSイメージがリストされています。
複数入れている場合は複数表示されます。

Ethernetでアップデートする場合は下記のようにいくつかの項目がリストされます。
この項目はサーバーへ接続する時期により内容が変わります。

リストされている項目をダブルクリックすると下記のような確認がでてきます。Yesをクリックするとインストールが始まります。

インストールが終了すると下記のような選択が表示されます。Rebootをクリックして書き込んだOSが起動するかどうかを確認します。

DistroBootでTEZIを使用する方法

Colibri-iMX7のLinux BSP3.0.4では不具合によりdistrobootが動きません。ほかのモジュールやBSPのバージョンなどでは動作します。

不具合を修正するパッチを適用してU-Bootをbitbakeし直すことでDistobootを使用することができます。

パッチをOpen Embeddedの該当ディレクトリにダウンロード

[ubuntu]$ wget -O /work/oe-core/layers/meta-toradex-nxp/recipes-bsp/u-boot/files/colibri-imx7/0001-FIT.patch "https://git.to
radex.com/cgit/u-boot-toradex.git/patch/?id=b90d461f8277f03a498644d1252a061d245633ed

bbappendにパッチ追加

[ubuntu]$ gedit /work/oe-core/layers/meta-toradex-nxp/recipes-bsp/u-boot/u-boot-toradex_2019.07.bbappend

内容

SRC_URI_append_mx7 = " file://0001-FIT.patch"

bitbake

[ubuntu]$ bitbake -c cleansstate virtual/bootloader && bitbake -c cleansstate console-tdx-image && bitbake console-tdx-image

できたOSイメージを書き込んでください。

TEZIを解凍してFAT32フォーマットのSDカードやUSBメモリのルートディレクトリに格納してください。
OSイメージ(TEZIフォーマット)も同様に解凍してリカバーモード時同様に任意のディレクトリに格納してください。
ToradexのサーバーからOSイメージを書き込む場合はOSイメージの準備は不要です。

TEZIとOSイメージは各々を別のリムーバルメディに格納することもできます。

ハードウェアの準備

以下を行います。

シリアル通信ソフトの準備

モジュールとシリアル通信を行います。本マニュアルではTeraTermを使います。
TeraTermを下記、設定でCOMポートを開きます。COMポート番号は任意です。

ブートローダーの起動

電源ボタン(SW7)を押し電源ONすると下記のように「Hit any key to stop autoboot:」と出力されます。
この時に何かしらのキーを入力するとブートローダー(U-Boot)で止まりますが入力しないとU-BootがLinuxを起動させます。(書き込まれている場合) 今回はブートローダーの機能を使ってDistroBootをするため何かしらのキーを入力しブートローダーで止めます。

run distro_bootcmdと入力するとdistroboot機能でSDカード内に格納されたTEZIが起動します。
あとはリカバリーモード時と同様でOSイメージの書き込みを行ってください。

自動インストール機能

OSイメージの中にimage.jsonというファイルがあります。この中にautoinstallという設定があります。この設定をtrueに変更すると自動でインストールするようになります。TEZIが起動した後リムーバルメディアをスキャンしてautoinstallがtrueがあればそのままインストールされます。この設定を使用すると量産工程などでGUIなどを操作することなく電源ONからインストールまでが自動で行われます。複数OSイメージがある場合はどれがインストールされるかは保証されていないためひとつだけtrueに設定してください。

TEZIで扱うテキストファイルはgeditで編集することをお勧めします。改行コードは¥nで処理されます。¥rが含まれると誤動作します。

TEZIの自動アップデート機能

OSイメージのBSPのバージョンが上がると古いTEZIでは書き込めなくなるケースがあります。(config_formatの設定に依存します。)Toradexのモジュールを購入したときにインストールされているTEZIのバージョンでは書き込めないケースがあります。この問題を解決するためにTEZIの自動アップデート機能があります。TEZIのimage.jsonにはisinstallerという設定がありtrueになっています。(Colibri-iMX7にはROMがNANDタイプとMMCタイプがあり、それぞれimage-rawnand.jsonとimage-mmc.jsonに分かれています。該当するタイプの方をimage.jsonに書き換えてください。) isinstallerがtrueかつautoinstallがtrueの場合、OSイメージよりも優先してTEZIの書き込みが行われます。実行中のTEZIのバージョン(versionの設定)と比較してリムーバルメディアにあるTEZIのバージョンが新しければ最初にTEZIをインストールして再起動が行われます。

再起動後は新しいTEZIが立ち上がりバージョンが同じになるため再度TEZIがインストールされることはありません。次にOSイメージのインストールが行われます。

U-Boot環境変数設定ファイル

image.jsonのu_boot_envに設定されたファイル(デフォルトはuEnv.txt)にU-Bootの環境変数の設定をします。U-Bootのヘッダーを参照して出力されるためU-Bootのソースコードを修正してもそのまま使用できます。U-Bootのソースコードに設定された値はenv defaultで初期化した時に設定される値です。個別で設定を追加したい場合はこのファイルに追加するだけで設定されます。フラッシュ上に有効なU-Boot環境変数がすでにある場合、新しい変数は追加され、既存の変数は上書きされ、空の変数は削除され、他の変数は変更されません。

スクリプト実行機能

prepare_script、wrapup_script、error_scriptにシェルファイルを設定することでそれぞれインストール前、インストール後、エラー発生時に自動でスクリプトを実行することが可能です。このシェルのパラメータは$1,$2,$3,$4にそれぞれプロダクトID、ボードリビジョン、シリアルナンバー、イメージのフォルダーが入っています。
例えば下記のような記述をするとOSイメージインストール後SDカードにログを出力して再起動します。TEZIはリムーバルメディアを読み込み専用でマウントします。そのままではログの保存ができないため一度、書き込み可能でマウントし直して最後に読み込み専用に戻しています。

TEZIが内部でどのようなことをしているかは/var/volatile/tezi.logにログが出力されています。
下記シェルではtezi.logも保存しています。

書き込み時間の短縮

書き込み時間はOSイメージの大きさに依存します。できるだけOSイメージから不要な機能を削除することでOSイメージのサイズを小さくすることで書き込み時間を短くすることができます。

OSイメージを出力するとrootfsやbootfsはLZMA2アルゴリズム（xzファイル）で出力されます。SDカードやUSBメモリなど高速に読み込みできるところにある場合、読み込速度に対して解凍の方が時間がかかるため遅くなります。(インターネット越しでダウンロードする場合は解凍時間に比べてダウンロード速度のほうが遅いため圧縮は効果的です。) tar.xzを解凍してtarにした状態でインストールすると大幅に早くなります。この場合image.jsonのファイル名をtar.xzからtarに修正し てください。xzの解凍は下記のコマンドで行います。

xz -d Console-Image-colibri-imx7.tar.xz

ディスプレイの設定変更

TEZIはオリジナルのソースコードは入手できませんが多少のカスタムは可能です。使用するディスプレイに合わせて設定変更を行いたい場合はデバイスツリーを変更することで対応することができます。
カスタムするためにTEZIをUbuntuに持っていきます。本マニュアルでは/work/tezi配下をワーキングディレクトリとします。 /work/tezi/orgにオリジナルのTEZIを格納します。

下記コマンドでu-boot-toolsをインストールします。

sudo apt-get install -y u-boot-tools

出力ディレクトリ作成

mkdir -p /work/tezi/out
cd /work/tezi/out

TEZIはitb形式でできています。itb形式のファイルにはカーネルとデバスツリーとファイルシステムが含まれます。

下記コマンドでtezi.itbの中身を情報を表示することができます。

dumpimage -l /work/tezi/org/tezi.itb

dumpimageで表示した内容からimage0-4までありそれぞれ

とわかります。その下にConfigurationが0-2までありデフォルトはimx7d-colibri-eval-v3.dtbとなっています。

下記のコマンドでimage0をzImageというファイルで出力することができます。

dumpimage /work/tezi/org/tezi.itb -T flat_dt -p 0 -o zImage

同様に下記コマンドでimage1のDeviceTreeとimage4のFilesystemを取り出します。

dumpimage /work/tezi/org/tezi.itb -T flat_dt -p 1 -o imx7d-colibri-eval-v3.dtb
dumpimage /work/tezi/org/tezi.itb -T flat_dt -p 4 -o ramdisk

デバイツリーは使用するモジュールに合わせて取り出すものを変えてください。

取り出したデバイスツリーはimx7d-colibri-eval-v3.dtbを下記コマンドでdtsに変換して修正します。

sudo dtc -I dtb -O dts -o ./imx7d-colibri-eval-v3.dts ./imx7d-colibri-eval-v3.dtb
sudo gedit ./imx7d-colibri-eval-v3.dts

TEZIのデバイスツリーはBSP3.0.4のものと大きく異なりますのでご注意ください。
ディスプレイの設定を変更するにはpanel-dpiの中にあるpanel-timingを変更します。

panel-dpi {
		compatible = "panel-dpi";
		backlight = <0x65>;
		power-supply = <0x39>;
		width-mm = <0x73>;
		height-mm = <0x56>;
		data-mapping = "bgr666";
	
		panel-timing {
			clock-frequency = <0x18023d8>;
			hactive = <0x280>;
			vactive = <0x1e0>;
			hsync-len = <0x60>;
			hfront-porch = <0x10>;
			hback-porch = <0x30>;
			vsync-len = <0x2>;
			vfront-porch = <0xa>;
			vback-porch = <0x21>;
		};

EDT 7.0を使用する場合下記の設定になります。修正後ファイルを保存します。

panel-dpi {
		compatible = "panel-dpi";
		backlight = <0x65>;
		power-supply = <0x39>;
		width-mm = <0x73>;
		height-mm = <0x56>;
		data-mapping = "bgr666";
		panel-timing {
			clock-frequency = <0x1fb81e0>;
			hactive = <0x320>;
			vactive = <0x1e0>;
			hback-porch = <0xd8>;
			hfront-porch = <0x28>;
			vback-porch = <0x23>;
			vfront-porch = <0xa>;
			hsync-len = <0x80>;
			vsync-len = <0x2>;
			de-active = <0x1>;
			hsync-active = <0x0>;
			vsync-active = <0x0>;
			pixelclk-active = <0x0>;
		};

dtsを再度dtbに戻します。

sudo dtc -I dts -O dtb -o ./imx7d-colibri-eval-v3.dtb ./imx7d-colibri-eval-v3.dts

最後にkernelとDevice TreeとFilesystemを結合してitbファイルに戻します。itbにするにはitsファイルという定義ファイルが必要です。下記にサンプルを記述します。

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - /dts-v1/;

/ {

	description = "U-Boot fitImage for Toradex Easy Installer";
	#address-cells = <1>;
	
	images {
		kernel@1 {
			description = "Linux Kernel";
			data = /incbin/("./zImage");
			type = "kernel";
			arch = "arm";
			os = "linux";
			compression = "none";
			load = ;;
			entry = ;;
			hash@1 {
				algo = "sha1";
			};
		};

	fdt@imx7d-colibri-eval-v3.dtb {
		description = "Flattened Device Tree blob";
		data = /incbin/("./imx7d-colibri-eval-v3.dtb");
		type = "flat_dt";
		arch = "arm";
		compression = "none";
		hash@1 {
			algo = "sha1";
		};
	};
	ramdisk@1 {
		description = "tezi-initramfs";
		data = /incbin/("./ramdisk");
		type = "ramdisk";
		arch = "arm";
		os = "linux";
		compression = "none";
		hash@1 {
			algo = "sha1";
		};
	};
};

	configurations {
		default = "config@imx7d-colibri-eval-v3.dtb";
		config@imx7d-colibri-eval-v3.dtb {
			description = "1 Linux kernel, FDT blob, ramdisk";
			kernel = "kernel@1";
			fdt = "fdt@imx7d-colibri-eval-v3.dtb";
			ramdisk = "ramdisk@1";
			hash@1 {
				algo = "sha1";
			};
		};
	};
};

カーネルの設定にあるの部分はdumpimage -l tezi.itbで表示された内容を記述します。
下記の場合

load = <0x81000000>;
entry = <0x81000000>;

になります。

itsファイルができたらitbファイルを下記コマンドで作成します。

mkimage -f tezi.its tezi.itb

作成したtezi.itbで置き換えて起動すると解像度が変更されているのが確認できます。

ディスプレイの設定変更

OSイメージのファイル一式の中にmarketing.tarがあります。このファイルはインストール中の背景画像が入っています。
この中のファイルを変更することでインストール中の背景画像を変更することができます。

下記コマンドで解凍します。

tar xf marketing.tar

slides_vgaというディレクトリに下記が入っています。これらの画像が順番に表示されていきます。

Embedded-Linux-Splash-Screen_V3_01.png
Embedded-Linux-Splash-Screen_V3_02.png
Embedded-Linux-Splash-Screen_V3_03.png
Embedded-Linux-Splash-Screen_V3_04.png
Embedded-Linux-Splash-Screen_V3_05.png

使用したい画像をpng形式で格納してください。

再度アーカイブ化してオリジナルに上書きしてください。

tar cf ./marketing.tar ./slides_vga/

インストール中の背景が変わっていることが確認できます。

Linux起動中からTEZIの起動

下記のコマンドでLinux起動中からU-Bootでコマンドを実行せずにTEZIを実行することができます。

fw_setenv bootcmd "run distro_bootcmd"

reboot

fw_setenvはU-Bootの設定領域を書き換えるコマンドです。参照するにはfw_printenvを使います。

上記はfw_setenvコマンドでU-Bootのbootcmdを"run distro_bootcmd"に書き換えています。
bootcmdはU-Bootが起動したときに実行するスクリプトです。通常は内部ROMから起動するスクリプトになっていますがこれを Distro Bootに書き換えています。次にリブートしたときにはDistro Bootが行われて、SDなどにTEZIがあればTEZIが起動されます。
TEZI起動後にアップデートを行えばbootcmdは元に戻りアップデート後には内部ROMから起動します。
TEZIのオートインストール機能とインストール後のシェルでrebootを行えば全自動でアップデートが行われたあとリブートします。

このコマンドを利用することでアプリケーションにも容易にOSアップデート機能を搭載することができます。
OSアップデートを行うと内部ROMのデータは消えてしまいます。ユーザーデータを保持したい場合はSDカードに一度退避してアップデート後に戻すことで保持できます。

Leave a comment