ScriptSDCC is machine code interpreter compatible with MCS51 and Z180 architectures. It uses 64kB code and data memory, which can be common or separated, but on Z80/Z180 architecture, separated memory is not usable, because Z80/Z180 processor is not designed to work on separated data and program memory. ScriptSDCC requires Windows or Linux system with SDCC compiler installed with add SDCC path to environment variable PATH. This compiler is invoked during compiling and running script. ScriptSDCC is designed to be compatible at the script source level with MCS51 and Z180, so in most cases, the same source can be compiled and run on either MSC51 or Z180 without changes. The only IO interface is the special address space with 256 bytes length called as swap memory. The IO interfaces existing in real processors are not supported. Interrupts are not supported, so interrupt functions can not be called. ScriptSDCC has three input/output modules, each module exists in 4 independent instances. This modules are console, spreadsheet and graph. You can watch the same instance of I/O module in several windows, especially when you want to display graph in several perspectives.
You can define bundle, which consists of maximum 256 independed scripts. This is usable to run one script from another script or run several script simultaneously.
Each script is run in independed virtual machine, but IO and memory buffer is shared, so the first script can generate data, which are aquired by second script.
You can create/edit ScriptSDCC script definition using following data:
- Description - User text intended to describe project, this text does not affect in script compiling and running.
- View/Edit command - System command to view od edit project. For example, using this command you can open source file in text editor or display project folder.
- Source file name - You have to input source *.c file with path. The path can be absolute or relative to project file. The file will be copied into temporary directory before compiling.
- Binary file name - You have to input compiled hex file name without the path.
- Library files - All needed file names from library directory or with path separated by "|". These files will be copied into temporary directory before compiling.
- Engine type - Select engine type between MSC51 or Z180.
- Memory - Select common CODE/DATA or separated CODE and DATA memory architecture.
- Compile command - Command line used in compilation.
In Compile Command field, you can use wildcard strings from following values:
- %CODELOC% - Code memory location.
- %CODESIZE% - Code memory size.
- %DATALOC% - Data memory location.
- %DATASIZE% - Data memory size.
- %SWAPLOC% - Swap memory location.
All mentioned values must be in hexadecimal form, these value are the most significant byte. For example, if you want to set 4000 to 7FFF range for data, you have to input "40" in Data memory location and "4000" in Data memory size. You can open existing project using Open button and save project using Save or Save as button.
You can create compile scheme to save the most frequently used compile configuration. Compile scheme consists of engine type, CODE/DATA memory architecture and compile command. If you want to create scheme, input name of new scheme and click Add/Modify scheme. If scheme with entered name exists already, it will be replaced. If you want to remove scheme, select scheme in Compile scheme and click Remove scheme.
If you want to compile project, you have to click the Compile button. Before compiling, ScriptSDCC creates file "_.h" in temporary directory, which defines macros characteristic for current compilation. The first macro is "mem_swap" with values, where there is defined swap memory address. The second macro is "engine_mcs51" when compiling for MCS51 or "engine_z180" when compiling for Z180. The third macro is "mem_separated" wher CODE and DATA memory are separated or "mem_common" when CODE and DATA are in common memory. The macros can be used to write one code, which can be used on several configurations without code modification. During compilation, if source file or library file is without path, the file will be searched in following paths:
- Project path if project is saved.
- Source code file path if this path is specified with source file name.
- Library paths.
Path existence is determined by detecting "/" or "\" character in file name. ScriptSDCC will try the first case, the next following cases will be tryed only if previous case fails. If file is not copied, compilation process will not invoked and appropriate message will be in Compiler messages on the Compile and run tab. After compilation, if compile is not successful, on the Compile and run tab, there are compiler error and warning messages in Compiler messages field. If compile is successful, the field Compiler messages is blank.
During script running, there is one special memory space, which is used to communicate with I/O and controlling behavior from running script. For swap memory, there is reserved 256 bytes. After compiling or resetting, the first byte is set to zero and this value is followed before running every elementary instruction. When this value is other than 0 (this value can be treated as command), the ScriptSDCC does any action assigned to this value. If desired action needs any parameters or returns some value, the parameters are read from further bytes from swap memory and value is written to further bytes of swap memory. After doing action by ScriptSDCC, in most cases, the first byte is set to 0, so this allows to continue script running. If the first byte has set value other than 0, this script is stopped and cannot be resumed. For script performance reasons, all commands with I/O ale multiples of 4 and there is added number of instances (from 0 to 3). The other commands are not multiples of any number. If any I/O command is designed to get or set data of miscellaneous types, there types are following numbers:
- 0 - Signed char as text.
- 1 - Unsigned char as text.
- 2 - Signed char as number.
- 3 - Unsigned char as number.
- 4 - Signed short.
- 5 - Unsigned short.
- 6 - Signed int.
- 7 - Unsigned int.
- 8 - Signed long.
- 9 - Unsigned long.
- 10 - Float.
The value type byte is at Swap+1 address and the value is at Swap+8 and can occupy 8 bytes. The returned value is in Swap+8.
All commands are used in the standard library (C header files), the usage can be easily dedicated by function code analysis, these function are very simple. All functions are described in comments.
After compiling, you can run script by clicking Run/Continue button. During script running, you can click Stop button to stop running, then you can click Run/Continue button to continue script running. The Reset button resets virtual machine to allow run script again from beginning. During script running, on the Compile and run tab, you can watch current script status, total executed instructions and number of instructions per second.
The first I/O module is text console. It can print any text and get characters from keyboard using buffer. It is usable to print program running messages and get simple choices as menu selection or working mode. You can control console using following buttons:
- 0, 1, 2, 3 - Display instances.
- Clear - Clear console.
- Copy - Copy selected text in console to clipboard.
- Paste - Paste text from clipboard as keystrokes.
The second I/O module it the spreadsheet are a simple table, which consists of 256 rows and 256 columns. This module is not intended to replace spreadsheet application from office suites, so it not supports formula calculation. Each cell contains text value, but it is possible to get or set number value. Spreadsheet is mainly intended to enter input data and read output data. You can manipulate using buttons:
- 0, 1, 2, 3 - Display instances.
- Clear - Clear selected area.
- Copy - Copy selected area to clipboard as text with tab used as column separator.
- Paste - Paste text from clipboard into selected area. The tab character in text is treated as column separator.
- Row add - Add one row.
- Row rem - Remove one row.
- Col add - Add one column.
- Col rem - Remove one column.
The third I/O module is graph, which can visualize 2D or 3D graphics. It can displays points, polygonal chains including line segments and triangles. There is 256 draw threads, the 0 thread is intended to draw points and triangles. The other threads are intended to draw polygonal chain. Using threads, you can draw a few polygonal chains simultaneously. To draw polygonal chain, you have to select any thread other than 0 and reset this thread. Then, you can set points of the chain one by one. If you want to draw another chain in the same thread, you have to reset this thread. To draw a triangle, tou have to plot at least three points and convert them to triangle using appropiate command. You can use the same points more than once, everytime there will be converted the last three plotted points. For example, you can draw tetragon by plotting the first three points (the second and third point must be a diagonal ends), convert them to first triangle, after that draw fouth point and convert to triangle again. The second triangle will be used second, third and fourth poins, so the second and third points will be used to both triangles.
The graph module has following display controls:
- 0, 1, 2, 3 - Display instances.
- Basic, Scale, Rotate, Light - Show or hide toolbar.
Basic toolbar:
- Clear - Clear graph.
- Color - Set background color.
- Point size - Set point size in pixels of plotted points.
- Line size - Set line size in pixels of plotted line segments.
- Surfaces - Fill triangle surfaces.
- Text - Diaplay text labels.
- Inv - Invert draw order at the same X, Y, Z display coordinates, this option can change artifacts in some cases.
- Value change - Set value change step in all spin controls in other toolbars.
- Render to file - Render picture to specified PNG file. The picture size can be specified.
Scale/pan toolbar, the following parameters has three values, each is for X, Y and Z coordinates:
- Scale X - Scale coordinate value to X value on screen.
- Scale Y - Scale coordinate value to Y value on screen.
- Scale Z - Scale coordinate value to Z value in Z-buffer.
- Scale XYZ - Scale coordinate proportionally on screen to change a scale. Values Scale X, Scale Y and Scale Z are multiplied by ScaleXYZ value. The product is in one millionth parts.
- Pan data - Offset in one millionths of source to plot.
- Pan render - Offset in pixels on screen of rendering graphics.
Rotate toolbar:
- Rot data - Transform source data by specified axis order and rotate around axes in degrees.
- Rot draw - Transform drawing data by specified axis order and rotate around axes in degrees.
Light toolbar:
- Lighting - Specify pseudo-lighting algorithm.
- Azimuth, Elevation - Set position of lighting line.
- Color position - Set position on lighting line (distance algorithm) or on angle (angle algorithm), where objects has original colors.
- Distance 1, Distance 2 - Set position/angle in front of object and behind the object, where color is faded to background (positive value) or faded to inverted background (negative value). When value is set to 0, color will not be faded.
This algorithm uses color fade settings on lighting line. This line always contains the zero point (X=0, Y=0, Z=0) on screen. For each pixel in space, the color will be based on distance between zero point and plane perpendicular to lighting line. The color position and distance parameters defines pixel color related to position on lighting line.
This algorithm user color fade related to object angle to lighting line. The color of points will be intact, because point has no dimensions. For lines, lighting angle is measured in plane, which is both parallel to calculated line and lighting line. User observes line as always lit. For triangles, lighting angle is measuret between triangle plane and lighting line. User can observe lit or unlit side. Shadows projected by other triangles are not simulated. Color position 0 means color of line or triangle, which is parallel to lighting line. Color position means object angle, where has original color. The distances determines angle, where color fades to background or inverted background.
ScriptSDCC allows to use 256 memory buffer items, each are 65536 bytes long. Script can copy data from internal data memory to buffer and from buffer to internal data memory. Script can also copy data from file to buffer and from buffer to file. In whole ScriptSDCC session, there can be open 256 files simultaneously, each script can access to all memory buffer items and all file handles.
On the Memory map tab you can see CODE or DATA or BUFF memory occupation. Each pixel on the map represents one byte. Using H+, V+, H- and V- buttons, you can zoom the map horizontally and vertically. If you click CODE button, the script code occupation and code reads will be displayed, and if you click DATA button, it will be displayed all reads and writes made during script running. The colors of blank bytes means following:
- Blank - Byte out of swap, code and data space.
- Gray - Byte in swap space.
- Dark blue - Byte in code space.
- Dark yellow - Byte in data space. If you see BUFF memory, the will be displayed shared memory buffer at the same number, whis is selected on Bundle tab. Below memory map, you can see file name attached to file handler. For example, if you select third item on Bundle tab, you can see third memory buffer occuparion and third file handle assignment despite of script, item, memory buffer item and file handle are independed.
After compiling and during script running, colors may be changed as follows by setting maximum channel value:
- Green - Read byte.
- Red - Wrote byte.
- Blue - Byte of program code based on HEX file.
These colors can be combined, which means as follows:
- Yellow - Byte, which was wrote and read.
- Cyan - Byte of code, which was read.
- White - Byte of code, which was read and wrote.
- Magenta - Byte of code, which was wrote and not read.
The cast of two cases theoretically can occur, but in most cases, it signals error in compilation parameters or script execution, because SDCC does not support self-modification code.
Directly after compilation, there is applied some patch in beginning of memory to ensure correctly script execution.
- MCS51 - There are written three bytes from "0000" to "0002" to ensure jump to program beginning. The first byte is always "02" (jump operation code) and the next two bytes are the code location beginning address in big endian order. Practically, the 0002 byte is always "00".
- Z180 - There are written two bytes to "0101" and "0102". These bytes is the stack pointer just after program beginning in little endian order. Practically, the first byte is always "00". Without the patch, the stack for data will be begin always from "FFFF".
Project can be saved to file. In file, there will be saved all parameters from Script tab. At the top of the tab, there list of favoutite projects, which providest fast and easy access to frequently used projects. You can manage projects using following buttons:
- New - New project (clears all fields and current file name).
- Open - Open project from file.
- Save - Save project to current file. If file name is not specified, ScriptSDCC will ask for file name.
- Save as - Save project to new file.
- Add to list - Add project to favourite list. This project must be saved to file and in list field you have to specify display name before clicking this button.
- Rem from list - Remove selected project from list.
At the first run, you have to set settings on the Settings tab. These settings are following:
- Timer interval - Time in milliseconds between two refreshes. To take effect of changing this value, you have to restart SDCCScript.
- SDCC command - Set SDCC compiler invocation command. This setting usually can be "sdcc", but in certain installations, you have to input this command with full path.
- Library directories - Paths to directories, which contains files, which can be included as library (mentioned in Library files field on Script tab). You can write more than one path separated by end of line character or "|" character.
- Temporary directory - Path to directory with read and write permission, which is used during compilation. Before compilation, all files placed in temporary directory will be removed.
- Console font - Font name and size used to display text in console window.
- Spreadsheet font - Font name and size used to display text in spreadsheet window.
- Graph font file - Bitmap file containing font, which is used in text rendering in graph window.
The font file, which can be used for labels in Graph, is a bitmap file. The bitmap width must be a multiplier of 256 plus 8 (for example 2056 pixels for character width 8 pixels), the bitmap height must be multiplier of font height. The font is monospaced font, which consists of some of Unicode pages. The first 8 pixels contains binary code for page and the each pixel represents of bit in the binary representation number of the page. The code must be painted across whole line and the line height must be constant for all defined pages. The pixels can be white and black, but the color is detected based on color brightness in picture. If picture is not valid, the labels will not be displayed. If the painted text contains characters in not included pages, the characters will not be displayed. The example property prepared font is in the "font.png" file, which should be placed in the same directore, where is the compiled ScriptSDCC executable file.
You can create default template, which will used for new projects. To create this, tou can have to save current project as "default.sdc" and plate it in application directory. After this, if you start ScriptSDCC or create new project using New button, this file will be loaded, but project will be treated as new, unsaved project.
ScriptSDCC is prepared for Windows and Linux using Qt5 library and project is created with Qt Creator. The other operating systems are not supported and tested. ScriptSDCC works only if "Q_OS_WIN" or "Q_OS_LINUX" is defined in Qt library. To compile in both systems, you have to install standard Qt5 library and Qt Creator. Then, you have to build project as release. To deploy in Windows, you have to use windeployqt.exe supplied with Qt library. To deploy in Linux, you have to use "linuxdeployqt-continuous-x86_64.AppImage" from https://github.com/probonopd/linuxdeployqt/releases. After deploying, application should run on another machine, without Qt preinstalled.
To write own script, you can use supplied API consisting of C headers. The details are described in "readme.txt".