SymbOS ASM-Developer kit 1.0

Enlighted (6127)

31-10-2021, 22:49

ℋℯℓℓℴ,

Have you always thought that developing for SymbOS is hard and you can't get any hang of it? Well, then you are now at the right place!

I'm proud to present to you SymbOS ASM-Developer kit 1.0!

This package includes all you need to know about SymbOS development in a much more user friendly package than before. It includes a 5-page long introduction that teaches you in a concrete way, how you can navigate through the official documentation, where you should look and how you can avoid the most obvious pitfalls while doing so. It also includes many SIMPLE example programs you can study and compile at home and the examples also guide you towards correct places in documentation. If you read my instructions carefully, I don't think you can get lost anymore. The official documentation is actually VERY good when you learn to navigate in it.

Naturally the very latest version of documentation is also included. Many people think that SymbOS development is only for Windows users, but even that is not true... With this developer package you can very well get going with Linux or Mac just as well and still get easy access to all parts of the OS. I've completely rewritten the application template, so you don't need to guess anymore what label means what. The templates also follow very simple up to down order with tips and all the different parts of programs are clearly separated, so their relationships should be easy to follow. The development libraries have been adapted to include standard routines automatically as you use them, so starting application development on assembler can not get much easier than this.

Still not convinced that YOU can do it? "Uh, oh, it is all so new and weird!"

Well, take a quick look at these few routines that I extracted from the examples:

Main_Routine:

            ld de,.TxtName
            ld c,9
            call BDOS    ; Print question

            ld de,.TxtBuffer
            ld c,10
            call BDOS    ; Ask for name

            ld de,.TxtHello
            ld c,9
            call BDOS    ; Print "Hello, "

            ld a,(.TxtBuffer+1)
            ld de,.TxtBuffer+2
            ld l,a
            ld h,0
            add hl,de
            ld (hl),"$"  ; Mark end of string

            ld c,9
            call BDOS    ; Print name

            ld de,.TxtRet
            ld c,9
            jp BDOS      ; Print CR,LF

;--------------------------------

.TxtName:    db "What is your name? $"
.TxtHello:   db 10,13,"Hello, $"
.TxtRet:     db 10,13,"$"
.TxtBuffer:  db 255,0     ; Must have length of 258 bytes
             ds 256

Main_Routine:

            ld hl,.TxtName   ; Print "What is your name"
            call .Print

            call QINLIN      ; Ask string input with "? "
            inc hl
            push hl

            ld hl,.TxtHello
            call .Print       ; Print "Hello, "

            pop hl
            call .Print       ; Print name

            ld hl,.TxtRet     ; Print CR,LF
.Print
            ld a,(hl)
            and a
            ret z
            inc hl
            push hl
            call CHPUT
            pop hl
            jr .Print


;--------------------------------

.TxtName:    db "What is your name",0
.TxtHello:   db 10,13,"Hello, ",0
.TxtRet:     db 10,13,0

Does even one of them look familiar? If yes, then you KNOW that you can at least compile SOMETHING for SymbOS as well... Ok, they do need the rest of the template around them to work and I do not recommend either of these programming styles to be used to make applications for SymbOS, but I know it sure is nice to have something familiar to start digging into.

Please have a look inside and tell what you think.

By Manuel

Ascended (19811)

31-10-2021, 23:22

Cool! What about a C library to make SymbOS apps easily in a common high level language like C?

By NYYRIKKI

Enlighted (6127)

01-11-2021, 00:02

Manuel wrote:

Cool! What about a C library to make SymbOS apps easily in a common high level language like C?

I was planning to write here quite a long story, but maybe it is enough at this point if I just say: No
There are quite a few things that make you understand me better if you just open the readme-file. I just say the core problem is quite a bit more complex than missing libraries. If you want high-level environment, try Quigs. It is designed from scratch to work efficiently with SymbOS.

By Manuel

Ascended (19811)

01-11-2021, 00:41

Yeah, sorry for the side tracking on your original post. Let's hope people will indeed get developing with this guide!

By ARTRAG

Enlighted (7003)

01-11-2021, 21:26

Very good !
Thanks

By NYYRIKKI

Enlighted (6127)

02-11-2021, 01:22

Manuel wrote:

Yeah, sorry for the side tracking on your original post.

That is not the problem, the problem was that I was not able to reduce my thoughts to correct high-level terms. Let me try again: The main problem is that we first need a C-compiler that supports the external linker that we also know as SymbOS,

Quote:

Let's hope people will indeed get developing with this guide!

I sure hope at least someone gets excited and something nice comes out of this... as otherwise I've just totally wasted few weeks of my free time for boring documentation, template & library refining tasks for nothing.

By Ped7g

Expert (68)

