.nl files format



FCEUX implements Symbolic Debugger which uses "NameList" files to store the data about labels and comments. The needed files are created automatically when user right-clicks an address in Disassembly and enters a symbolic name or a comment for it. The files are stored in the same folder as the debugged ROM, and they inherit the name of the ROM.

These files are simple ASCII text files. You can edit them in any text editor like Notepad.


When reverse-engineering a game for which you don't have a source, you can reconstruct the logic incrementally, by adding labels/comments while debugging (right-clicking addresses).


But if you want to debug your own homebrew game, you can setup your workflow to automatically export all names and comments when building the game using your favourite assembler (e.g. ca65 or ASM6). This way you can use FCEUX as a Source-Level Debugger.


Example: for the ROM called "NES Test Cart (PD).nes" the NL files will be named "NES Test Cart (PD).nes.0.nl", "NES Test Cart (PD).nes.ram.nl", etc. 


Example of contents of a NL file:


$C000#NewName1#Comment1

$C002##Comment2

$C004#NewName2#

$C006#NewName3#MultilineComment-Part1

\MultilineComment-Part2

\MultilineComment-Part3

$C008/10#NewName4#


Every line contains two # characters which separate the three parts of one line:

* The first part (starting with a $ character) is the address to be renamed. Optionally you can add a "/number" part which marks the offsets as a beginning of an array of the given size (the size must be specified in hex form).

* The second (optional) part is the new name of that address. Whenever the line of that address is shown in the disassembly window, an extra line saying "NewName1: " is shown above it.  Instructions referencing this address, for example JSR $C000 are also changed to JSR NewName1 (in that example).

* The third (optional) part is the comment that's also added above the disassembly line the comment refers to. It works exactly like the additional name line, only the prefix of that line is different. Comment lines start with "; ".  Multi-lines comments are possible. Lines in an NL file starting with the \ character are just appended to the comment of the preceding line. Multi-line comments are also shown in multiple lines in the disassembly window.


In the example above, the first line contains all three parts. Using this NL file, all references to the address $C000 are replaced with NewName1, and whenever line $C000 is shown in the disassembly window (or Trace Logger window) an additional comment is also visible right above the actual disassembled line. The second example line defines only a comment while the third line defines only a name. Following that, there's a multi-line comment definition for address $C006. The last line defines an array called NewName4 of size 0x10 (= 16) bytes starting at offset $C008. FCEUX will regard the line like there are 16 lines describing 16 adjacent addresses with names like NewName4[0], NewName4[1], ... NewName4[F].


NL files must follow a specific naming convention to account for bank swapping. Each bank needs its own NL file with a hexadecimal number of the bank.

For instance, an NES file named "mygame.nes" that has 4 banks (i.e. ROM size = 64k) would have these NL files:


mygame.nes.ram.nl

mygame.nes.0.nl

mygame.nes.1.nl

mygame.nes.2.nl

mygame.nes.3.nl


All NL files must be in the same directory as the ROM file itself.


RAM can also be given its own NL file. In the *.ram.nl file you can name and comment RAM addresses (system bus range of 0x0000 - 0x7FFF) instead of ROM addresses. In this case, you might use a line such as:


$00A5#Mic Test OK#00=Not Passed, 01=Passed





Created with the Personal Edition of HelpNDoc: Easily create CHM Help documents