The files in this directory come from 3rdparty sources.
They do not stand under the uGFX licensing terms as they come with their own
licensing model.

No warranty for the correct functionality for this software is given by the
uGFX maintainers.
No official support for this software is provided by the uGFX maintainers.


This file contains all readme informations from: fatfs-0.13, freetype-2.6.1, petitfs-0.003, tinygl-0.4-ugfx, yaffs-2

==========================================================================================================================================
fatfs-0.13

00readme.txt:

FatFs Module Source Files R0.13


FILES

  00readme.txt   This file.
  00history.txt  Revision history.
  ff.c           FatFs module.
  ffconf.h       Configuration file of FatFs module.
  ff.h           Common include file for FatFs and application module.
  diskio.h       Common include file for FatFs and disk I/O module.
  diskio.c       An example of glue function to attach existing disk I/O module to FatFs.
  integer.h      Integer type definitions for FatFs.
  ffunicode.c    Optional Unicode utility functions.
  ffsystem.c     An example of optional O/S related functions.


  Low level disk I/O module is not included in this archive because the FatFs
  module is only a generic file system layer and it does not depend on any specific
  storage device. You need to provide a low level disk I/O module written to
  control the storage device that attached to the target system.




==========================================================================================================================================
freetype-2.6.1

readme.txt:

freetype-2.6.1 source code has not been included in this repository so that you are fully
aware of the license types and restrictions before using it with uGFX.

README:

  FreeType 2.6.1
  ==============

  Homepage: http://www.freetype.org

  FreeType is a freely available software library to render fonts.

  It  is  written  in  C,  designed to  be  small,  efficient,  highly
  customizable, and  portable while capable of  producing high-quality
  output  (glyph  images) of  most  vector  and bitmap  font  formats.

  Please   read   the  docs/CHANGES   file,   it  contains   IMPORTANT
  INFORMATION.

  Read the  files `docs/INSTALL*'  for installation  instructions; see
  the file `docs/LICENSE.TXT' for the available licenses.

  The FreeType 2 API reference is located in `docs/reference'; use the
  file   `ft2-toc.html'   as   the   top  entry   point.    Additional
  documentation is available as a separate package from our sites.  Go
  to

    http://download.savannah.gnu.org/releases/freetype/

  and download one of the following files.

    freetype-doc-2.6.1.tar.bz2
    freetype-doc-2.6.1.tar.gz
    ftdoc261.zip

  To view the documentation online, go to

    http://www.freetype.org/freetype2/documentation.html


  Mailing Lists
  =============

  The preferred way  of communication with the FreeType  team is using
  e-mail lists.


README.git:

The git  archive doesn't  contain pre-built configuration  scripts for
UNIXish platforms.  To generate them say

  sh autogen.sh

which in turn depends on the following packages:

  automake (1.10.1)
  libtool (2.2.4)
  autoconf (2.62)

The versions given  in parentheses are known to  work.  Newer versions
should work too, of course.   Note that autogen.sh also sets up proper
file permissions for the `configure' and auxiliary scripts.

The autogen.sh script  now checks the version of  above three packages
whether they match the numbers  above.  Otherwise it will complain and
suggest either upgrading or using  an environment variable to point to
a more recent version of the required tool(s).

Note that  `aclocal' is provided  by the `automake' package  on Linux,
and that `libtoolize' is called `glibtoolize' on Darwin (OS X).


For static builds which  don't use platform specific optimizations, no
configure script is necessary at all; saying

  make setup ansi
  make

should work on all platforms which have GNU make (or makepp).


