How to use mlterm-fb on NetBSD/x86 VESA framebuffer console

how-to-use-mlterm-fb.txt

How to use mlterm-fb on NetBSD/x86 VESA framebuffer console:

Summary:

1. Boot NetBSD/x86 with VESA framebuffer console
2. Install mlterm binary packages
3. Edit /etc/ttys
4. Prepare mlterm config files
5. Start mlterm-fb


Detailed procedures:

1. Boot NetBSD/x86 with VESA framebuffer console

Enable VESA console on the bootloader prompt as following:
- press SPACE to stop countdown during bootloader menu
- choose "5" (Drop to boot prompt)
- check avaiable VESA mode by "vesa list"  command
- choose proper VESA mode by "vesa 1024x768x32" etc.
  (note 32bpp is preferred)
- type "boot" to start the default kernel

---

NetBSD/x86 ffsv2 Primary Bootstrap


>> NetBSD/x86 BIOS Boot, Revision 5.9 (from NetBSD 6.1)
>> Memory: 638/1300416 k

     1. Boot normally
     2. Boot single user
     3. Disable ACPI
     4. Disable ACPI and SMP
     5. Drop to boot prompt

Choose an option; RETURN for default; SPACE to stop countdown.
Option 1 will be chosen in 0 seconds.

Option: [1]:5
type "?" or "help" for help.
> vesa list
Modes:
0x105=1024x768x8  0x117=1024x768x16  0x118=1024x768x32  0x112=640x480x32
0x114=800x600x16  0x115=800x600x32  0x101=640x480x8  0x103=800x600x8
0x111=640x480x16
> vesa 1024x768x32
> boot
11254956/

[starting a kenrel with 1024x768 console instead of normal VGA]

---

Note 1: some old (pre ACPI) or too newer (some Ivy Bridge integrated video)
        machines might not work with VESA framebuffer settings.
Note 2: VMware and VirtualBox (with VT-x or AMD-V) also work fine with
        VESA framebufrer settings.


2. Install mlterm binary packages

(Assuming users and network environment are already configured)
Login as a user, su root, and add packages as following:

---
$ su
Password:
# PKG_PATH=http://ftp.NetBSD.org/pub/pkgsrc/packages/NetBSD/`uname -p`/6.0/All \
 pkg_add http://ftp.NetBSD.org/pub/NetBSD/misc/tsutsui/mlterm/`uname -p`/6.0.2_2013Q1/mlterm
