A very preliminary approach of µCsim

The most obvious desire is not the one we never question, but the one we come back to most often.
Blanche de Richemont, Eloge du Désir

Yeah I’m thinking again about the C compiler for the TLCS-900H. It keeps popping up in my head then I forget about it for months then it comes back and I tell myself "I should give it a try". Even though I never wrote a compiler nor a simulator nor an emulator. I only took a random Computer Architecture course like 20 years ago. And I now have a time-consuming baby.

But the desire is there. And there is also a need for this, as the amateur development world for the Neo Geo Pocket depends today on Toshiba’s proprietary C compiler. There is an open-source assembler for the TLCS-900H CPU but one has to be realistic, programming is much easier in C. I’m definitely not against using commercial tools for hobby projects, but I believe that the price of the compiler is too expensive and using the versions that circulate online cause a legal risk.

So yeah, the desire is there. This time I decide to investigate SDCC again. Since it’s 2026 i use ChatGPT as a discussing partner and we come to the conclusion that the first thing to write would be a simulator that can take TLCS-900H binaries and run them and return the results, so that when I reach the moment where I generate binary code from C, I can check whether the code works. And this would be a simulator.

I had been wondering how SDCC was being tested and ChatGPT kindly tells me that it contains its own multi-architecture simulator called µCsim. The simulator might be modular enough so that it is easy to add a new architecture to it.

However, as it is often the case with open-source projects, there is zero developer documentation on this thing. How to dive in? I check the sources which do not contain comments or so few, realize that it’s in C++ that i have never really used. Sigh. Where to start? There is a folder named "core" containing some subfolders and a folder named "sims" which contains 1 subfolder per CPU. This might be a good place. I open some files at random, they’re full of preprocessor macros, the horror. How can I make sense of it?

I ask ChatGPT for advice. It suggests me to do 3 things:

• first to use a code editor that allows to navigate between files. I choose Geany, a lightweight editor.
• then to use the ctags -R * command line in the root folder of the project so as to generate a database of symbols that will ease search
• finally to locate the main function, eg. The program’s starting point.

What do I find? Of course, there are dozens of main(). It looks like µCsim ia not one big program but more a collection of small utilities. So which main() is the good one?

Each architecture has a main() which can be found (for example) in src/sims/tlcs/sltcs.cc and contains roughly the same thing for all the CPUs :

int
main(int argc, char *argv[])
{
  int retval;
  class cl_sim *sim;

  app_start_at= dnow();
  cpus= cpus_tlcs;
  application= new cl_app();
  application->set_name("stlcs");
  application->init(argc, argv);
  sim= new cl_simtlcs(application);
  if (sim->init())
    sim->state|= SIM_QUIT;
  application->set_simulator(sim);
  retval= application->run();
  application->done();
  delete application;  
  return retval;
}

So what does this do? It creates an instance of an application (class cl_app) and then an instance of a simulator (class cl_simtlcs). Both classes take each other as a parameter. Then we initialize the simulator, and finally we launch the application.

It looks like the cl_app class is most likely generic and that the cl_simtlcs class most likely derives from a simulator base class that i can derive for my new architecture.

ChatGPT also suggests to create my own class instead of tacking my CPU to the existing TLCS simulator. The TLCS-900H is being very different from the already implemented TLCS-90 and TLCS-870. It’s better to start from a clean state than adding plenty of exceptions. I guess that’s a sensible idea, so I’ll get started like that.