
SymbOS ASM-developer pack 1.0 Made By: NYYRIKKI (11/2021)
---------------------------------------------------------

So you wan't to become a SymbOS-developer, great! This OS will offer you great number of useful routines. I'm quite sure that when you get in to this stuff, you will learn to love this OS. It does not offer you only multitasking, but also other nice things like FAT32-support and networking... and here it is in a very user friendly package. Please read this file all the way as it teaches you how to navigate trough the official documentation. Personally I'm also quite n00b SymbOS developer coming from MSX background, but I want to help more people to join this great journey. Just two more classic words before we start:

	D O N ' T   P A N I C

The problem with official development stuff has been that it is drop to the deep end of the pool without learning to swim first. There are lot of sources available for really big, optimized and complex applications as well as this developer documentation that you don't really know where to start from... I think that it is pretty tempting to start reading the documentation in order Overview, Applications, Memory map, Desktop data records... but if you do just that I'm afraid that you will feel that you have landed on an alien planet and you want to quit even before you have compiled your first test program... This is why I made this developer package.

First of all, the tool that you need to compile your applications is SjAsmPlus and the version needs to be at least 1.16.0 Personally I have tested these examples on version 1.18.3. I hear you now say "but I want to use asMSX, Glass, traditional SjAsm, tniAsm, Pasmo..." but unfortunately you can't. For SymbOS development there are ATM only two powerfull enough assemblers to choose from and they are SjAsmPlus and WinAPE. From MSX user perspective using WinAPE feels a bit weird to me and it only works on Windows, so I've selected to make this package for SjAsmPlus that is a multi platform 3-pass assembler. These restrictions are caused by output that SymbOS needs to relocate your code to free memory area. As application developer this gives you few restrictions as well, but generally you can pretty safely close your eyes from this stuff. Usually SjAspPlus will warn you, if you have accidentally managed to do something not compatible. If the warning comes from low byte of certain memory address, you can safely ignore it.

In reality SymbOS is not much different from any other operating system. If you have already working routine that is not operating system specific, just copy/paste it to code area and it likely works ok as long as it does not disable interrupts or use exx or ex af,af' commands. You might be puzzled about the multitasking thing, but that is mostly OS problem, not yours. Only exception that I have found is the rare case of busy loops... If you ie. want to wait your interrupt counter to move forward (Interrupt routines are called timers in SymbOS) just add extra RST #30 to the loop and the code is fine again. The system will not hang even if it is missing, but you will see from task manager that your program uses 100% CPU time even when it is not doing anything useful and naturally this is pretty bad as other processes could be using that time more vicely.

Generally in learning there are two main ideologies: Those who like to work on high level and then dive in to details when needed and those who like to start from bottom and work their way up.

If you are a person who likes to work down from high level, you most likely already know Quigs-project (VisualBasic-style development environment for SymbOS that works on Windows) and now you want to dig in to assembly. The libraries included here were originally developped for Quigs, so using the skills learned from here in a Quigs-project should be pretty straight forward. (In documentation you may see SymStudio mentioned... This is former name of Quigs)

You should start by reading the HelloYou-Console and HelloYou-Window examples. These examples use the libraries instead of directly talking to the OS. The individual routines in libraries are included automatically to your project as you use them, so you should not need to be worried about explosion of your code size. The libraries work as your "BIOS". You set up the registers, call the routine and get data back in registers. The library files them self work as a documentation to you. There are commented explanations of input/output of each routine at start of it that also includes the "Name" that you can use to search correct location in appropriate service documentation, if you need to know more details about the parameters. Hopefully all of this will be transformed to hypertext or wiki some day by someone.

If you are a person who likes to work from bottom to up, then it is best you take a look of HelloYou-Window-Direct example... This will show you how you use kernel to send messages to other processes. (In this case Desktop and System) In SymbOS most of the outside world communication is just sending and receiving messages using RST-commands. Practically you put sender and receiver process ID to IX, point the message with IY and select the appropriate RST-command. The RST-commands them self are explained in kernel documentation (SymbOS-Kernel.txt). Besides messages there are also some functions, that might have direct address to call or you need to call them using Banking calls (also kernel RST-commands). In these cases the documentation has "How to call" that shows best available assembler commands to call the routine.

If you don't know what process you should talk to, take a quick peek to constants in LIB-folder. You can find the correct service and routine name from there. The separate text files of different processes clearly explains content of each message and you can use the name to search the documentation.

After reading the examples. seeking your way around documentation using these tips and understanding this concept go and read the application documentation and it all starts to make a lot more sense to you.

Few notes of vocabulary used in the documentation: Messages are described so that first there is offset from the message start, then lenght of the field (ie. 1B = 1 byte or 2W = 2 words) and then content. Sometimes the bytes in message are referrerred like "P2" that means content of offset 2 from the message start. Message based communication is usually called "commands" and banking call based communication as "functions"

Here is the list of current services and some of my notes about them:

Desktop Manager: (SymbOS-Desktop.txt)
-------------------------------------
"The desktop manager is responsible for all actions, which are taking place on
the video screen. Especially the handling of the application windows is done by
the desktop manager."

