
About ROMPatch
--------------

This is an entirely new version of ROMpatch, coded in C and assembler,
and using an improved mapping strategy. It breaks ROM mapping into
sections, large pages and pages, retaining larger mappings where
possible (the restriction being that patch hits must appear in
pages). The old version always breaks the ROM entirely into pages.

The advantage of retaining larger mapping granularity is that it
is potentially far less likely to provoke MMU TLB misses (the
unpatched ROM is mapped very efficiently, as 4x 1Mb sections).

Version 2.02 supports patches for multiple ROMs (within reason).

A brief description of files in this directory follows:
 
binary               holds interim build target(s); just the
                     unsqueezed runimage in this case

c.rompatch           most of C code
c.debug              routines for debugging only

docs.xxx             other documents, including info on StrongARM bug, and
                     results of binary and source code searches

h.debug              defs used only for debugging
h.defs               types and defs

Install              target stuff for distribution; the obey file
                     !!ROMPatch and the directory ROMPatch should be
                     placed in the user's !Boot.Choices.Boot.PreDesk, to
                     implement patches; the make builds ROMPatch.!RunImage;
                     a ReadMe and TechNote for distribution are also there

patches.h.patch      structure that collects all patch groups for all ROMs together
patches.370.h.*      all patches for RISC OS 3.70
patches.360.h.*      all patches for RISC OS 3.60

pdiff                contains C app that can compare two 4Mb ROM files,
                     and output difference list in style required for
                     a patches.h file

s.asmutils           routines implemented in assembler (they require
                     supervisor status)
s.module             construction of module that is inserted to handle
                     patches dynamic area (mainly, to remove patches on reset)

UK                   compile-time internationalisation (yeah, want to make
                     something of it?)


Adding a ROM supported by patches
---------------------------------

See patches.h.patch. Should be straightforward, but note that some code may
be affected by OS variable placement changes (see h.defs and the assembler source
in the s directory). Only 4 Mb ROMs are currently supported.

Adding a patch group:
---------------------

See patches.360.h.* and patches.370.h.* for examples. Each ROM has an h.patch
file that collects the patches together. Each patch must define a procedure of
the form:

static patchentry_t *somepatches_proc(void *handle)
{
  /* return either a list of patchentry_t triplets, terminated by {0,0,0},
     or NULL meaning this group not required in this configuration */
}

The generic handle is currently not used (always passed as NULL).

This function is then of type patchlist_proc, and suitable for inclusion
in the list of functions (terminated by NULL), in h.patch.

Note that the function must be callable more than once.

See patches.370.h.STMHpatch for an example of a patch conditional on current
configuration. See patches.370.h.RTCAfix for an example of a 'patch' that
doesn't output a patch, but applies a runtime fix.

---

mjs/issue 2, 24 Feb 97