02-11-2021, 10:44

about sjasmplus warnings: if you are relocating from higher address (not "org $0000"), I don't think you should see any of those? (except when you deliberately read from the absolute $0000..$00FF address range) You can post some example if you run into it. Also you can disable that warning globally, but it shouldn't happen in the first place.

Stuff like `ld a,address/256` should be detected by relocation mode and warned about. Unfortunately SymbOS and sjasmplus does support only word-like relocation, but the assembler should at least warn about it, like this:
"warning[relunstable]: Relocation makes one of the expressions unstable, resulting machine code is not relocatable"

Either way, if you will experience some issue with sjasmplus, you know where to find me (just open issue on github ).

By NYYRIKKI

Enlighted (6127)

02-11-2021, 15:19

Ped7g wrote:

Exactly... In template I used org $1000 and this was one of the reasons.

Quote:

Yes, this was the warning I was talking about... So as practical example, if you do:
ld a,Label and 255
... you get a warning and you can safely ignore it, but if you do:
ld a,Label / 256
... the warning should be taken seriously.

Quote:

Either way, if you will experience some issue with sjasmplus, you know where to find me (just open issue on github ).

Yes, thank you! I must say that without your work we would not have today stuff like Doom:

... or I could not run BASIC on SymbOS:
https://www.youtube.com/watch?v=CZ_hk4MSPlg

It is really nice that we finally have a good standalone assembler to compile SymbOS applications!

By NYYRIKKI

Enlighted (6127)

03-11-2021, 01:10

We did some minor tweaks to the documentation together with Prodatron, so feel free to use the existing link to update to version 1.01 ... but you don't miss much even if you don't... It mostly concerns stack init where the details were a bit of a mess.

Ped7g wrote:

BTW I just realized that on SymbOS you can do this by adding the command as whole manually to the table... So practically writing something like "Relocate_this: ld a,label/256" and then adding "dw Relocate_this" just after "relocate_end"... The "relocate_size" should be then calculated in traditional (end-begin)/2 way though.

Is it kludge? Yes
Is it ugly? Yes
Will the assembler hate you? Yes
... but should get the job done.

I think I should move this talk to separate place though as these things are long long way from any beginner stuff... Even Prodatron got lost for a while when I tried to explain this idea.

By Ped7g

Expert (68)

03-11-2021, 10:19

Yep, that will work only if SymbOS does relocate only to 256-aligned addresses, which I guess it does.
The sjasmplus internal logic is full-word relocation, so it reports also stuff like `ld a,low(address)`, while that's constant in SymbOS even after relocation, if the 256-alignment is always enforced.

The kludge hack to tag only high byte can be also did this way... testing it a bit... ok, turns out to be more complicated than I expected, but will still post it just to give you one more perspective

 DEVICE NOSLOT64K ; must use any virtual device to make opcode rewrite possible
 ; output done by OUTPUT (write) is useless too, has to removed (would contain all bytes emitted)

 ; kludge itself, doing first relocatable word to get into table, then rewriting the position with `ld a,*`
  dw label : org $-2 : ld a,high(label) ; relunstable-ok

 ; hack to avoid relocation warning on lower byte (offset), if you know the relocation is 256-aligned
 ld a,low(label-Compile_Address) ; get offset from start of relocated block, making it relative -> no relocation needed

 ;...
 ; and output is extracted after everything is done from the virtual device memory
The_End:
 SAVEBIN "some.com", Compile_Address, The_End-Compile_Address

EDIT:
But you made me wonder, whether it would be worth to add 256-byte aligned relocation scheme to sjasmplus. Because ZX Next drivers use it too (the NextZXOS goes even one tiny step further... the relocation table contains +1 addresses pointing directly at high byte of those word values).

so then in 256B mode stuff like `ld a,low(label)` would produce no relocation data and no warning, and `ld a,high(label)` and `ld hl,label` would produce relocation data pointing directly at high byte, without warning about the high-byte only (which is wrong for SymbOS, but you can adjust it by adding offset to relocation table like `RELOCATE_TABLE 1` or `RELOCATE_TABLE -1` - never sure which way the offset works, sorry).

Sounds a bit useful, but heuristic to detect word/high-byte relocation will be maybe more complex... and maybe not... should be doable.

I have also seen ELF relocation possibilities somewhere in z88dk discussions, and those are way beyond this simple stuff, so I'm pretty sure I don't want to go there unless somebody has strong real use case. I know sometimes you can create it first and then somebody will figure out how to use it, but in this case it would be lot of work with unclear benefit. Anyway, getting offtopic now...

By AxelStone

Prophet (3209)

03-11-2021, 22:24

Thanks for your great SymbOS stuff NYYRIKKI. Are you planning to continue MSX or is it finished?