Similarly, a  build with  `cmake' can  be done  directly from  the git
repository.


----------------------------------------------------------------------

Copyright 2005-2015 by
David Turner, Robert Wilhelm, and Werner Lemberg.


==========================================================================================================================================
petitfs-0.003

00readme.txt:

Petit FatFs Module Source Files R0.03                (C)ChaN, 2014


FILES

  pff.h      Common include file for Petit FatFs and application module.
  pff.c      Petit FatFs module.
  diskio.h   Common include file for Petit FatFs and disk I/O module.
  diskio.c   Skeleton of low level disk I/O module.
  integer.h  Alternative type definitions for integer variables.

  Low level disk I/O module is not included in this archive because the Petit
  FatFs module is only a generic file system layer and not depend on any
  specific storage device. You have to provide a low level disk I/O module that
  written to control your storage device.



AGREEMENTS

 Petit FatFs module is an open source software to implement FAT file system to
 small embedded systems. This is a free software and is opened for education,
 research and commercial developments under license policy of following trems.

  Copyright (C) 2014, ChaN, all right reserved.

 * The Petit FatFs module is a free software and there is NO WARRANTY.
 * No restriction on use. You can use, modify and redistribute it for
   personal, non-profit or commercial use UNDER YOUR RESPONSIBILITY.
 * Redistributions of source code must retain the above copyright notice.



REVISION HISTORY

  Jun 15, 2009  R0.01a  First release (Branched from FatFs R0.07b)

  Dec 14, 2009  R0.02   Added multiple code page support.
                        Added write funciton.
                        Changed stream read mode interface.
  Dec 07,'2010  R0.02a  Added some configuration options.
                        Fixed fails to open objects with DBCS character.

  Jun 10, 2014  R0.03   Separated out configuration options to pffconf.h.
                        Added _USE_LCC option.
                        Added _FS_FAT16 option.




==========================================================================================================================================
tinygl-0.4-ugfx

README:

TinyGL 0.4 (c) 1997-2002 Fabrice Bellard.

General Description:
--------------------

TinyGL is intended to be a very small implementation of a subset of
OpenGL* for embedded systems or games. It is a software only
implementation. Only the main OpenGL calls are implemented. All the
calls I considered not important are simply *not implemented*.

The main strength of TinyGL is that it is fast and simple because it
has not to be exactly compatible with OpenGL. In particular, the
texture mapping and the geometrical transformations are very fast.

The main features of TinyGL are:

- Header compatible with OpenGL (the headers are adapted from the very good
Mesa by Brian Paul et al.)

- Zlib-like licence for easy integration in commercial designs (read
the LICENCE file).

- Subset of GLX for easy testing with X Window. 

- GLX like API (NGLX) to use it with NanoX in MicroWindows/NanoX.

- Subset of BGLView under BeOS.

- OpenGL like lightening.

- Complete OpenGL selection mode handling for object picking.

- 16 bit Z buffer. 16/24/32 bit RGB rendering. High speed dithering to
paletted 8 bits if needed. High speed conversion to 24 bit packed
pixel or 32 bit RGBA if needed.

- Fast Gouraud shadding optimized for 16 bit RGB.

- Fast texture mapping capabilities, with perspective correction and
texture objects.

- 32 bit float only arithmetic.

- Very small: compiled code size of about 40 kB on x86. The file
  src/zfeatures.h can be used to remove some unused features from
  TinyGL.

- C sources for GCC on 32/64 bit architectures. It has been tested
succesfully on x86-Linux and sparc-Solaris.

Examples:
---------

I took three simple examples from the Mesa package to test the main
functions of TinyGL. You can link them to either TinyGL, Mesa or any
other OpenGL/GLX implementation. You can also compile them with
Microwindows.

- texobj illustrates the use of texture objects. Its shows the speed
of TinyGL in this case.

- glutmech comes from the GLUT packages. It is much bigger and slower
because it uses the lightening. I have just included some GLU
functions and suppressed the GLUT related code to make it work. It
shows the display list handling of TinyGL in particular. You can look
at the source code to learn the keys to move the robot. The key 't'
toggles between shaded rendering and wire frame.

- You can download and compile the VReng project to see that TinyGL
has been successfully used in a big project
(http://www-inf.enst.fr/vreng).

Architecture:
-------------

TinyGL is made up four main modules:

- Mathematical routines (zmath).

- OpenGL-like emulation (zgl).

- Z buffer and rasterisation (zbuffer).

- GLX interface (zglx).

To use TinyGL in an embedded system, you should look at the GLX layer
and modify it to suit your need. Adding a more user friendly
developper layer (as in Mesa) may be useful.

Notes - limitations:
--------------------

- See the file 'LIMITATIONS' to see the current functions supported by the API.

- The multithreading could be easily implemented since no global state
is maintainted. The library gets the current context with a function
which can be modified.

- The lightening is not very fast. I supposed that in most games the
lightening is computed by the 3D engine.

- Some changes are needed for 64 bit pointers for the handling of
arrays of float with the GLParam union.

- List sharing is partialy supported in the source, but not by the
current TinyGLX implementation (is it really useful ?).

- No user clipping planes are supported.

- No color index mode (no longer useful !)

- The mipmapping is not implemented.

- The perspecture correction in the mapping code does not use W but
1/Z. In any 'normal scene' it should work.

- The resizing of the viewport in TinyGLX ensures that the width and
the height are multiples of 4. This is not optimal because some pixels
of the window may not be refreshed.

Why ?
-----

TinyGL was developped as a student project for a Virtual Reality
network system called VReng (see the VReng home page at
http://www-inf.enst.fr/vreng).

At that time (January 1997), my initial project was to write my own 3D
rasterizer based on some old sources I wrote. But I realized that it
would be better to use OpenGL to work on any platform. My problem was
that I wanted to use texture mapping which was (and is still) quite
slower on many software OpenGL implementation. I could have modified
Mesa to suit my needs, but I really wanted to use my old sources for
that project. 

I finally decided to use the same syntax as OpenGL but with my own
libraries, thinking that later it could ease the porting of VReng to
OpenGL.

Now VReng is at last compatible with OpenGL, and I managed to patch
TinyGL so that VReng can still work with it without any modifications.

Since TinyGL may be useful for some people, especially in the world of
embedded designs, I decided to release it 'as is', otherwise, it would
have been lost on my hard disk !

------------------------------------------------------------------------------
* OpenGL(R) is a registered trademark of Silicon Graphics, Inc.
------------------------------------------------------------------------------
Fabrice Bellard.

README.BEOS.txt:

BeOS support for TinyGL, 1998 Peder Blekken

I implemented (a limited version of) the BGLView class. There is 
no DirectWindow support, and some other funtions are missing too,
but it should work ok for most uses. Feel free to use and modify 
GLView.cpp and GLView.h in any way you desire.

You will need to take a look in Makefile to compile the library
under BeOS. For those of you not familiar with using makefiles: too bad :)

Also, you will probably need to remove  /boot/develop/headers/be/opengl 
from the BEINCLUDES environment variable. Unfortunately, this means 
editing the /boot/beos/system/boot/SetupEnvironment. It might be possible 
to just make sure the TinyGL path is before Be's  OpenGL in the include-paths 
though. But I prefer to remove /boot/develop/headers/be/opengl, since I 
often use Mesa as well. It is a better to add the OpenGL include path in your 
makefile; or BeIDE project if that is what you use.

Contact me for any reason: <pederb@sim.no>

README.uGFX.txt:

uGFX support for TinyGL, 2014 Andrew Hannam

Some files have been modified to remove references to non-embedded
functions such as fprintf, exit and assert.


==========================================================================================================================================
yaffs-2

readme.txt:

Yaffs2 source code has not been included in this repository so that you are fully
aware of the license restrictions before using it with uGFX.

Yaffs2 may be downloaded from http://www.yaffs.net 
 
This notice has been provided in collaboration with Aleph One - the owners of Yaffs2.
As such it represents an agreement of understanding between Aleph One and uGFX.
 
Yaffs2 is distributed under the GPLv2 license. Specifically that means the following…
-	You may publish the source code for your project including the yaffs2 and uGFX code
        provided that you retain the respective licenses and copyrights in the header
        of each source file.
-	You may create a binary for your own personal use.
-	You MUST NOT distribute a binary that you produce in any form (even in the ROM of
        a device) that contains both yaffs2 and uGFX code as that will put you in
        breach of either the GPL license or the uGFX license no matter what you do.
        See http://ugfx.io/licensing for more details.
-	Regardless of whether the project is commercial or non-commercial, you MUST NOT
        even compile binaries for other people since that is considered "distribution".
        You cannot even compile binaries for a friend, they must build it for themselves.
 
If you want to distribute a binary that contains both yaffs2 and uGFX (even in the
ROM of a device) then you must obtain a commercial license of yaffs2 just as you must
obtain a commercial license for uGFX if you want to use it for commercial purposes.
 
Just as uGFX provides special licenses for certain open hardware projects, Aleph One
may consider providing special licenses for various special purposes. Please contact
Aleph One at info@aleph1.co.uk for more information.

README-linux:

Welcome to YAFFS, the first file system developed specifically for NAND flash.

It is now YAFFS2 - original YAFFS (YAFFS1) only supports 512-byte page
NAND and is now deprecated. YAFFS2 supports 512b page in 'YAFFS1
compatibility' mode (CONFIG_YAFFS_YAFFS1) and 2K or larger page NAND
in YAFFS2 mode (CONFIG_YAFFS_YAFFS2).


A note on licencing
-------------------
YAFFS is available under the GPL and via alternative licensing
arrangements with Aleph One. If you're using YAFFS as a Linux kernel
file system then it will be under the GPL. For use in other situations
you should discuss licensing issues with Aleph One.


Terminology
-----------
Page -  NAND addressable unit (normally 512b or 2Kbyte size) - can
        be read, written, marked bad. Has associated OOB.
Block - Eraseable unit. 64 Pages. (128K on 2K NAND, 32K on 512b NAND)
OOB -   'spare area' of each page for ECC, bad block marked and YAFFS
        tags. 16 bytes per 512b - 64 bytes for 2K page size.
Chunk - Basic YAFFS addressable unit. Same size as Page.
Object - YAFFS Object: File, Directory, Link, Device etc.

YAFFS design
------------

YAFFS is a log-structured filesystem. It is designed particularly for
NAND (as opposed to NOR) flash, to be flash-friendly, robust due to
journalling, and to have low RAM and boot time overheads. File data is
stored in 'chunks'. Chunks are the same size as NAND pages. Each page
is marked with file id and chunk number. These marking 'tags' are
stored in the OOB (or 'spare') region of the flash. The chunk number
is determined by dividing the file position by the chunk size. Each
chunk has a number of valid bytes, which equals the page size for all
except the last chunk in a file.

File 'headers' are stored as the first page in a file, marked as a
different type to data pages. The same mechanism is used to store
directories, device files, links etc. The first page describes which
type of object it is.

YAFFS2 never re-writes a page, because the spec of NAND chips does not
allow it. (YAFFS1 used to mark a block 'deleted' in the OOB). Deletion
is managed by moving deleted objects to the special, hidden 'unlinked'
directory. These records are preserved until all the pages containing
the object have been erased (We know when this happen by keeping a
count of chunks remaining on the system for each object - when it
reaches zero the object really is gone).

When data in a file is overwritten, the relevant chunks are replaced
by writing new pages to flash containing the new data but the same
tags.

Pages are also marked with a short (2 bit) serial number that
increments each time the page at this position is incremented. The
reason for this is that if power loss/crash/other act of demonic
forces happens before the replaced page is marked as discarded, it is
possible to have two pages with the same tags. The serial number is
used to arbitrate.

A block containing only discarded pages (termed a dirty block) is an
obvious candidate for garbage collection. Otherwise valid pages can be
copied off a block thus rendering the whole block discarded and ready
for garbage collection.

In theory you don't need to hold the file structure in RAM... you
could just scan the whole flash looking for pages when you need them.
In practice though you'd want better file access times than that! The
mechanism proposed here is to have a list of __u16 page addresses
associated with each file. Since there are 2^18 pages in a 128MB NAND,
a __u16 is insufficient to uniquely identify a page but is does
identify a group of 4 pages - a small enough region to search
exhaustively. This mechanism is clearly expandable to larger NAND
devices - within reason. The RAM overhead with this approach is approx
2 bytes per page - 512kB of RAM for a whole 128MB NAND.

Boot-time scanning to build the file structure lists only requires
one pass reading NAND. If proper shutdowns happen the current RAM
summary of the filesystem status is saved to flash, called
'checkpointing'. This saves re-scanning the flash on startup, and gives
huge boot/mount time savings.

YAFFS regenerates its state by 'replaying the tape'  - i.e. by
scanning the chunks in their allocation order (i.e. block sequence ID
order), which is usually different form the media block order. Each
block is still only read once - starting from the end of the media and
working back.

YAFFS tags in YAFFS1 mode:

18-bit Object ID (2^18 files, i.e. > 260,000 files). File id 0- is not
       valid and indicates a deleted page. File od 0x3ffff is also not valid.
       Synonymous with inode.
2-bit  serial number
20-bit Chunk ID within file. Limit of 2^20 chunks/pages per file (i.e.
       > 500MB max file size). Chunk ID 0 is the file header for the file.
10-bit counter of the number of bytes used in the page.
12 bit ECC on tags

YAFFS tags in YAFFS2 mode:
  4 bytes 32-bit chunk ID
  4 bytes 32-bit object ID
  2 bytes Number of data bytes in this chunk
  4 bytes Sequence number for this block
  3 bytes ECC on tags
 12 bytes ECC on data (3 bytes per 256 bytes of data)


Page allocation and garbage collection

Pages are allocated sequentially from the currently selected block.
When all the pages in the block are filled, another clean block is
selected for allocation. At least two or three clean blocks are
reserved for garbage collection purposes. If there are insufficient
clean blocks available, then a dirty block ( ie one containing only
discarded pages) is erased to free it up as a clean block. If no dirty
blocks are available, then the dirtiest block is selected for garbage
collection.

Garbage collection is performed by copying the valid data pages into
new data pages thus rendering all the pages in this block dirty and
freeing it up for erasure. I also like the idea of selecting a block
at random some small percentage of the time - thus reducing the chance
of wear differences.

YAFFS is single-threaded. Garbage-collection is done as a parasitic
task of writing data. So each time some data is written, a bit of
pending garbage collection is done. More pages are garbage-collected
when free space is tight.


Flash writing

YAFFS only ever writes each page once, complying with the requirements
of the most restricitve NAND devices.

Wear levelling

This comes as a side-effect of the block-allocation strategy. Data is
always written on the next free block, so they are all used equally.
Blocks containing data that is written but never erased will not get
back into the free list, so wear is levelled over only blocks which
are free or become free, not blocks which never change.

Integrating YAFFS2 into a Linux 2.6.x kernel
--------------------------------------------

We'll start by assuming you have a building linux 2.6.x source tree called
linux-dir and have the
yaffs2 source code in a directory calls yaffs-dir.

yaffs-dir has a handy shell script called patch-ker.sh will painlessly do all the patching
for you.

patch-ker.sh takes three parameters:
c/l	copy or link: c will copy yaffs files into the kernel tree, l will
create symbolic links.
m/s	multi-version or single version vfs glue layer. Suggest you use m.
linux-tree

eg.

cd yaffs-dir
./patch-ker.sh  c m linux-tree

You will now have to do "make menuconfig" or similar in the Linux tree to
set up the yaffs2 configs. The configs are found under:
File systems/Miscellaneous file systems/ yaffs2


Updating YAFFS2 in a Linux 2.6.x. kernel
----------------------------------------

Updating the yaffs in a kernel tree is much the same as above. The only
difference is that you will have to first get rid of the old yaffs2 code.
Just run patch-ker.sh as above which will tell you what to do.

eg.

cd yaffs-dir
./patch-ker.sh c m linux-tree
 complains that linux-tree/fs/yaffs2 already exists
rm -rf linuux-tree/fs/yaffs2
./patch-ker.sh c m linux-tree

Now go and do the linux menuconfig again to set up any new configs.


Some helpful info
-----------------

Formatting a YAFFS device is simply done by erasing it.

Making an initial filesystem can be tricky because YAFFS uses the OOB
and thus the bytes that get written depend on the YAFFS data (tags),
and the ECC bytes and bad block markers which are dictated by the
hardware and/or the MTD subsystem. The data layout also depends on the
device page size (512b or 2K). Because YAFFS is only responsible for
some of the OOB data, generating a filesystem offline requires
detailed knowledge of what the other parts (MTD and NAND
driver/hardware) are going to do.

To make a YAFFS filesystem you have 3 options:

1) Boot the system with an empty NAND device mounted as YAFFS and copy
   stuff on.

2) Make a filesystem image offline, then boot the system and use
   MTDutils to write an image to flash.

3) Make a filesystem image offline and use some tool like a bootloader to
   write it to flash.

Option 1 avoids a lot of issues because all the parts
(YAFFS/MTD/hardware) all take care of their own bits and (if you have
put things together properly) it will 'just work'. YAFFS just needs to
know how many bytes of the OOB it can use. However sometimes it is not
practical.

Option 2 lets MTD/hardware take care of the ECC so the filesystem
image just had to know which bytes to use for YAFFS Tags.

Option 3 is hardest as the image creator needs to know exactly what
ECC bytes, endianness and algorithm to use as well as which bytes are
available to YAFFS.

mkyaffs2image creates an image suitable for option 3 for the
particular case of yaffs2 on 2K page NAND with default MTD layout.

mkyaffsimage creates an equivalent image for 512b page NAND (i.e.
yaffs1 format).

Bootloaders
-----------

A bootloader using YAFFS needs to know how MTD is laying out the OOB
so that it can skip bad blocks.

YAFFS Tracing
-------------

README-linux-patch:

To build YAFFS in the Linux kernel tree you need to run the patch-ker.sh
script from the yaffs source directory, giving your choice as to whether
you wish to copy (c) or link (l) the code and the path to your kernel
sources and whether you want to use the single-version or multi-version
code. e.g:

./patch-ker.sh c m /usr/src/linux

This will copy the yaffs files into /usr/src/linux/fs/yaffs2 and modify the Kconfig
and Makefiles in the fs directory.

./patch-ker.sh l m /usr/src/linux

This does the same as the above but makes symbolic links instead. This can
be handy if you are developing yaffs and want to interact with the yaffs git
repository, make patches, or whatever.

The single-version code is intended to track the current latest Linux kernel
and does not attempt to support older versions of the kernel.

The multi-version code supports more versions of the Linux kernel. It also
supports some optional features that might be excluded from the
single-version code.

After you've run the script, go back to your normal kernel making procedure
and configure the yaffs settings you want.

Prolems? Contact the yaffs mailing list:

http://www.aleph1.co.uk/mailman/listinfo/yaffs


