ROM Allocation Tag System

ROM Allocation Tag System, also known as RATS tags, is a system that protects code from being overwritten by programs that automatically detect freespace. It was created by FuSoYa and originally introduced on Lunar Magic.

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.