ROM Allocation Tag System

From SMWiki

ROM Allocation Tag System, also known as RATS tags, is a system that protects code from being overwritten by programs that automatically detect freespace.

Due to the way freespace finders work, if there is a bunch of $00's in the middle of a piece of code, the freespace finder will mistakenly think the block of $00's is freespace. However, RATS tags tell freespace finders that a certain number of bytes following the RATS tag shouldn't be touched, so even if there are a bunch of $00's in your code, they won't get overwritten.

Implementation Details

A RATS tag is in the following format:

   (Binary, 8 bytes.)
   0 1 2 3 4 5 6 7
   S T A R n N x X
   
   "STAR" is the identifier of RATS tags.
   
   Consider the 16-bit unsigned integer Nn.
   Nn is the size of the RATS protected code (not including the RATS tag) - 1.
   
   n is the low byte of Nn; N is the high byte.
   x is the bit-wise complement of n. X is the bit-wise complement of N.

Consider if you wanted to protect the text "Hello!" (without quotes). The text is 6 characters long.

   Nn = 6 - 1 = 5.
   n = 0x0005 & 0xFF = 0x05.
   N = 0x0005 >> 8 = 0x00.
   x = ~0x05 = 0x05 ^ 0xFF = 0xFA.
   X = ~0x00 = 0x00 ^ 0xFF = 0xFF.
   
   The RATS tag would be: (binary)
    S  T  A  R  n  N  x  X
   53 54 41 52 05 00 FA FF

To make a RATS tag protect the freespace used by an xkas patch, you would use code like this:

   org !Freespace
   
   db "STAR"
   dw CodeEnd-CodeStart-1
   dw CodeEnd-CodeStart-1^$FFFF
   
   CodeStart:
   
       ; ...
   
   CodeEnd:

Important

• Nested RATS tags are not allowed. While Lunar Magic does extra checks to preserve data integrity, do not rely on its behaviour; other applications may not be so forgiving.
• The minimum size of RATS protected data is 1 byte. Attempting to protect 0 bytes will cause the RATS tag to protect 0x10000 bytes instead of 0 bytes.
• If a patch submitted to SMW Central uses freespace, it must protect the freespace used with a RATS tag.