emufat 0.9
==========

HELP!
---------------

I need help translating the following text
to English.

Основные функции
----------------

  - Генерация правил для эмуляции FAT32
  - Генерация стабов для проигрывания скомпилированных правил
  - Автоматические тесты

Принцип работы
--------------

Для описания файловой системы в виде EDSL

	helloFile = const $ BS8.pack "HELLO WORLD!!"

	fatSample2 = filesystem $ do
	  file "file0" (16384) helloFile 
	  dir "A" $ do
		file "file1" (megs 100) helloFile 
		dir "C" $ do
		  file "file3" (megs 100) helloFile 
		  file "file4" (megs 100) helloFile 
		  file "file5" (megs 100) helloFile 
		  dir "E" $ emptyDir 


генерируется набор правил типа RANGE a b и REQ a. Правила на попадание сектора
в диапазон и сравнение с заданным сектором соответственно. Данные правила 
компилируются в псевдо-форт и группируются в виде бинарного дерева сравнений с 
высотой ~ Log N относительно количества проверок. 

Каждому правилу поставлен в соответствии некоторый форт-код, исполнение которого
приводит к генерации содержимого сектора.

Для динамического контента (файлов) предусмотрена возможность вызова коллбеков.
Каждый коллбек получает на вход своё "замыкание" (void* указатель на контекст,
инициализируется пользователем, может быть 0) и буфер после отработки правила
для данного сектора. Предполагается, что буфер будет содержать, например,
сишную структуру с идентификатором файла и URL потока, но это на усмотрение.

Предполагается, что коллбек по содержимому буфера определяет, какие данные
в него нужно поместить, и перезаписывает буфер этими данными.

Для любознательных. Правило примерно такого вида (содержимое файла выше):

    RANGE 2122 821353 [SEQ [48 45],
                       RLE 2 76,
                       SEQ [4F 20 57 4F 52 4C 44],
                       RLE 2 33,
                       CALLBACK 0]

будет скомпилировано примерно в следующий код:

    L215:
        DUP
        CONST 2122
        JGQ L220
        DUP
        CRNG 00000843 00000849
        JZ L235
        RLE512 00
        EXIT
    L220:
        DUP
        CRNG 0000084A 000C8869 ;; проверяем на попадание в диапазон
        JZ L223  ;; если не попали --- то в сад
        LOADS2   ;; иначе пишем в выходной буфер строку 'HELLO WORLD!!'
        BYTE 48
        BYTE 45
        RLE2 4C
        LOADS7
        BYTE 4F
        BYTE 20
        BYTE 57
        BYTE 4F
        BYTE 52
        BYTE 4C
        BYTE 44
        RLE2 21
        CALLN 00 ;; и вызываем коллбэк
        EXIT

Компилятор пытается оптимизировать код, например сокращать цепочки JMP
и частично выносить повторяющийся код в функции (см. CALL/RET).

См. FatGen, TestVM и cbits/teststubs.c для подробностей.

Виртуальная машина и прочие стабы для проигрывания правил генерируются 
автоматически (FatGen).

API содержится в файле 	FatGenAPI, для примеров использования смотреть 
FatGen.hs

Известные проблемы и ограничения
--------------------------------

  - Длинные имена файлов (LFN) не поддерживаются

  - Маленький размер кластера (CL_512) и большая область данных 
    могут приводить к жору памяти и торможению

  - Функции копирования и заполнения буфера написаны субоптимально,
    но безопасно: буфер обрабатывается как циклический, в случае переполнения
    переписывается сначала. Это приводит к проверкам на выход за границы для
    каждого байта. Возможно, по соображениям производительности стоит 
    переписать их таким образом, что бы определять расстояние до границы
    и копировать до нее стандартными функциями (memset, memcpy и т.п.)
    Остается на усмотрение.

  - Генерируемый код (правила) может быть еще уменьшен


Сборка
------

Должен работать make config && make all.
Если не работает -- смотрите мейкфайлы

Тестирование
------------

Должно работать make test
По этой команде запускаются тест-кейсы для генерации, компиляции и проигрывания
правил.

См. TestVM.hs для более детального описания тестов.

Если не работает --- смотрите Makefile

Принцип тестирования: каждый тест-кейс генерирует последовательность байткодов, 
эти байткоды поступают в STDIN к cbits/teststubs, результат читается из STDOUT и
сравнивается с образцом.

Примеры:

  ./TestVM run cbits/teststubs

  ./TestVM dump testCallRet1 | cbits/teststubs | hexdump -C

последний пример позволяет посмотреть, во что скомпилировался тест-кейс и 
что получается в результате его проигрывания.

TestVM выдает подсказку по параметрам при запуске без них.


Запускаемые файлы
-----------------

FatGen
~~~~~~

  - Генерация стабов на С
  - Компиляция правил
  - Пример использования FatGenAPI
  - Для подсказки по командам запустить без параметров


TestVM
~~~~~~

Тесты VM


cbits/teststubs
~~~~~~~~~~~~~~~

Тестовая оболочка для тестирования правил. Получает бинарный файл с правилами
в STDIN, пишет результат в STDOUT.

Параметром является номер сектора,  по умолчанию считается 0.

Размер файла правил предполагается не более 16Kb.

cbits/genfat
~~~~~~~~~~~~~~~

Генератор образов FAT. В STDIN получает бинарный файл с правилами, в STDOUT 
пишет результат. Параметр --- количество 512-байтовых секторов для генерации.

Размер файла правил предполагается не более 16Kb.

Пример:

    ./FatGen bin | cbits/genfat 1200000 > fat.img