unyaffs
=======

Overview
--------

  Unyaffs is a program to extract files from a YAFFS2 file system image.
  Currently it can only extract images created by mkyaffs2image.

  Unyaffs is based on work of the YAFFS project, see http://www.yaffs.net/

  The original implementation was done by Kai Wei <kai.wei.cn@gmail.com>,
  it is available at http://code.google.com/p/unyaffs/

  As the project was inactive, Bernhard Ehlers <be@bernhard-ehlers.de>
  started a fork at https://github.com/ehlers/unyaffs


License
-------

  This program is free software; you can redistribute it and/or modify
  it under the terms of the GNU General Public License version 2 as
  published by the Free Software Foundation.

  The full license text is available in the file gpl-2.0.txt.


Requirements
------------

  Unyaffs should run on most unix-like operating systems.
  A C compiler environment and make is neccessary to compile it.


Compiling
---------

  type "make"


Usage
-----

  unyaffs extracts all the files from a YAFFS2 file system image.

  unyaffs [-l <layout>] [-t] [-v] [-V] <image_file_name> [<base dir>]
      -l <layout>      set flash memory layout
          layout=0: detect chunk and spare size (default)
          layout=1:  2K chunk,  64 byte spare size
          layout=2:  4K chunk, 128 byte spare size
          layout=3:  8K chunk, 256 byte spare size
          layout=4: 16K chunk, 512 byte spare size
      -t               list image contents
      -v               verbose output
      -V               print version

  In most cases the flash memory layout is detected automatically.
  If the detection doesn't work properly, the layout can be set with
  option -l.

  Option -t lists all the file names in the image without extracting them.
  Option -v generates a 'ls -l' like listing of the extracted files.
  When combined with -t it generates an extended file listing, nothing
  is extracted.

  The image file can be - for standard input.

  If the base directory is not given, the filea are extracted into the
  current directory. If the base dir doesn't exist, it will be created.

  unyaffs extracts all file types (regular files, directories, soft links,
  hard links and special files). The permissions and modification dates
  are restored. When run as root, the ownership is restored as well.

  Please be careful extracting images as root. It might be possible,
  that important system files get overwritten. The use of chroot
  or fakeroot can guard against these problems.

Limitations
-----------

  Block and character devices can only be restored as root. In some
  operating systems (e.g. Mac OS X) sockets can't be restored.

  The use of special files (block devices, character devices, pipes,
  sockets) is not portable across different unix flavors. E.g. device
  files created on linux will get a strange major and minor device id,
  when restored under BSD.

  When it's necessary to deal with special files, please use the same
  OS as used in the system the image is build for. In most cases that's
  linux.

Windows
-------

  The differences between the unix and windows file system are big enough
  to make a windows port of unyaffs a complicated task. But with cygwin
  (http://www.cygwin.com/) a unix compatibility layer for windows is
  available. The unmodified source compiles and runs nicely within cygwin.

  The main differences to a pure unix environment:
  - Unix functionality only within cygwin environment, native windows
    programs won't see the more advanced features.
  - Permissions and file dates/time are correctly restored
  - Owner/group are not fully restored, only user/groups available in windows
  - Hard and soft links are correctly restored
  - Device files have different ids as in linux
  - Sockets are not restored

  For analysis of a firmware image, unyaffs within cygwin is a nice tool,
  but because of the restricted user/group functionality rebuilding a
  modified image can't be recommended.