README

Little C Compiler

Please find language reference at: ./Docs/littleC\ manual.txt

LittleC is an almost-C-language cross-compiler (more in the docs, about the "almost"), originally written in the early 2000s by Simon Lehmayr (https://www.simon-lehmayr.de/))

The LittleC runs on a regular Windows/DOS machine, and makes ASM and binary code for the SC61860 CPU, compatible with several Sharp Pocket Computers, like:

PC-1360, PC-1350, PC-1475, PC-1450, PC-1401, PC-1402, PC-1403, PC-1403H, PC-1421, PC-1260, PC-1261

LittleC is composed of three distinct tools:

• lcpp (the C pre-compiler)
• lcc (the C-to-ASM compiler)
• pasm (the ASM-to-binary compiler)

but these are also wrapped for easier use into a make.bat (MS-DOS batch) file.

A disassembler sdasm, as well as a transer utility wintr are included too, but I won't go into the details about these here. Please refer to documentation (Docs/littleC manual.txt), for additional info.

In order to compile a C source code, take for example the file Demos\parameters\main.c, and generate POKE instructions ready to be embedded in a BASIC program, in a Windows cmd shell, from within the LittleC home dir, enter:

 > make.bat Demos\parameters\main.c tmp.bas bas
 > more tmp.bas
10 POKE 57392,128,16,224,66,0,11,25,120,224,175,128,16,224,66,0,11,24,55,0
20 POKE 57411,0,0,0,0,0,0,0,0,0,0,0,34,116,2,48,89,218,80,89,55,34,116,22
30 POKE 57434,48,89,218,80,89,52,218,52,120,224,78,128,219,34,116,2,50,219
...

Several other example C programs can be found in the Demo\ directory, exploring some of the available features and libraries. See for example Demo\io_libs\main.c, to show

Note that some bugs might still be present, and the supported language is not the full ANSI-C standard (features and limitations are reported in Docs/littleC manual.txt). Not all unsupported features are checked during compilation, so beware! Nonetheless, the job Simon has done is impressive, and even though uncomplete, it can be used to build useful blocks in assembler from simpler C code.

I'm publishing LittleC here on github (including its source code - see below), hoping someone else might find this project interesting enough to improve it even more.

Only a basic set of libraries for keyboard input and screen output handling, is available, and mostly relying on the PC-1403(H) ROM routines, or hardware (LCD) features, so not exactly portable to othe rmodels. See for example how keyboard and screen are handled in Demo\io_libs\main.c.

Debugging with MAME

MAME (https://www.mamedev.org/ - a freeware general purpose machine emulator) demonstrated to be extremely useful for programs debugging, as it offers convenient step-tracing, disassembly and memory debug features. Refer to the MAME manuals, for furhter info about that.

It has to be set up with Sharp PC ROM and artwork, as they don't come bundled with the standard setup. ROM and artwork files can be found around the Internet.

Other emulators offer a much larger set of supported pocket computer models (see https://pockemul.com/)) but at the moment they don't offer a machine language debugging feature.

To run a simulation on MAME, after a binary output tmp.bin (default option) has been generated by LittleC:

 > make [...]\main.c tmp.bin

the binary file should be copied onto the MAME root:

 > copy tmp.bin ..\mame

Then (preferably from a different cmd window), start MAME in debug mode:

 > cd [...]\mame
 > mame pc1403 -debug -nomaximize

which will open a debugger window, along with the Sharp PC emulation window.

NOTE - Sometimes the emulated machine doesn't start up properly. It just doesn't respond to the keyboard! Use the soft reset menu command, from MAME debugger window, until you get:

 MEMORY ALL CLEAR O.K.?

on the emulated Sharp PC screen, then give <Enter> to confirm the device reset.

We need to reserve some memory to store our machine code. Detailed instructions differ for each Sharp PC model, and are provided in the Docs/littleC manual.txt.

E.g. to reserve 2Kb on the PC-1403, the following should be done, before uploading the binary in the device memory.

Set the emulated Sharp PC to BASIC [PRO] mode, then enter:

 NEW
 MEM
 > 6878
 POKE &FF01,&30,&E8
 NEW
 MEM
 > 4830

The machine code entry point is set at 0xE030 = 57576, at the beginning of the main.c program:

#org 0xE030
...

hence you can prepare a Sharp BASIC program to call the machine language program, with a CALL like:

10 CALL &E030

Then, in the MAME debugger console window, enter the command to load the binary in the emulator memory:

 load tmp.bin,e030:maincpu

If you want to set a breakpoint, for example at the program entry point, in the MAME debugger console enter the "breakpoint set" command:

 bps e030

Back to the emulated PC-1403, in BASIC [RUN] mode, start the program

RUN

and MAME debugger will stop at the breakpoint, if set, where you can start your tests from. The 'Enter' key will move step-by-step. The debugger has the usual 'step' and 'run' commands accessed by the debugger window menu. CPU registries are shown. The internal SC61860 CPU RAM (addresses starting at 0x0000) can be shown opening a new debugger memory window and selecting the one tagged with Sharp SC61860 :maincpu/0/m_ram.

For each new test cycle, rebuild the binary, load it on MAME and restart the program:

 (cmd)> make [...]\main.c tmp.bin
 (cmd)> copy tmp.bin [...]\mame
 (debugger) load tmp.bin,e030:maincpu
 (debugger) 'soft reset' (repeat, if device is not responding)
 (Sharp PC) go to <RUN> mode
 (Sharp PC) RUN

Replace [...] with paths to program source, and mame home.

No need to reenter the POKE or the BASIC program, as MAME soft reset won't wipe memory out.

Automating key input in MAME

Tested on the PC-1403 only

The key.lua file is a script for MAME. First, start MAME with the -console option:

> mame pc1403 -debug -nomaximize -console

to open the Lua scripting console, where you can load the script with:

[MAME]>

MAME debugger version 0.267 (mame0267)
Currently targeting pc1403 (Pocket Computer 1403)

[MAME]> dofile ("[...]\pc1403_key.lua")

Replace [...] with your path to the location of LitteC where pc1403_key.lua is found, or even easier, copy pc1403_key.lua to your mame home beforehand, and no need to add a path.

With the script loaded, the keyline() function can be used to send a line of key strokes (auto-terminated with ENTER) to the emulated device keyboard.

Or, keyfile(), to send a list of keystrokes as from an input file.

For example, the below is to enter some of the instructions seen before. Start with Sharp PC in 'CALC' mode (note how "|" is a shortcut to toggle BASIC mode):

[MAME]> keyline("_||POKE&ff01,&30,&e8")
[MAME]> keyline("|NEW")
[MAME]> keyline("MEM")
[MAME]> keyline("1 CALL&E030")
[MAME]> keyline("|")

MEM step should return with on the PC.

Alternatively, using a text file to store the same key strokes, named pc1403_init.key:

_||POKE&ff01,&30,&e8
| 
NEW 
MEM 
1 call&e030 
|

and executing it from the Lua console (still with PC in CALC mode):

[MAME]> keyfile("pc1403_init.key")

More could be done, like interacting with the debugger, etc., but this is just a starting point, for easier test replay.

Compiler source code and rebuild

The LittleC version found on present github repo (the source code was published as freeware by the author, on its page), and it's a sligthly upgraded and revised version, with respect to the original the source code was published as freeware by the author, on its page), to fix some bugs and make some minor upgrades. It includes or example a -still tentative-, early implementation for floating-point variables (note how ROMs differ among different PC models, and I have found some partial documentation about floating-point operations for the PC-1403 only).

The compiler source code is written in Pascal, originally for the TurboPascal I think, but the version on this repo has been ported to modern free Pascal IDE: Lazarus (https://www.lazarus-ide.org/)) at the expense of getting larger executables, compared to Simon's original ones. On the other hand, TurboPascal isn't for free.

Code has been imported using the Lazarus standard import tool, and the generation of new executables went fine at first try.

In order to build a new executable, for example the lcc.exe, you should (assuming Lazarus has already been installed):

• double click on the Source/lcc/lcc.lpi file (this will launch the Lazarus IDE)
• Exec - Compile (ctrl-F9) menu

which will produce a message, if successful, including the destination of the newly built executable. You should then copy this executable to the LittleC home dir, so that it can be used by the make batch:

With the aim of reducing executable size, the following Lazarus compiler options could be set, from the 'Project - Project Options - Compiler Options' menu:

• Configuration and Target:
  • Destination OS: Win32
  • CPU Family Destinatio: i386
• Compilation and link
  • Optimization: O3 (slow optimization)
  • Other: rather smaller than faster

but this needs first the installation of the 64-to-32bit cross-compiler extension (lazarus-3.4-fpc-3.2.2-cross-i386-win32-win64.exe). However, this isn't necessary because the executable size isn't a significant issue.

C Migration Project

A migration project from Pascal to C has been initiated to modernize the Little C Compiler toolchain.

✅ LCPP (Preprocessor) - COMPLETATO

The migration began with the preprocessor component (lcpp), which has been successfully ported to C and enhanced with improved functionality and bug fixes.

The C version of lcpp can be found in Source/C/lcpp/ and includes:

• Complete migration from Pascal to C99 standard
• Enhanced macro parsing with support for complex expressions and parentheses
• Improved error handling and memory safety
• Full compatibility with the original Pascal version
• Comprehensive test suite

🔄 PASM (Assembler) - UNDER VERIFICATION

The assembler component (pasm) has been migrated from Pascal to C, but thorough verification of binary and functional compatibility is still ongoing.

For detailed test cases, a verification harness and current status, see the dedicated README for the pasm C migration at:

• Source/C/pasm/README.md — contains test instructions, test_pasm.ps1 usage, current pass/fail status and debugging notes.

🔄 LCC2 (Compiler) - UNDER DEVELOPMENT

The new C compiler, lcc2, is under development alongside the Pascal lcc. See the lcc2 project, its language manual, and the library reference for the currently supported subset and usage.