pkg_add: Warning: package `mlterm-3.2.0nb1' was built for a platform:
pkg_add: NetBSD/i386 6.0.2 (pkg) vs. NetBSD/i386 6.1 (this host)
pkg_add: Warning: package `ibus-1.4.2nb5' was built for a platform:
pkg_add: NetBSD/i386 6.0 (pkg) vs. NetBSD/i386 6.1 (this host)
 :
 [~42 packages will be installed with "6.0.x vs. 6.1" warnings
  but it's harmless to use 6.0.x binaries on 6.1]
---

If you want to use ibus for Japanese (and other) input method,
you also have to install necessary ibus client binaries.
In pkgsrc-2013Q1, mozc (ibus-mozc and mozc-server) is useful enough
for Japanese input method.

---
# PKG_PATH=http://ftp.NetBSD.org/pub/pkgsrc/packages/NetBSD/`uname -p`/6.0/All \
 pkg_add ibus-mozc mozc-server
 :
---


3. Edit /etc/ttys

You have to edit ttys(5) file to enable getty(8) on /dev/ttyE0
instead of the default /dev/console, to allow mlterm(1) open /dev/ttyE0.

Open /etc/ttys with vi(1) or other editors,
change "on" at "console" line to "off", and
also change "off" at "ttyE0" line to "on".

Before:
---
# name  getty                           type    status          comments
#
console	"/usr/libexec/getty Pc"		vt100	on secure
constty	"/usr/libexec/getty Pc"		vt100	off secure
ttyE0	"/usr/libexec/getty Pc"		wsvt25	off secure
ttyE1	"/usr/libexec/getty Pc"		wsvt25	on secure
 :
---

After:
---
# name  getty                           type    status          comments
#
console	"/usr/libexec/getty Pc"		vt100	off secure
constty	"/usr/libexec/getty Pc"		vt100	off secure
ttyE0	"/usr/libexec/getty Pc"		wsvt25	on secure
ttyE1	"/usr/libexec/getty Pc"		wsvt25	on secure
 :
---

Note: if you will also use a serial console on the same machine,
      you might have to enable getty at tty00 line after these change.

To enable getty per updated ttys(5) you have to send SIGHUP to init(8):
---
# kill -HUP 1
---
Then you will be automatically logged out and
a new login prompt at "(ttyE0)" will appear.


4. Prepare mlterm config files

Login and create ~/.mlterm directory for your favorite user,
prepare (or copy) mlterm config files, at least main, font, and font-fb:
---
$ mkdir ~/.mlterm
$ cd ~/.mlterm
$ ftp http://ftp.NetBSD.org/pub/NetBSD/misc/tsutsui/mlterm/dot.mlterm/main
 :
$ ftp http://ftp.NetBSD.org/pub/NetBSD/misc/tsutsui/mlterm/dot.mlterm/font
 :
$ ftp http://ftp.NetBSD.org/pub/NetBSD/misc/tsutsui/mlterm/dot.mlterm/font-fb
 :
---
Then edit each config file per mlterm(1) man pages if necessary,
especially for favorite fonts for your local language.

The above sample font and font-fb files only contain
settings for Japanese and limited UTF-8 fonts.
You might have to add misc pcf font packages for your encodings.


5. Start mlterm-fb

Just start mlterm-fb with proper LANG settings:
---
$ export LANG=ja_JP.UTF-8
$ mlterm-fb
---
then you'll get a multi-lingual terminal on the framebuffer console.
If you have any troubles, you can check messages in ~/.mlterm/msg.log.

If you want to use ibus-mozc as an input method,
you have to start ibus daemons before mlterm-fb:
---
$ ibus-daemon -d
$ /usr/pkg/libexec/ibus-engine-mozc &
$
(process:NNN): IBUS-WARNING **: DISPLAY is empty! We use default DISPLAY (:0.0)

 [note: this ibus warning is harmless since we are on the console]
---
and specify "-M" (input method option) to mlterm-fb:
---
$ mlterm-fb -M ibus
---
By the default, [CTRL]+[SPACE] will invoke the input method.

For other options and configurations, please check mlterm(1) man pages.


6. Misc 

- mlterm-3.2.0 is the first version that supports NetBSD wsfb framebuffer.
  It might still have some bugs.  Any reports are appreciated.

- mlterm-fb requires pcf font files in the xfont.tgz set so you have to
  choose "Full installation" (or explicitly choose xfont manually)
  during sysinst(8) installation.
  
- to use proper UTF-8 pcf fonts, pkgsrc/fonts/efont-unicode might be useful.

- mlterm-fb will work on all ports that support wsdisplay framebuffers.
  Currently NetBSD/dreamcast (16bpp) and NetBSD/luna68k (1bpp) are
  confirmed working (though no pre-compiled bianries yet).

- You can add a prefer vesa mode command (like "vesa 1024x768x32" etc.)
  into the default bootloader menu by editing /boot.cfg like:
---
menu=Boot normally:rndseed /var/db/entropy-file;vesa 1024x768x32;boot netbsd
---

- The above mlterm binaries are built with "ibus mlterm-fb" options,
  but the default pkgsrc/x11/mlterm/options.mk doesn't enable "ibus".
  (note it also has "uim" option)

- On some ports (like dreamcast) getty for ttyE0 in ttys(5) is
  enabled by default.