I've listed two recommended compile lines below that go from source to output sna. These assume you are not making a dot command. The source files can be any mix of .asm / .c / whatever as zcc knows what to do with it all. The options in the compile lines are described and you may want to adjust them for what you are doing. You can also build to object files first and combine the object files to make the binary if you want to use a makefile or similar. If you come up with a set of utility routines you may also want to look into building a library from which the linker can pull out a minimum set of code used by a program.
A beginner introduction to using zsdcc and the new library (which has the zx next target) can be found here:
https://github.com/z88dk/z88dk/blob/mas ... edGuide.md
It's written for the plain zx spectrum but plain zx spectrum is a subset of the zx next so everything written there also applies, although maybe it's not as complete for the zx next. You can change the compile lines to use "+zxn" instead of "+zx" to generate zxn compiled code.
A technical introduction to using z88dk geared at z80 embedded systems can be found here:
https://www.z88dk.org/wiki/doku.php?id= ... t_embedded
ZSDCC AS COMPILER
(zsdcc can be very slow when optimization is high but it yields smaller and faster code)
zcc +zxn -vn -m --list -startup=31 -clib=sdcc_iy -SO3 --max-allocs-per-node200000 --opt-code-size @source.lst -o outname -pragma-include:zpragma.inc -subtype=sna -Cz"--clean --pages --fullsize --main-fence 0xf000" -create-app
SCCZ80 AS COMPILER
(sccz80 is very fast)
zcc +zxn -vn -m --list -startup=31 -clib=new @source.lst -o outname -pragma-include:zpragma.inc -subtype=sna -Cz"--clean --pages --fullsize --main-fence 0xf000" -create-app
Select the zx next target making its library available, its defines available and enabling the z80-zxn cpu in the assembler.
Keep messages to a minimum. If you want to see what zcc is doing use "-v"
Create a map file showing all symbols in the project.
Generate list files for all input source. You will be able to see the generated asm for each c source file, eg. Adding "--c-code-in-asm" will also add c source as comments into the generated .lis files. If you only want to see how a particular c file is translated to asm, look into the "-a" option for zcc.
Select one of the canned crts. The crt is startup code that generally has form "initialize; call main; tidy up; exit behaviour". What goes into the crt is controlled by pragmas for which there are defaults defined. For convenience, z88dk provides quite a few different crts identified by number whose main difference is what drivers are instantiated on stdin,stdout,stderr. Users can define their own driver instantiation as well if they want to have multiple text windows open or want to subclass the library drivers to change behaviour.
31: no drivers instantiated on stdin,stdout,stderr. printf and scanf will not work. Minimum size.
0: spectrum screen 32x24, 8x8 fixed width font, no control codes
1: spectrum screen 32x24, 8x8 fixed width font, control codes
4: spectrum screen 64x24, 4x8 fixed width font, no control codes
5: spectrum screen 64x24, 4x8 fixed width font, control codes
8: spectrum screen 256x192 pixel, fzx proportional font, no control codes
9: spectrum screen 256x192 pixel, fzx proportional font, control codes
16: timex hi-res 64x24, 8x8 fixed width font, no control codes
20: timex hi-res 128x24, 4x8 fixed width font, no control codes
24: timex hi-res 512x192 pixel, fzx proportional font, no control codes
30: spectrum rom rst $10 driver, no scanf.
(for small compiles still needing printf and for dot commands)
We're still not finished here - we still need text drivers for layer 2, lo-res, some more with control codes, and interfaces to NextOS's own windowed text terminals. Mainly we're doing them as people request them because there is still a lot of work to do.
All code in the library is independent of the rom except for startup=30 which uses rst$10.
-clib=sdcc_iy or -clib=new
-clib=sdcc_iy : Select zsdcc as c compiler and select the sdcc_iy version of the library. If you have no C in the project, the c compiler will not be used but asm using library code will get this version of the library.
-clib=new : Select sccz80 as c compiler and select the new version of the library. If you have no C in the project, the c compiler will not be used but asm using library code will get this version of the library.
The library's asm code is identical in both versions of the library*** but the c interface to that asm code is different.
*** Very important: In sdcc_iy, the index register the library uses is changed from ix to iy. This is done to improve performance when using zsdcc.
-SO3 --max-allocs-per-node200000 --opt-code-size (optional)
These are optimization settings for zsdcc only.
-SO3 selects the aggressive peephole rules and can clean up the generated code considerably. Use -SO2 if you suspect a bug.
--max-allocs-per-node200000 sets the optimization setting of the compiler itself very high. It gives the compiler permission to investigate alternate code generation. A high setting like this leads to better code but it is also makes zsdcc extremely slow. The default value is 3000 and you can eliminate this option during dev to speed up turnaround.
--opt-code-size Informs zsdcc you want to prefer small code. Impact on code speed is usually not that great.
This is a separate file "source.lst" that can contain a list of source files you want in the compiler. Alternatively you can just list all the source files on the zcc compile but the .lst file option makes it easier when there is a long list of input source files.
Example contents of source.lst:
Code: Select all
; comment src/foo.c here.asm @more.lst
The root name of all output files. "outname.sna" will be the name of the generated sna file in this case.
What the crt does is determined by pragmas. In any compile there is a default set active that you can override inside a file like "zpragma.inc".
Code: Select all
// move org to have more room for software sprites #pragma output CRT_ORG_CODE = 30000 // typical stack location when using sp1 sprite engine #pragma output REGISTER_SP = 0xd000 // indicate we are not returning to basic, reduces crt size #pragma output CRT_ON_EXIT = 0x10001 // control size of printf #pragma printf = "%u" // use a different font to be crazy #pragma redirect CRT_OTERM_FONT_8X8 = _font_8x8_clairsys // heap sizes #pragma output CLIB_STDIO_HEAP_SIZE = 0
https://www.z88dk.org/wiki/doku.php?id= ... figuration
The default values for the zx next target ram model compiler are here:
https://github.com/z88dk/z88dk/blob/mas ... ig.inc#L19
Some new pragmas are defined just for the zx next to configure the text terminals and set org for memory banks:
https://github.com/z88dk/z88dk/blob/mas ... les.inc#L2
The toolset has a lot in it so don't be too overwhelmed. You can safely ignore what doesn't make sense right away.
-subtype=sna -Cz"--clean --pages --fullsize --main-fence 0xf000" -create-app (optional)
-subtype=sna selects sna as output type.
-create-app has zcc invoke appmake following a compile to form the sna
-Cz passes additional options to appmake concerning the generation of the sna.
--clean = remove all binary files generated that have been placed into the sna. Any binary files remaining is your responsibility to get into memory somehow. For example, if you place something into page 30, this cannot be in the sna so instead the tools will output a binary representing page 30 that your program must load into ram when it starts.
--pages = prefer the zx next's memory to be output as 8k pages instead of 16k banks.
--fullsize = pad each binary representing the zx next's memory to the full 8k/16k size.
--main-fence 0xf000 = generate an error if the main binary exceeds this address. You may want this, eg, if you want to reserve the top 8k for banking so you don't want any code to pass the 56k mark.
To make the crt as small as possible (perhaps a dozen bytes) you would use:
-startup=31 (printf,scanf will not work)
and these pragmas:
// on exit, enter infinite loop
#pragma output CRT_ON_EXIT = 0x10001
// eliminate the user heap (malloc)
#pragma output CLIB_MALLOC_HEAP_SIZE = 0
// eliminate the stdio heap (files cannot be opened at runtime)
// note this does not affect esxdos, nextos low level opens without FILE*
#pragma output STDIO_HEAP_SIZE = 0
The rest of the defaults should be good.
There are additional zcc options "--codeseg" and "--constseg" to compile c code into particular pages or banks. From asm, changing to a particular page or bank can be done at any time with the "SECTION" directive.