nono document

### nono 0.1.5 (2020/12/05)

nono は NetBSD とかで動作する OMRON LUNA-I とかのエミュレータです。 nono is OMRON LUNA-I emulator runs on NetBSD and etc.

#### はじめに Introduction

nono は NetBSD とかで動作する OMRON LUNA-I とかのエミュレータです。 LUNA88K は実験的サポートです。 nono is OMRON LUNA-I emulator runs on NetBSD and etc. LUNA88K is still experimental support.

#### ビルド方法 How to build

ビルドには以下が必要です。 NetBSD(pkgsrc) なら wxWidgets は pkgsrc/x11/wxGTK30 です (OPTIONS:gtk2 で動作確認しています)。 The followings are required for build. If you use NetBSD(pkgsrc), wxWidgets is pkgsrc/x11/wxGTK30 (Only OPTIONS:gtk2 is tested).

- make (BSD make, not GNU make)
- C/C++ compiler which supports -std=c++14.
  (For gcc, 7.4 works but 5.5 doesn't work, at least. For clang, 7.0 and 8.0 works at least.)
- wxWidgets >= 3.0
- gettext

(NetBSD 以外でのビルドはサポートしていませんが) Ubuntu 18.04 ではたぶん以下のパッケージが必要です。 You may need the following packages on Ubuntu 18.04 (though we won't support non-NetBSD platform).

  bmake build-essential gettext libbsd-dev libedit-dev libkqueue-dev libwxgtk3.0-dev zlib1g-dev

アーカイブを展開したら以下のようにビルドします。 configure には環境変数 CC、CXX でコンパイラを指定することが出来ます。 また wx-config が標準的な名前で提供されていないために見付けられない場合には 環境変数 WX_CONFIG にパスを指定することが出来ます。 Extract the archive and build as following. You can specify C/C++ compiler using environment variable CC and CXX if configure cannot find standard name suitable compiler. Also, you can specify wx-config path using environment variable WX_CONFIG if configure cannot find wx-config.

>     % ./configure
>     % make depend
>     % make
>     % su
>     # make install

2つの実行ファイルがインストールされます。 `nono` が GUI 版実行ファイル、 `nono-cli` がコマンドライン版です。 Two executables will be installed. `nono` is GUI executable and `nono-cli` is command line executable.

#### コマンドラインオプション Command Line Option

`-A file`
  ホストの `file` をロードして実行します。 `file` が相対パスの場合カレントディレクトリからのパスになります。 ファイルが gzip 圧縮されていれば自動的に展開します。 (展開後の) ファイル形式は a.out (OMAGIC) か ELF で、 実際にはブートローダとカーネル程度しか想定していません。 設定ファイルの `prom-image` とともに指定されると `-A` のほうが優先します。 Loads and executes host's `file`. If `file` is relative path, it is path from the current directory. If the file is gzip'd, it is automatically extracted. The supported file format (after extracting) is a.out (OMAGIC) or ELF. Actually, it only assumes bootloaders or kernels. If this option is specified at the same time as `prom-image` in configuration file, this option preceeds.
`-c vmpath`
  VM ディレクトリ/設定ファイルを指定します。 vmpath がディレクトリならそのディレクトリの中の nono.cfg を設定ファイルとします。 vmpath がファイルならそれを設定ファイルとします。 そしていずれの場合も 設定ファイルがあるディレクトリを VM ディレクトリとします。 -c オプションを省略すると vmpath をカレントディレクトリとします。 Specifies the VM directory/configuration file. If vmpath is a directory, make nono.cfg in that directory a configuration file. Or if vmpath is a file, make the specified file a configuration file. And in both cases, make the directory where that file is located a VM directory. If `-c` option is omitted, vmpath is considered as the current directory.
`-f`
  高速モードで起動します。 GUI なら起動後にもメニューから変更できますが、その初期値を変えるだけです。 Boot as the fast mode. You can change this mode on GUI menu after boot, and the option only changes its initial state.
`--fontsize height`
  GUI 版のみ。 全サブウインドウの起動時のフォントサイズを指定します。 `height` には 12, 16 のいずれかを指定します。デフォルトは `12` です。 起動後にメニューから変更できます。 GUI Only. Specifies the initial fontsize on all sub windows. `height` is one of 12 or 16. The default value is `12`. You can change this value on GUI menu after boot.
`-s scale`
`--scale scale`
  GUI 版のみ。 メインウィンドウの起動時のスケールを実数で指定します。 起動後にもメニューからプリセットされた倍率には変更可能ですが、 任意倍率は起動時のみ指定可能です (そのうちなんとかしたい)。 デフォルトは 1.0 です。 GUI Only. Specifies the initial main window scale in real number. You can change this scale on GUI menu after boot, but unlike this option, there are only a few preset choices (Should be improved in someday). The default value is 1.0
`--show-config`
  設定ファイルと `-V` オプションを読み込んだ結果を表示します。 Shows the result of reading configuration file and parsing `-V` options.
`-v`
  バージョンを表示します。 Shows the version.
`-V name=value`
  設定ファイルで指定した `name=configvalue` の代わりに このオプションの `name=value` を適用します。 Use this name=value instead of name=configvalue specified in configuration file.

以下開発用。For developers:

`-b hexaddr[,skipcount]`
  デバッガのブレークポイントを 16進数で指定します。
`-C`
  ログをコンソールにも出力します。 通常はログウィンドウにだけ出力されます。
`-d`
  起動時にデバッガプロンプトで停止します。
`-D`
  コンソールをデバッガとして使用します。 -d を指定しなくても起動時にプロンプトで停止します (そのうちなんとかしたい)。
`-L name1=level1[,name2=level2,...]`
  ログレベルを指定します。 カンマで区切って複数指定することも出来ます。 `-Lhelp` で name の一覧を表示します。
`-M name[,name2,...]`
  起動時に表示するモニタウィンドウを指定します。 カンマで区切って複数指定することも出来ます。 `-Mhelp` で name の一覧を表示します。

#### 設定 Configuration

VM の設定ファイルはその VM ディレクトリ内の nono.cfg (または -c で指定したファイル) です。 書式は `key = value` 形式で1行1項目ずつです。 `key` と `value` の前後の空白は取り除かれます。 また空行と "`#`" で始まる行は無視します。 知らないキーの行も無視します。 VM configuration file is nono.cfg (or the file specified by -c option) in the VM directory. Its syntax is `key = value` format, one per line. White spaces before and after `key` and `value` are ignored. And, blank lines, lines beginning with "`#`", and lines with unrecognized key are also ignored.

設定項目は次の通りです。 The configuration items are:

`vmtype = string`
  VM 種別を以下のいずれかから指定します。 省略不可です。 Specifies the VM type from the following. This field is mandatory.

  | `luna` | … LUNA-I
  | `luna88k` | … LUNA88K (experimental)

`debugger-port = integer`
  デバッガの TCP 待ち受けポート番号を指定します。 0 なら待ち受けを行いません。 デフォルトは 0 です。 Specifies the TCP port number that debugger listens. If 0, it will not listen. The default is 0.
`ethernet-hostdriver = string`
  イーサネットデバイスのホスト側ドライバを指定します。 `none`、`tap`、`bpf` が指定できます。 `none` ならホスト側とは一切通信を行いません。 `tap` か `bpf` かはホスト OS によってビルド時に決定します。 NetBSD、OpenBSD、FreeBSD、Linux なら `tap` です。 Specifies the host driver of ethernet device. `none`, `tap` and `bpf` can be specified. If `none`, it doesn't make any communication with the host. `tap` or `bpf` is determined at build time for the host OS. If the host is NetBSD, OpenBSD, FreeBSD, or Linux, it's `tap`.
`ethernet-hostdevice = string`
  イーサネットデバイスのホスト側のデバイス名を指定します。 `ethernet-hostdriver` が `tap` の場合ここには tap デバイスを(フルパスで)指定します。 Specifies the host device name of ethernet device. If `ethernet-hostdriver` is `tap`, this field specifies the full path to the tap device.

  デフォルトは `auto` で、この場合の動作はホスト OS ごとに異なります。 Linux なら "`/dev/net/tun`" を指定したのと同じです。 OpenBSD なら `/dev/tap0` から `/dev/tap9` まで 順番にオープンできるまで試します。 NetBSD (と FreeBSD) ならまず `/dev/tap` でクローニングを試み、 それが失敗すれば `/dev/tap0` から `/dev/tap9` までを 順番にオープンできるまで試します。 The default is `auto`. The behavior in this case depends on the host OS. On Linux, it's the same as `/dev/net/tun`. On OpenBSD, it will try from `/dev/tap0` to `/dev/tap9` until successful. On NetBSD (and FreeBSD), it will try cloning by `/dev/tap` first. If that fails, then try from `/dev/tap0` to `/dev/tap9` until successful.

`ethernet-macaddr = string`
  イーサネットデバイスの仮想マシン側の MAC アドレスを指定します。 `XX:XX:XX:XX:XX:XX` 形式で指定します。 `auto` なら自動的に決定します。 デフォルトは `auto` です。
`luna-dipsw1 = string`
  本体前面 DIPSW#1-1..#1-8 の内容を指定します。 "`0`" を DOWN、"`1`" を UP として、 これを8つ並べた形式で、前から順に #1..#8 に対応します。 Specifies status of the front panel DIPSW#1-1..#1-8 using 8 digit. "`0`" means DOWN and "`1`" means UP. The first character corresponds to #1 and the eighth character corresponds to #8.

  LUNA-I でのデフォルトは `11110111` です。 各スイッチの内容は以下のリンクを参照してください。 On LUNA-I, the default value is `11110111`. See the following link about DIPSW.
  → NetBSD/luna68k: Information
  LUNA88K でのデフォルトは `11111111` です。 各スイッチの内容は以下のリンクを参照してください。 On LUNA88K, the default value is `11111111`. See the following link about DIPSW.
  → OpenBSD manual pages: boot_luna88k(8)

`luna-dipsw2 = string`
  本体前面 DIPSW#2-1..#2-8 の内容を指定します。 書式は `luna-dipsw1` と同じです。 デフォルトは `11111111` です。 Specifies status of the front panel DIPSW#2-1..#2-8. The same syntax as `luna-dipsw1` is used. The default value is `11111111`.

  NetBSD/luna68k のブートローダは、 DIPSW#2 が "`11111111`" なら自動的にカーネルをロードして実行し、 どれかでも "`0`" にするとプロンプトで停止するようです。 (本当は #8 だけで制御するつもりだったんじゃないかという気がします) NetBSD/luna68k bootloader will automatically load and execute the kernel, if the DIPSW#2 is "`11111111`". Otherwise, the bootloader will enter interactive mode. (I doubt that they actually wanted to switch with only #8)

`monitor-rate = integer`
  テキスト系モニタウィンドウの更新頻度を Hz 単位で指定します。 1 から 60 までの間で指定でき、デフォルトは 20Hz です。 起動後にメニューからプリセットされた頻度には変更可能です。 Specifies refresh rate of all text monitor windows in Hz. It ranges from 1 to 60. The default is 20Hz. You can change this value on GUI menu after boot, but unlike this configuration value, there are only a few preset choices.
`mpu-clock = value`
  MPU のクロック数を MHz 単位で指定します。 デフォルトは LUNA-I なら 20MHz、LUNA88K なら 25MHz です。 Specifies the MPU clock in MHz. The default value is 20MHz on LUNA-I, or 25MHz on LUNA88K.
`prom-image = path`
  LUNA-I/LUNA88K の外部 ROM イメージファイルのパスを指定します。 path がファイル名のみなら VM ディレクトリとその親ディレクトリからこのファイル名を検索します。 path が相対パスなら VM ディレクトリからの相対パスになります (現在のディレクトリからではありません)。 空にすると内蔵 ROM を使用します。 デフォルトは空です。 Specifies the LUNA-I/LUNA88K's external ROM image file path. If the path does not have any path delimiters, the VM directory and then its parent directory will be searched. If the path is a relative path, it will be path from the VM directory, not from the current directory. If the path is empty, internal emulated ROM will be used. The default value is empty.

  実機を持っていない場合はこの値を空に (= デフォルトのままに) しておくと、 nono 内蔵のなんちゃって下位互換 ROM で起動します(現状 LUNA-I のみ)。 If you does not have the real LUNA machines, you can boot with nono's internal downward compatible emulated ROM if you set this field empty (or leave it as the default). For now, it's only for LUNA-I.

  LUNA-I 実機を持っている場合は ROM ファイルを指定することで実機 ROM で起動できます。 ROM ファイルは実機の 0x41000000-0x4101ffff (128KB) を保存したものです。 今のところ ROM は V4.22 (Thu Jul 27 11:45:42 1989) のみサポートしています。 それ以外については何も分かりません。 If you have the real LUNA-I machine, you can boot with the real ROM spcifying the ROM file path. The ROM file is extracted from 0x41000000-0x4101ffff (128KB) of the real LUNA-I machine. For now, only V4.22 (Thu Jul 27 11:45:42 1989) is supported. I have no idea about other ROMs.

  LUNA88K 実機の場合は 0x41000000-0x4103ffff (256KB) を保存したものです。 ただし現状サポートしていません。 For LUNA88K, the ROM file is extracted from 0x41000000-0x4103ffff (256KB). However, it's not supported yet.

`ram-size = integer`
  搭載する RAM サイズを MB 単位で指定します。 LUNA-I のデフォルトは 16MB です。 16MB 未満は 4MB 単位で、 16MB 以上は 255MB まで 1MB 単位で指定できます (ちなみに NetBSD/luna68k の起動には最低でも 8MB 必要です)。 LUNA88K のデフォルトは 64MB です。 64MB 未満は 16MB 単位で、 64MB 以上は暫定で 255MB まで 1MB 単位で指定できます。 Specifies the RAM size in MB. On LUNA-I, the default is 16MB. If the size is less than 16MB, you can specify in 4MB unit. If larger, you can specify up to 255MB in 1MB unit. By the way, NetBSD/luna68k needs at least 8MB to boot. On LUNA88K, the default is 64MB. If the size is less than 64MB, you can specify in 16MB unit. If larger, you can specify up to tentative 255MB in 1MB unit.
`spc0-idN-image = devtype,path`
  SCSI デバイスを指定します。N には 0 から 7 が入ります。 ID 7 は本体が使用しますので指定しないでください。 値はデバイス種別 devtype とイメージパス path を "`,`"(カンマ) で区切って並べた形式で、 今の所デバイス種別 devtype には "`hd`"(ハードディスク) のみ指定可能です。 ディスクイメージパスが相対パスなら VM ディレクトリからの相対パスになります。 Specifies SCSI device. N is 0 to 7. But don't specify ID 7 because the host uses it. The value is in a form of device type devtype and the image path path separated by "`,`"(comma). For now, only "`hd`" (hard disk) can be specified for devtype. If the path is relative path, it is from the VM directory.

  例えば、nono.cfg と同じディレクトリに置いたディスクイメージ luna.img を使う場合、 LUNA では通常 ID 6 をプライマリ HDD に割り当てるのでこんな感じになります。 For example, if you use disk image luna.img placed in the same directory as nono.cfg, since LUNA usually assigns ID 6 to the primary HDD, write as following:

  >     spc0-id6-image = hd,luna.img

`spc0-idN-seektime = integer`
  指定の SCSI HDD の平均シークタイムを msec 単位で指定します。 現在のデフォルトは `0` です (S・S・D!! S・S・D!!)。 16 程度を指定すると幾分往時に思いを馳せることが出来るかもしれませんが、 今の所あまり安定していません。 Specifies the average seek time of specified SCSI HDD in msec. Currently, the default value is `0` (This may be something like SSD :-). If you specify about 16 or so, you can feel nostalgic, but this feature is still unstable.
`spc0-idN-writeprotect = integer`
  指定の SCSI デバイスへの書き込みを無視するかどうか指定します。 `0` なら通常動作(書き込みを行う)です。 `1` なら書き込みコマンドは成功したように振る舞いますが実際には ディスクイメージに一切書き戻しません。 fsck を気にせずカーネルのデバッグとかを行いたい場合にはどうぞ。 何が起きるか意味が分からない人は指定しないでください。 デフォルトは `0` です。 Specifies whether nono ignores writing to SCSI devices. `0` means normal operation (writes to the devices). If `1` is specified, nono will not actually write back to the disk image even though the write command is succeeded. nono's SCSI devices acts as write command is successfully done but it never writes back to the actual disk image. This is useful for kernel debugging because it does not require fsck after the kernel hangs. But don't use this flag if you don't understand this paragraph. The default value is `0`.

#### 実行してみる Try it

つついさんが NetBSD/luna68k 9.0 の liveimage を用意してくださっています (いつもありがとうございます)。 Tsutsui-san has provided NetBSD/luna68k 9.0 liveimage for this (Thanks as always).

1. どこかに nono 用のディレクトリを用意し(例えば ~/nono/)、 その中に VM ディレクトリを用意します (例えば ~/nono/luna/)。 Create a directory somewhere for nono (for example ~/nono/), and create subdirectory for individual VMs in it (for example ~/nono/luna).
2. 以下のリンクからイメージファイルをダウンロードして展開し、 VM ディレクトリ ~/nono/luna/ に置きます。 Download imagefile from the following link, extract it and place it in the VM directory, ~/nono/luna.

   > http://teokurebsd.org/netbsd/liveimage/20200518-luna68k/

3. 同じく VM ディレクトリに設定ファイル nono.cfg を以下の内容で用意します。 Create a configuration file nono.cfg in the same VM directory, ~/nono/luna, with following contents:

   >     vmtype = luna
   >     spc0-id6-image = hd,liveimage-luna68k-raw-20200518.img

4. `nono -c ~/nono/luna` で起動します (VM ディレクトリに自動的に NVRAM.DAT が作られます)。 Run as `nono -c ~/nono/luna`. (NVRAM.DAT will be created automatically in the VM directory)
5. Emulated ROM Monitor が起動するので、 初回は以下のように入力すると NetBSD が起動します。 The emulated ROM Monitor will be executed. Then, only for the first time, entering the following can boot NetBSD.

   >     k
   >     [Enter]
   >     [Enter]
   >     d
   >     boot
   >     g
   >     x

   この内容は NVRAM.DAT に記録されているので次回以降は直接 NetBSD が起動します。 The information you have just entered is recorded in NVRAM, so next time it boots NetBSD automatically.

元ツイートはこちらOriginal tweet。

#### ネットワーク設定 Setup network

設定ファイル nono.cfg に以下の行を追加します。 Add the following line to configuration file, nono.cfg.

>     ethernet-hostdriver = tap

次に VM ディレクトリかその親ディレクトリに nono-ifup、nono-ifdown というスクリプトを用意します。 nono は tap(4) をオープンし、 そのデバイス名を引数にこれらのスクリプトを呼びます。 Then, prepare two scripts named nono-ifup and nono-ifdown in the VM directory or its parent directory. nono will open tap(4) and invoke these scripts with the name of the device as an argument.

例えば、NetBSD ホストで、ホストの wm0 セグメントに nono のゲスト OS を接続する場合、 For example, if you want to connect guest OS to host's wm0 segment on NetBSD,

1. デフォルトでは /dev/tap は一般ユーザからアクセスできないので、 chmod で適当にパーミッションを与えます。 番号の付いていないほうの /dev/tap だけでいいです。 By default, /dev/tap is only accessible to privileged user. You need to chmod /dev/tap (without unit number) appropriately. sysinst 等で OS をアップグレードするとパーミッションが 600 に戻るのがハマりポイントです。
2. bridge(4) インタフェースを作成し、 ホストの外側のインタフェースをブリッジに追加しておきます。 Create a bridge(4) interface, and add your physical interface to the bridge.

   >     # ifconfig bridge0 create
   >     # brconfig bridge0 add wm0

   常用するなら設定ファイルに書いておきましょう。 If you want to use this all the time, you can put configuration file into /etc.

   > /etc/ifconfig.bridge0

   >     create
   >     up
   >     !/sbin/brconfig $int add wm0

   >     # /etc/rc.d/network restart

3. 一般ユーザに戻って、 VM ディレクトリかその親ディレクトリに 次のような 2つのスクリプトを用意します。 sudo の設定は別途行ってください。 Return to non-privileged user, and create following two scripts in the VM directory or its parent directory. In addition, you need to set up sudo separately.

   > nono-ifup

   >     #!/bin/sh
   >     sudo /sbin/ifconfig $1 up
   >     sudo /sbin/brconfig bridge0 add $1

   > nono-ifdown

   >     #!/bin/sh
   >     sudo /sbin/brconfig bridge0 delete $1
   >     sudo /sbin/ifconfig $1 down

   >     % chmod +x nono-ifup nono-ifdown

4. nono を起動し、 メニューの「モニタ > ホスト > ホストネットワーク」を開いて NetDriver が None 以外 (この場合 BSD tap) になっていれば動いてるはずです。 Run nono, and open "Monitor > Host > Host Network" window from menu. It's OK if you can see "NetDriver: BSD tap" (in this case).

#### 変更履歴 Changes

See changes.html.

#### ライセンス License

See nono-license.txt.

#### 連絡先 Contact us

バグ報告などは以下にお願いします。日本語でおk。 If you find any problems, please let me know. You may write in English.
https://github.com/isaki68k/nono-issue/issues

#### パッチの提供について About contributes

パッチを提供してくださる場合は以下に同意したものとします。 If you provide a patch to nono, you must agree to the following conditions:

- 成果物が nono のライセンスに従って運用あるいは配布されること。 All your work are operated or distributed under the nono license.
- ライセンスが将来変わる可能性があること。 The license may be changed in the future.
- 著作部分に関して著作者人格権を行使しないこと。 Do not exercise your author's rights.

#### Acknowledgements

nono は以下の広告条項を含むソースコードを利用しています。 nono uses source code with the following advertising clause.

> This product includes software developed by Gordon Ross
> This product includes software developed by the University of California, Lawrence Berkeley Laboratory.

nono project