romtools

A set of tools to manipulate pocketpc roms. specifically written for the xda, but probably not hard to modify for use with other pocketpc platforms

Currently you cannot yet:

You can however:

A tool to do the opposite is dumprom.

Download archive here
Browse source here
note: the source is much more up to date than the zip file

These tools are also described here on xda-developers.com.

README:


'cfg' contains editable configuration files like
   initobj.txt   - specifying how the filesystem is to be organised
   default.reg   - the coldboot contents of the registry.
       [ pay special attention to the 'multi_sz' type keys,
         which are non standard, normally these are represented
         as 'hex(7)' followed by a rather unreadable hex dump. ]
   initdb.ini    - how the databases are setup.

   operator.cfg  - where files are to be copied from autoconfig.
   bootimage.bmp - the bootup background image
   rom.nb1       - the base rom, this patch is to be applied to.
   xipchain      - hand modified xipchain.
   bootloader.nb0- bootloader to insert in nbf

all these files MUST be saved as dos ascii ( with CRLF at end of line )


'tmp' contains intermediary files
'out' contains the burnable rom images

'files1' is to fill up a small hole usually found in roms
'files2' and 'operator' may together contain upto about 5M of files

'operator' is what is used by autoconfig.
   this directory must contain at least 'customid.dat' and 'customtab.dat'
   customtab.dat specifies which configuration options the user can choose
   from.
   registry files can be put in 'platformxxx.reg'

the 'modules1' and 'modules2' directories are currently not used.


...........................
the scripts

makexip.pl   - build new xip block from files and modules directories
               use chainedit.pl to create a corresponding entry in the xipchain
               use splitrom.pl to merge the new xip block into a new rom
					makexip compresses files.

dir2opimg.pl - create operator rom image from cfg file and directory
               use splitrom.pl to add this image to a rom.

opimg2dir.pl - extracts the operator rom from a romimage
               this tool is mainly used to investigate roms.

fdf2reg.pl   - converts a default.fdf to a .reg file
               this tool is mainly useful to investigate new roms

reg2fdf.pl   - converts a .reg file to a .fdf file
               note that a version parameter is needed, to specify if we
               are targeting a wince 3.x or 4.x rom.

splitrom.pl  - general purpose romimage manipulator, add or extract sections of roms
               also validates the result, and checks input files against a list of known
               roms.

tounicode.c  - converts ascii to unicode file, used for initobj.dat
               a win32 executable and elf/linux executable are provided

chainedit.pl - tool to modify a xipchain image

makefiles.pl - split files over several file sections, each with a specified max size.

mkrom.sh     - puts everything together

adaptrom     - tool to fix the nbf header to a desired value, either obtains these values from your
               device via active sync, or lets the user provide them manually

dumprom      - tool to convert a rom back into a collection of files.

setup.sh     - splits rom into bootloader, osimage, xipchain, operator rom
               asks user to manually extract and convert default.fdf, initobj.dat, initdb.ini

calcgaps.pl  - script to locate gaps in the rom suitable for our use.

drparse.pl   - constructs commandline arguments for splitrom, to redirect the filedata pointers
               of duplicate files to the newest entry, using dumprom
               
               This is nescesary to be able to replace files in ppc2003 roms.
               In ppc2002, files in higher numbers xip blocks would override files in lower
               number blocks, in ppc2003 this feature is broken.

make sure 'tounicode' and 'dumprom' are executable ( 'chmod +x tounicode' ) before running mkrom.sh

...........................

bash mkrom.sh output.nb1

this will create a complete romimage, from configuration data in the 'cfg' directory,
operator files in  the 'operator' directory, and other files in the 'files' directory.

...........................

perl splitrom.pl <romfile>  -wo out.nbf -n PW10A1-ENG-3.12-001 -t NBF

  will convert <romfile> to nbf format, with the specified header,
  and a correct checksum.

splitrom.pl can handle plain rom images, sd-card images ( with HTC$WALLABY
header), nbf files ( with 32 byte header with dashes and checksum), bin
files ( with B000FF header ), and xip files.
if you want to manipulate the bootsplash image, the offset must be supplied
using the '-ob' option. newer roms have the bootsplash at 0x81ec0000, older roms
have it at 0x81900000.

these are 2 example commandlines, one for creating a 3.x rom, one for creating a 4.x rom

