The content of this page is in
README. If you change something here make a sync with it.
Mamona FIASCO Image Creator and Combiner (MIC)
==============================================
:Author: Osvaldo Santana Neto <osvaldo.neto@openbossa.org>
:Version: 0.1
:Copyright: `Instituto Nokia de Tecnologia <http://www.indt.org>`_
.. contents::
Mamona FIASCO Image Creator and Combiner enable the Mamona users and developers
to create FIASCO images compatible with `Nokia's flasher tool
<http://tabletsdev.maemo.org/nokia_N800.php>`_.
Motivation
----------
The main idea behind the Mamona Project is to provide an open source (free)
alternative platform for mobile devices. In the first stage we will focus in
the Internet Tablet devices like Nokia 770, N800 and N810.
But some components of this devices are proprietary and cannot be distributed
under any circunstances preventing that some features of the hardware work
correctly with Mamona.
We've plans to replace these proprietary components with open source
alternatives but it demands a lot of time to be done. So, you can use MIC to
create FIASCO images that contains Mamona components (FOSS) and proprietary
components from official Nokia's ITOS software.
Requirements
------------
MIC requires the following components:
- Python 2.5 (or newer)
- MTD Tools for JFFS2 image creation
- Kernel Support for MTD devices (compiled as modules)
This software is running on Ubuntu 7.10 (Gutsy Gibbon) with the standard kernel
(2.6.22-14-generic). If you find some problem with other configuration open a
ticket on our `bugtrack system <http://dev.openbossa.org/mamona>`_.
Installation
------------
You can `download <http://dev.openbossa.org/mamona/0.2/mic/mic_0.1-2.tar.gz>`_ and install MIC
with the following command::
$ python setup.py install
Download the `Debian package <http://dev.openbossa.org/mamona/0.2/mic/mic_0.1-2_all.deb>`_ to
install it on your Debian/Ubuntu Linux distribution or the `RPM package <http://dev.openbossa.org/mamona/0.2/mic/mic-0.1-2.noarch.rpm>`_ if
you're using Fedora or other RPM based distribution.
Usage
-----
MIC needs superuser permissions to run::
# mic -C image.xml [-I input_image.bin] [-D rootfs:image_dir/]* [-W workdir/] final_image.bin
Options:
``--version``
show program's version number and exit
``-h, --help``
show this help message and exit
``-C FILE, --config=FILE``
Instructions about how contruct the final image
``-I FILE, --image=FILE``
Original FIASCO image
``-D PIECE:DIR, --dirs=PIECE:DIR``
Directory with image pieces (initfs, rootfs). You can use more than one.
``-W DIR, --workdir=DIR``
Set the work directory and leave it after the image creation.
Example::
# ./mic --config=image.xml --image=img_nokia.bin --dirs=rootfs:mamona-root img_mamona.bin
Configuration File
------------------
The configuration file is a XML file with instructions to build a FIASCO image. The basic structure of this file is::
<?xml version="1.0" encoding="UTF-8"?>
<image format="fiasco">
<header>
<... attr tags ...>
</header>
<... piece tags...>
</image>
We will use an example to illustrate how you can create a configuration file for Mamona:
1. Add the XML header and the base ``<image>`` tag. The `format="fiasco"`
define the output format of image. We are currently supporting only `fiasco`
format::
<?xml version="1.0" encoding="UTF-8"?>
<image format="fiasco">
</image>
2. Add a ``<header>`` with some attributes. FIASCO images requires two ``name``
attributes and the first one needs to be "``OSSO UART+USB``"::
<image format="fiasco">
<header>
<attr name="name" value="OSSO UART+USB" />
<attr name="name" value="1 RX-34_2007SE_4.2007.38-2_RD_MR0" />
</header>
:
3. It's time to define the "pieces" of our FIASCO image. A FIASCO image
normally contains 6 pieces as you can see at `FIASCO image structure`_. In
our example we will use pieces from a Nokia ITOS image and a directory that
contains our ``rootfs`` ('debootstraped' mamona chroot).
4. Let's define the "``kernel``" piece. The kernel format is "``file``". The
"``version``" attribute is optional but we'll define it here to show you that
is possible to use the ``<header>`` and ``<attr ...>`` tags with pieces. The
"``source``" tag define the source of file and the available options are
``dir`` (defined with ``-D`` option in command line) or ``image`` (defined
with ``-I`` option in command line)::
<piece name="kernel" format="file">
<header>
<attr name="version" value="2.6.18-200738osso1" />
</header>
<source origin="image" name="kernel" />
</piece>
5. We'll not provide a ``initfs`` root directory to use in our image so we'll
use the ``initfs`` provided by the ITOS image::
<piece name="initfs" format="file">
<header>
<attr name="version" value="0.94-17" />
</header>
<source origin="image" name="initfs" />
</piece>
6. Mamona provides a ``rootfs`` but we will need some files from ITOS image. As
you can see we are using the attribute "``format="jffs2"``" in our
"``<piece>``" tag. This option tells MIC to create a JFFS2 filesystem image
with ``mkfs.jffs2`` utility. The sources are our rootfs directory
(``-Drootfs:mamona-root``) and the directory ``/lib/dsp`` available in ITOS`s
``rootfs``::
<piece name="rootfs" format="jffs2">
<header>
<attr name="version" value="RX-34_2007SE_4.2007.38-2_RD_MR0" />
</header>
<source origin="dir" name="rootfs" />
<source origin="image" name="rootfs" sub_object="/lib/dsp" />
</piece>
7. The other components (``2nd``, ``xloader`` and ``secondary``) works the same
way of kernel piece::
<piece name="2nd" format="file">
<header>
<attr name="version" value="1.1.6-5" />
<attr name="valid" value="RX-34:1301,1302,1501,1502,1503,1504,1601,1602" />
</header>
<source origin="image" name="2nd" />
</piece>
8. The final configuration file is in ``image.xml``.
FIASCO Image Structure
----------------------
The FIASCO structure is very simple. It is basically a binary file with a small
header plus 6 pieces:
- xloader - first part of NOLO (NOkia LOader)
- secondary - second part of NOLO
- kernel - Linux Kernel
- initfs - the init filesystem
- rootfs - the root filesystem
- 2nd - ???
You can find detailed informations about FIASCO images at the `0xFFFF
<http://www.nopcode.org/0xFFFF/>`_ project web site.
Known Issues
------------
- When a jffs2 file has only one origin source the program breaks::
<piece name="rootfs" format="file">
<header>
<attr name="comment" value="RX-34_2007SE_4.2007.38-2_RD_MR0" />
</header>
<source origin="image" name="rootfs" />
</piece>
- Combiner does not add the meta data header informations into pieces
Future Developments
-------------------
- Add support to ``--verbose``
Acknowledgment
--------------
Thanks to `pancake <http://www.nopcode.org/>`_ to the useful information about the FIASCO structure.
License
-------
::
Copyright 2007, Instituto Nokia de Tecnologia (OpenBossa Lab),
and individual contributors as indicated.
Author: Osvaldo Santana Neto <osvaldo.neto@openbossa.org>
This is free software; you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as
published by the Free Software Foundation; either version 3.0 of
the License, or (at your option) any later version.
This software is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public
License along with this software; if not, write to the Free
Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
02110-1301 USA, or see the FSF site: http://www.fsf.org.