The messages may also contain pointers to data records that the OS handles for you. The format of these is explained in "SymbOS-DesktopDataRecords.txt". As the desktop windows are pretty complex entities, many times there are data records that point to data record that point to data records. This may feel a bit overwhelming, but it is good idea to read the provided example and compare it to descriptions to get overall understanding of what kind of information and features these records contain. In reality you likely want to mostly develop these data records in Quigs & maybe tweak them manually a bit as this will speed up the development quite a bit. More info about this on end of this file.

System Manager: (SymbOS-System.txt)
-----------------------------------
"The system manager is responsible for starting and stopping applications and
for general system jobs. It provides several dialogue services and it owns the
file manager, which can only be accessed via the system manager process"

I have no special notes about this one

File Manager (SymbOS-File.txt)
------------------------------

As the name suggests File Manager handles all file I/O on SymbOS

If you seek a routine from file manager documentation, you may be puzzled that it talks about registers instead of messages, but if you scroll all the way up, you will see that this is just a quirk in documentation as all file manager functions use common message template and these registers are given places on the message. This is why the message has not been explained on each function separately. This may not be in line with other documentation, but on the other hand it is very nice documentation style if you happen to use libraries. I guess this documentation difference is side effect caused by the fact that messages are routed trough System Manager.

Screen Manager (SymbOS-Screen.txt)
----------------------------------

Screen Manager is practically the video driver of SymbOS. Applications have very rarely any need to talk to it.

Device Manager (SymbOS-Device.txt)
----------------------------------

This process handles real time clock, mouse and keyboard. It also hadles screen modes.

Usually System Manager and Desktop Manager are the ones that talk to Device Manager, but sometimes application needs to know exactly if ie. certain key is really pushed down at the moment or not. Please note how ever that these routines talk directly to hardware. If you for example make a game, you most likely don't want random things to happen on your game while user is ie. writing text on Notepad, so in this kind of scenario you need to keep track of your Window focus messages and accept the results only if your application has focus.

Apart from these basic services there are few more things that you may want to talk to:

Network Daemon (SymbOS-Network.txt")
------------------------------------
"The SymbOS network daemon provides all services for full network access. It's
running as a shared service process."

This Daemon documentation seems to use similar standardized message type as File Manager does, so don't get confused by the registers.

SymShell text terminal (SymbOS-SymShell.txt)
--------------------------------------------
"The SymShell system application provides a program environment with a text
based user interface. Applications, which are working inside the SymShell
environment, can use terminal input and output routines for sending and
receiving text data to and from the standard console or another redirected
source and destination."

This is maybe most easy environment to start if you have some existing tool you want to port to SymbOS as it gives you environment close to ie. DOS or CP/M. The COM-files of SymShell have same structure as EXE-files. They are just associated to the shell program and use different routines to talk with this hosting shell. Naturally all other OS funtions are also usable.

Other applications
------------------
Naturally applications can talk with each other and that is practically how Daemons work... They are practically normal applications that wait messages from other applications. "Daemon" or "shared service process" only means there are some naming conventions that make sure SymbOS can start and stop them automatically according to usage. (More on System menager documentation)

Some last words:

The DOC-folder contains the latest official documentation. Therefore you can safely upgrade it from SymbOS.de if new features are implemented. The LIB-folder routines are modified versions of official WinAPE routines spiced up a bit, converted to SjAsmPlus directives and to my new naming system, so these might not be upgradeable so easy unless I convince Prodatron to move to using SjAsmPlus instead. :) The provided code template is complete rewrite of the original template where I have used more descriptive labels and overall more sraight forward approach.

If you are an MSX coder like me, then you might be interested about a special library that I added. It is called "SymbOS-Lib-MSX-Compatibility.asm". This library adds some famialiar looking routines you can call such as BDOS, CHGET & CHPUT and few readable labels like LINLEN and CRTCNT... These have restrictions, but should help porting applications over to SymbOS SymShell. If you are interested, there is more information on the file it self.

If you want to make a GUI-app then making the GUI Forms is very important part of the development... and it is hard & slow on text only assembler environment...  While writing this Quigs does not allow exporting forms, but such feature is planned. Before digging deeper in to this subject, check if the feature is already implemented in latest version.

Here are my current tips, how to steal the form data from Quigs project: (Note these are just overall hacking tips. The internal handling of forms on Quigs may change any time so you should not take these instructions too literally.)

When you compile ie. empty project with just form in Quigs, Quigs will save file called "form.asm" to "sys"-folder where you can then go and rip the form data to your project. Unfortunately the format of Quigs built it assembler is not quite compatible with SjAsmPlus. Few tips: Search "*** Z80 version of Form <form> ***" In my version the block started from label <form>_Begin and ended to label ".SyStud_TimerRoutines" very near the end of file. The string data in "**** Data Section ****" all started with ".<form>_". You need to remove all dots away (search / replace "." with "") and then make sure that "Equ" is witten all small or capitals. (search / replace "Equ" with "equ") There should not be DW-statements on beginning of line. (search / replace "dw" with " dw") Quigs adds extra cross reference and string length to front of strings, but if you don't mind, you can leave them as is... So quite a bit of tweaking required but it still wins making the data from scratch manually if your form is even a bit more complex. I hope it will get more easy soon.

I guess that was all that I wanted to say... Happy coding,

~NYYRIKKI (nyyrikki@gmail.com)