perl splitrom.pl cfg/rom.nb1 \
        -rm tmp/xdaopimg:0x81940000 \
        -rm tmp/xda1.bin:0x81800000 \
        -rm tmp/xda2.bin:0x81d40000 \
        -rx tmp/xipchain \
        -rb cfg/bootimage.bmp -ob 0x81900000 \
        -rl cfg/bootloader.nb0 \
        -wo nk.nbf -t nbf -n PW10A1-ENG-3.16-007

perl splitrom.pl cfg/rom.nb1 \
       -rm tmp/xda1.bin:0x81740000 \
       -rm tmp/xda2.bin:0x81b00000 \
       -rx tmp/xipchain \
       -rb cfg/bootimage.bmp -ob 0x81ec0000 \
       -rl cfg/bootloader.nb0 \
       -wo nk.nbf -t nbf -n PW10A1-ENG-4.01-007

...........................

perl makexip.pl 0x81940000 files modules myxip.bin

will create a xip rom section, to be burned in rom at offset 81940000
from the files in directory 'files' and modules in directory 'modules'

this tool does the reverse of 'dumprom'

NOTE: the modules part is not implemented yet.

...........................
dumprom.c

this tool extracts all files from the xip sections from an ce-romimage.
the linux ELF binary does not extract files, it only dumps rominfo.

...........................
perl dir2opimg.pl operator.cfg operator operator.bin

will create an operator rom section, operator rom sections are independent of
actual offset, and will be burned at the first 256K boundary after the last
xip section.

beware that the autoconfig tool has a bug, causing strings to be stored incorrectly
in the registry. not all applications will work correctly after their registry
settings were set with autoconfig. most of the time it is better to use
default.fdf to set registry settings.

...........................
perl opimg2dir.pl  romimage operator.cfg operator

this will extract the files in the operator image from a rom to the directory 'operator'
and write a configuration file 'operator.cfg' describing the files.

if the 'operator' directory does not exist, no files will be written.

this file is suitable to recreate this image using 'dir2opimg.pl'

...........................
perl fdf2reg.pl  default.fdf default.reg

will convert an .fdf file ( as extracted from an existing romimage with 'dumprom' )
to a editable .reg file.

...........................

perl reg2fdf.pl   default.reg default.fdf

this will compile an ascii default.reg file, into a default.fdf file,
which is needed to initialize the registry of a device on coldboot.

...........................
tounicode.c  

this is a tool to convert the 'initobj.txt' to 'initobj.dat'.

...........................
chainedit.pl

tool to add xip chain entries to a xip chain image.
normally these contain public keys, used to verify the validity of
xip updates ( as processed by updatexip.exe ), our script does not 
have any keys. we do not intend to send partial romupdates.

example usage: first for ppc2002/wince3.0, second for ppc2003/wince4.2

perl chainedit.pl load cfg/xipchain \
        add XDA_DEVELOPERS1:81740000,00040000 \
        add XDA_DEVELOPERS2:81b00000,00400000 \
        save tmp/xipchain

perl chainedit.pl load cfg/xipchain  \
        add XDA_DEVELOPERS1:81800000,00100000  \
        add XDA_DEVELOPERS2:81d40000,001c0000  \
        save tmp/xipchain

............................
calcgaps.pl

   perl splitrom.pl nk.nb1 | perl calcgaps.pl

start0=81040000
size0=00010000
start1=81740000
size1=00040000
start2=81b00000
size2=003c0000

this will locate all holes of 256k or larger that are in the rom.

you can also specify another 'hole-mask', like 0xffff:

   perl splitrom.pl nk.nb1 | perl calcgaps.pl 0xffff

this will find all holes 64k and larger

............................
todo: describe these:
perl makefiles.pl
perl calcgaps.pl
bash setup.sh

...........................
future:
   - use calcgaps to create list of xip regions.
   - issue is that the operator region needs to be substracted from this list.
   - mkrom should then create cmdlines for makexip, chainedit, and splitrom.
or maybe even better:
   - makexip should use this list of gaps, to create many small files to fit all the
     holes, and act if it is all one region.

about initobj.txt

all files in rom can be found in the \windows directory. the initobj.txt files specifies for certain files that copies to other places should be made..

so if a file is not mentioned in initobj.txt, it is only visible in \windows. also the name of a file in \windows does not nescesarily correspond to the name in wherever it was copied to by initobj

initobj.txt has 2 types of lines ( there are more, but I never looked at them )

   Directory(..dir..) :- Directory(...subdirname...)
to create a subdirectory in 'dir'
   Directory(..dir..) :- File(..filename.. , ...source...)
creates copy of 'source' as 'filename' in directory 'dir'