                                DINGUX

                            www.dingux.com

    Linux for the Dingoo A320 (and hopefully other JZ47xx based devices)

               Ignacio Garcia Perez <iggarpe@gmail.com>

                         (updated 2009-08-11)

-------------------
** What's this ? **
-------------------

This package contains all that is needed to run linux on an A320 from a
miniSD card using only a FAT32 partition. This means you should be able to
install it easily from Windoze.

----------------
** Quickstart **
----------------

1- Find out your LCD type: enter the A320 system setup "about" section and
press the following key sequence: up-right-down-up-right-down. A hidden
info screen will be shown and you should read somewhere either ILI9325 or
ILI9331. If you don't, this means you have a yet unknown LCD model. Please
email me and include all the text shown in the hidden info screen.

2- Install the dual-boot (not included in this package, but should be
available wherever you downloaded this package from).

3- Format your miniSD card as FAT32. Dingux now supports also partitioness
cards (i.e. no partition table, the whole device holds the filesystem
which begins at sector 0). However, partitioned cards are prefered so if
you can and know how to do it, partition your card, no matter if you are
creating only one partition.

4- Choose the right kernel image for your LCD model ("zImage-ILI9325" or
"zImage-ILI9331"), rename it as "zImage" and copy it to the root directory
of your miniSD card.

5- Copy the "rootfs" file also to the root diectory of your miniSD card.

That's it. Reset the A320 while holding pressed SELECT and you should see
dingux booting. At the end of the boot process you'll see a message being
printed about one time per second. This is normal because linux is trying
to execute your "main" application which is you must provide on your own.
It must be installed as "local/sbin/main" in your miniSD card (it will
become /usr/local/sbin/main under dingux since /usr/local is a symlink to
/boot/local and the miniSD is mounted on /boot).

-------------------------------
** Console and file transfer **
-------------------------------

In this release the USB serial gadget has been replaced by the ethernet
gadget, and a minimal network subsystem has been enabled. If your A320 is
connected to your PC through the USB cable, as soon as linux boots you
should see a new network device which will be soon assigned a network
configuration. Telnet to 10.1.0.2 to get console access (no user/password
needed) or FTP to transfer files ("root" or "anonymous" user, no password
needed).

IMPORTANT: this release fixes a kernel bug that prevented Windows
operation. You will most likely have to uninstall the driver (from the
Hardware Manager) and install it again.

------------------------
** How does it work ? **
------------------------

The zImage has an initial ram disk embedded, which contains a special init
process. This special executable mounts the first miniSD partition in
/boot, sets up a loop device pointing to /boot/rootfs, mounts the loop
device as /root, moves the /boot mount to /root/boot and switches current
system root to /root.

On startup two daemons are started: udhcpd and inetd. The first is a DHCP
server which assigns the 10.1.0.1 IP addres to your PC when it asks for
network configuration. The inetd daemon launches the telnet and FTP
servers on demmand (i.e. when you try to connect to ports 23 and 21).

As I said earlier, your A320 end of the network is assigned IP address
10.1.0.2. The gateway is set to 10.1.0.1, which means that if you try to
access the Internet your A320 will try to use your PC as a router. To
access the Internet you need to:

1- Set the DNS server(s): create a file "local/etc/resolv.conf" in your
miniSD card with the following contents (put the DNS server of your
choice):

    nameserver 194.179.1.100

2- Configure your PC to behave as a router. In linux this can be done as
follows:

    echo 1 > /proc/sys/net/ipv4/ip_forward
    iptables -t nat -A POSTROUTING -s 10.0.0.0/8 -j MASQUERADE

----------------
** Developers **
----------------

The rootfs is ROMFS and as such you can't mount it read-write and modify
it. It is quite optimized uclibc setup and I've tried to include as many
libraries as possible (including the whole SDL family except SGE).

The miniSD card is mounted at /boot and /usr/local in the root filesystem
is a symlink to /boot/local. During boot dingux will create local/ in your
miniSD and a default set of subdirectories inside (bin, sbin, lib,
etc...). Place your executables in there bearing in mind that
local/whatever in your miniSD card will become /usr/local/whatever when
dingux is running.

If you need some specific library you can either put it in "local/lib" in
your miniSD card (untested at this time) or link your program against the
static version of the library. In any case, please let me know and I'll
try to include it in the next release.

As mentioned earlier, once the system has started up it will try to
execute /usr/local/sbin/main (which is local/sbin/main in your miniSD). It
can be any kind of executable file, including a shell script, but you must
bear in mind some particularities:

1- Since it is executed by init, the environment is set to a bare minimum
default, which may not be appropriate for your application. This is what
busybox's init sets:

    HOME=/
    PATH=/sbin:/usr/sbin:/bin:/usr/bin
    SHELL=/bin/sh
    USER=root

If you need a valid, writable HOME directory, set it to /usr/local/home.
The latest included SDL no longer requires setting SDL_NOMOUSE=1.

2- If /usr/local/sbin/main is an executable using the SDL library, it
will receive a SIGHUP followed by SIGCONT when calling SDL_init. Make sure
to handle those signals or your executable will silently die.

Explanation (thanks Rookie1): FB_CloseKeyboard() of SDL_fbevents.c (called
by SDL_init) does an ioctl(tty0_fd, TIOCNOTTY, 0) to detach the process
from its terminal. As the process is the session leader, SIGHUP and
SIGCONT are sent to it.

3- If you are using a shell script as /usr/local/sbin/main to do some
initialization and then execute a menu application, use the exec shell
script command. This way, the shell script gets replaced in memory by the
menu application, while otherwise would just sit there waiting for the
menu application to finish and consuming precious memory.

