--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/imgtools_os/romkiteka2/tools/buildrom.txt	Tue Feb 02 01:39:43 2010 +0200
@@ -0,0 +1,296 @@
+BUILDROM.PL extensions to the OBY language
+Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).  All rights reserved.
+
+
+0. General Comments
+
+BUILDROM processes OBY files written in a superset of the language supported by ROMBUILD.EXE,
+producing an OBY file which is directly acceptable to ROMBUILD. BUILDROM then invokes
+ROMBUILD.EXE on the final OBY file and performs a number of post-processing steps to produce a
+ROM symbol file and directory listing.
+
+BUILDROM keywords are not case-sensitive.
+
+The C++ preprocessor is applied to the file(s) before processing, and the C++ #define, #ifdef 
+and #include facilities should be used to control the inclusion and exclusion of source lines.
+The modifications to the content of those lines should be done using the BUILDROM textual 
+substitution facility.
+
+
+
+
+1. Textual Substitution
+
+BUILDROM.PL implements a simple textual substitution scheme: the C++ preprocessor can't be used
+conveniently because it inserts whitespace around the substituted text.
+
+    DEFINE name replacement
+
+All subsequent instances of "name" will be replaced by "replacement". 
+BUILDROM will also replace "##" with an empty string.
+
+There are three pre-defined substitutions
+
+    EPOCROOT    = the value of the EPOCROOT environment variable
+    TODAY       = today's date as dd/mm/yyyy
+    RIGHT_NOW   = the exact time as dd/mm/yyyy hh:mm:ss
+
+There is no "UNDEFINE" facility, and the substitutions are applied in an unspecified order.
+
+
+2. Additional Simple Keywords
+
+BUILDROM implements the following simple keywords
+
+    ECHO anything at all
+    WARNING anything at all
+    ERROR anything at all
+    ROMBUILD_OPTION command-line-option
+
+The ECHO keyword simply prints the rest of the line to standard output. The WARNING and ERROR 
+keywords report the source file and line number as well as printing the message, and any ERRORs
+will cause BUILDROM to abort without attempting to create the ROM.
+
+The ROMBUILD_OPTION keyword can be used multiple times if desired, and adds additional commandline
+parameters to the eventual invocation of ROMBUILD.EXE. It is primarily used to specify the 
+"-no-header" option for platforms which don't want the 256-byte REPRO header.
+
+
+3. Localisation Support
+
+BUILDROM implements the MULTILINGUIFY() macro that can expand a single source line into multiple
+lines referring to distinct language codes.
+
+    LANGUAGE_CODE nn
+    DEFAULT_LANGUAGE nn
+    data=MULTILINGUIFY( EXT sourcename destname )
+
+The LANGUAGE_CODE keyword can be used multiple times to specify the Symbian 2-digit codes for
+languages to be supported in this ROM. The DEFAULT_LANGUAGE keyword should be used only once.
+
+During the localisation pass, the MULTILINGUIFY lines are expanded into a line per language code,
+as follows
+
+    data=MULTILINGUIFY( EXT sourcename destname )
+
+becomes
+
+    data=sourcename.Enn destname.EXT	    for the default language code nn
+    data=sourcename.Enn destname.Enn	    for all other language codes nn
+
+This provides support for the BafUtils::NearestLanguageFile() function, which is performing a
+similar mapping from language codes to filenames.
+
+
+4. XIP ROM format bitmaps
+
+MAKMAKE normally generates EPOC MBM files in a compressed format, but there is an alternative 
+uncompressed format which allows an MBM to be used directly from the ROM filesystem. BUILDROM
+supports on-the-fly generation of ROM format MBM files from compressed MBM files using the
+BITMAP keyword as follows
+
+    BITMAP=source dest
+
+becomes
+
+    DATA=source_rom dest
+
+and source_rom is generated from source using BMCONV /q /r source_rom /msource
+
+
+If the files are already compressed then the COMPRESSED-BITMAP keyword has to be used in the same way
+
+   COMPRESSED-BITMAP=source dest
+
+becomes
+
+
+    DATA=source_rom dest
+
+in this case source_rom is generated from source using BMCONV /q /s source_rom /msource
+
+BUILDROM will use an existing source_rom file if if is newer than the corresponding source file.
+
+
+4.1 XIP and Non-XIP ROM format bitmaps
+
+BUILDROM provides a keyword to automatically select between XIP and non-XIP versions of bitmaps.
+This is used when it is not known by the application author if the bitmap is to be included in
+an XIP or non-XIP ROM.
+
+	AUTO-BITMAP=source dest
+
+This keyword will use "compressed-bitmap=" for XIP ROMs and "data=" for non-XIP ROMs.
+
+
+4.2 XIP and non-XIP ROM format AIF files
+
+A keyword is provided to automatically select between XIP and non-XIP versions of AIF files.
+
+	AIF=source dest
+
+This keyword will use the _xip version of the specified AIF for XIP ROMs or the originaly supplied file
+otherwise.
+
+
+5. Source reorganisation for two-section ROMs
+(see also section 8 "ROM Configuration support").
+
+ROMBUILD.EXE has the ability to create ROMs divided into two sections, such that the upper section 
+can be replaced without needing to change the lower section. This facility is most often used to
+put localised resource files into the upper section, so BUILDROM provides support for gathering
+marked OBY source lines and placing them in the upper section of the ROM.
+
+    SECTION2 anything
+
+All lines beginning with the SECTION2 keyword are removed from the OBY file, and placed into 
+a separate list with the SECTION2 keyword removed. When BUILDROM encounters the SECTION keyword, 
+the accumulated section2 list is inserted after the SECTION line, and subsequent SECTION2 keywords
+are removed as they occur. If no SECTION line is encountered, the accumulated section2 list is
+emitted after the end of the input file(s).
+
+
+6. Elaborate Example
+
+For example:
+
+    LANGUAGE_CODE 01
+    LANGUAGE_CODE 10
+    DEFAULT_LANGUAGE 10
+
+    file=sourcedir\myapp.dll destdir\myapp.dll
+    SECTION2 REM bitmaps for myapp
+    SECTION2 bitmap=MULTILINGUIFY( MBM sourcedir\myapp destdir\myapp )
+    file=sourcedir\myengine.dll destdir\myengine.dll
+
+    section 0x800000
+
+    file=sourcedir\example destdir\example
+    SECTION2 data=sourcedir\example2 destdir\example2
+
+would become
+    
+    file=sourcedir\myapp.dll destdir\myapp.dll
+    file=sourcedir\myengine.dll destdir\myengine.dll
+
+    section 0x800000
+    REM bitmaps for myapp
+    data=sourcedir\myapp.M01_rom destdir\myapp.M01
+    data=sourcedir\myapp.M10_rom destdir\myapp.MBM
+
+    file=sourcedir\example destdir\example
+    data=sourcedir\example2 destdir\example2
+
+
+
+7. Problem suppression
+
+BUILDROM does a number of things which probably aren't appropriate for producing production devices, 
+but which increase the chance of Symbian internal development builds producing a ROM in the
+presence of build problems.
+
+    ABI_DOWNGRADE   from->to
+
+The ABI_DOWNGRADE keyword allows BUILDROM to substitute a compatible executable if the specified
+source file is not available. It is usually used as
+
+    ABI_DOWNGRADE   THUMB->ARMI
+
+and will substitute \ARMI\ for \THUMB\ if a specified source file can't be found.
+
+In the localisation support, problem suppression allows BUILDROM to handle a missing source.Enn 
+file by specifying source.EXT instead.
+
+In a final pass, if any file is still not available after applying these downgrades then BUILDROM
+will simply comment out the line in the OBY file, in the hope that the missing file is not vital
+to the ROM. If this behaviour is not required the command line option -s can be used to enforce
+stricter behaviour and cause BUILDROM to terminate after the final pass. 
+
+
+8.  Rom configuration support
+
+BUILDROM has ROM configuration features to support building of multiple xip and non-xip
+ROMs for the same device.
+
+8.1 First you must specify the ROM devices
+The ROM_IMAGE keyword specifies a ROM image.  There can be up to 8 images.
+
+Syntax:
+ROM_IMAGE <id> <name> [size=<rom max size>] [xip | non-xip] [compress | no-compress] [extension]
+where:
+id = 0 .. 7
+name = a name suitable as a suffix for the ROM image, oby and logs
+xip = specifies an XIP ROM.  This is the default.
+size = max size of the ROM.  Not required for XIP roms.
+compress = Compress an XIP ROM.
+extension = Indicates this image as an extension to the previous image.
+
+8.2 Including files
+8.2.1 To mark a file for inclusion in a ROM it is prefixed with the keyword
+ROM_IMAGE[<id>]
+eg.
+ROM_IMAGE[2] data=ZSYSTEM\Apps\Calc\calc.INSTCOL_MBM 	    System\Apps\Calc\Calc.mbm
+
+8.2.2 A Block of files can be included using '{' '}' braces.
+eg.
+ROM_IMAGE[2] {
+#include "calc.iby"
+#include "word.iby"
+}
+
+8.2.3 File blocks can be nested eg.
+ROM_IMAGE[2] {
+	#include "calc.iby"
+	ROM_IMAGE[0] {
+		#include "word.iby"
+	}
+	#include "video.iby"
+}
+
+
+8.3 Automatic generation of extension header for XIP ROM
+
+If the ROM_IMAGE specifices an XIP image with an extension, than the following header
+will automatically be added to the obey file. 
+
+extensionrom=<name>
+romsize=<rom max size>
+
+The <name> and <rom max size> are as specified in the ROM_IMAGE keyword. 
+
+The addition of the header will result in rombuild tool producing multiple images
+from the obey file.
+
+9. Strict checking of missing files.
+
+BUILDROM will normally ignore any missing files specified in the obey files. To
+prevent the generation of the ROM when files are missing the -s option is used. This
+ensures that BUILDROM terminates after all the files have been checked and some are
+found missing. The error message indicates how many files are missing.
+
+10. Tests for strict checking and automatic generation of extension header for XIP ROM.
+
+The following tests are executed to check that functionality for
+strict checking of missing files (section 9) and automatic generation
+of extension header for XIP ROM (section 8.3) functions correctly.
+
+Test 1 : Buildrom normal behaviour with missing files.
+
+This test shows that if files are missing then the rom image is still
+generated if the -strict option is not used. The test involves
+renaming some files so that the standard obey file cannot find them.
+Run buildrom and then check that the appropriate files are reported as
+missing and that rom image is generated.
+
+Test 2 : Buildrom missing files behaviour with strict option
+
+This test shows that if the files are missing and the strict option is
+selected then buildrom terminates the generation of the rom image and
+reports the missing files.
+
+Test 3 : Produce a kernel rom image with extension rom
+
+This test shows that if an extension rom is specified in the obey file
+then the obey file generated by buildrom contains the correct header
+information to generate an extension rom.
+