SmallBASIC Git

316 lines (214 with data), 9.1 kB

Porting SB to a new OS.
_______________________________________________________________________________
                                                           v2 - ndc, 11-03-2002

After the version 0.5.6 the SB can support more OSes.

The major part of the code is using itself. So, the SB needs a small 
set of OS routines. If you have a normal C library with malloc/free, 
open/read/write commands sets then your job will be easy.

The main SB code calls the routines on the device.c (which is actually
a shell for the OS driver). 

Example:
The RTL command CIRCLE will call the dev_circle() witch is located at
circle.c. 
The dev_circle() will call the dev_setpixel() from device.c which will
do some clipping and finaly it will call the osd_setpixel().

So, your actually job is to create the osd_setpixel().

There are two driver-shells, one for the devices (like display, mouse
and sound) and one for file system.


Info: SmallBASIC source code structure
_______________________________________________________________________________

[SmallBASIC code] 
	// generic device driver
	---> [device.c]
	     // low-level graphics driver 
	     +--> [dev_palm.c]
	     +--> or [dev_ndcfb.c]
	     +--> or [dev_x.c]
	     +--> or [dev_uvga.c]
	     +--> or [dev_sdl.c]
	     +--> ...

	     // add-on drivers 
	     +--> and/not [dev_oss.c] - OSS sound
	     +--> and/not [dev_gpm.c] - GPM mouse

	  // file system
	  ---> [file.c] --- files, virtual file systems
	     +--> [fs_stream.c] - classic file-streams

         // VFS = virtual file system
	     +--> [fs_serial.c] - serial I/O
	     +--> [fs_memo.c]   - MemoDB (PalmOS)
	     +--> ...

_______________________________________________________________________________

The final code (drivers) will be linked with the executable.

Examples of my Makefile:
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

unix_obj=brun.o scan.o ...

#
#	unix console/svgalib 
#	(dev_uvga.c is the driver, rom16.c is the font-data)
#
sbasic: $(unix_obj) dev_uvga.c unix/rom16.c
	gcc -g -D_UnixOS dev_uvga.c $(unix_obj) -o sbasic -lm -lvga -lvgagl

#
#	unix console/framebuffer
#	(dev_ufb.c is the driver)
#
fb_sbasic: $(unix_obj) dev_ufb.c
	gcc -g -D_UnixOS dev_ufb.c $(unix_obj) -o fb_sbasic -lm -lofbis

#
#	unix console/XWin
#	(dev_x.c is the driver)
#
xsbasic: $(unix_obj) dev_x.c
	gcc -g -D_UnixOS dev_x.c $(unix_obj) -o xsbasic -L/usr/X11/lib -lm -lX11 -lXext

>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>


Info: Generic framebuffer driver
_______________________________________________________________________________

This driver is a special case. 

Its a generic device driver which includes, lines, pixels, and
other routines for a memory block (virtual video-RAM)!
This is usefull because its easy to add a driver in minutes. You'll
only need to add routines for events and the osd_refresh().

The drivers dev_xf.c (XFree86), dev_dos (DOS/DJGPP direct access),
dev_ndcfb (Linux framebffer) are working with that.

The following parts must implement by you:

int		osd_devinit()	// initialization
{
	...
	// init & create virtual video ram
	gfb_init(dev_width, dev_height, dev_depth);	
	...
}

int		osd_devrestore()
{
	...
	// free virtual video ram
	gfb_close();
}

void	osd_refresh()
{
	// copy virtual video ram to real video ram
	memcpy(real_video_ram_address, gfb_vram(), gfb_vramsize());
}

// the events
void	osd_setpenmode(int enable);
int		osd_getpen(int code);
int		osd_events(int wait_flag);

That's all :)

The rest of the OSD API it is already exists in GFB.
(line, set/get pixel, print, gettext height/width, rect, setcolor, etc)

Also, this driver can use more than one video-pages.

byte	*gfb_alloc(void);		// create a new vram
byte	*gfb_clone(void);		// create a clone of the active vram
void	gfb_free(byte *buf);	// free vram
byte	*gfb_switch(byte *buf);	// set the active vram


Info: Add-on drivers
_______________________________________________________________________________

This is one another category of drivers. That kind of drivers can be
used with an other OSD driver.

Example:
The drivers for X and for FB are have no sound. So, we can link an
'add-on' driver for OSS (/dev/dsp).

See: dev_oss.c, dev_gpm.c


Info: Virtual file-system drivers
_______________________________________________________________________________

This is one another category of drivers. 
These drivers must support a specified API for file-system commands.
That API is described on file.c.

The commands OPEN,CLOSE,PRINT,INPUT can be used for read/write to
serial port, to pdoc files, to parallel, to memopad, etc

So, by implementing the basic I/O routines for the new device, SB
can use that device with the standard set of file commands.

See: fs_stream.c, fs_serial.c, fs_memo.c


More about drivers
_______________________________________________________________________________

More info about drivers can be found on DEVELOP.TXT


Starting to port
_______________________________________________________________________________

First you'll need a macro for the OS

Example: _NewOS

it will used at compile time

_______________________________________________________________________________

You'll need to specify the CPU and OS's feautures

sys.h:
#if defined(_PalmOS)
	...
#elif defined(_NewOS)
	... CPU FLAGS ...
	... OS FLAGS ...
#else
	...
#endif

For more info about the macros, read the remarks on sys.h
or take a look of the following text


sys.h: CPU's FLAGS
_______________________________________________________________________________

CPU_BIGENDIAN    --- The words are stored reversed;
                     first the low-byte followed by high-byte (Intel x86)

CPU_LITTLEENDIAN --- The words are stored normal; first the high-byte
                     followed by low-byte (Motorola 68K)

CPU_CODESEG64K   --- 64KB code size limit

CPU_REG16        --- 16bit registers (64KB code|data segments)
                     (there will be many problems with 64KB 
                     code+data segments)


sys.h: OS FLAGS
_______________________________________________________________________________

OS_NAME          --- OS name!
OS_LIMITED       --- Use few resources (use it for handhelds or DOS)

OS_ADDR16        --- Use 16bit memory address range
OS_ADDR32        --- Use 32bit memory address range

MALLOC_LIMITED   --- Limited systems without memory handles
                 
				 Its much much much faster than the original SB's
                 memory manager but its not keep tracks of memory leaks
                 or invalid pointers.

                 Use it on real OSes (like Unices) or on very limited 
                 OSes and only for the final release.

OS_DIRSEP        --- OS directory separator (unix=/, win=\\)
OS_PATHNAME_SIZE --- Maximum full-path name size (DOS=64,Unix/Win32=1024)
OS_FILENAME_SIZE --- Maximum filename size (DOS=12,Unix/Win32=256)


The driver for graphics & sound
_______________________________________________________________________________

Create the OS driver:

dev_newos.c:
             The implementation of osd.h routines
_______________________________________________________________________________

* DONE *

If your OS has no strange C-lib, then you have finished,
otherwise you'll need to do the next steps.


Non-compatible C library:
_______________________________________________________________________________


panic.c: system errors and warnings
_______________________________________________________________________________

	This is the first module to touch.
	There are two important versions.
	panic()   --> fatal error (prints a message and quit)
	warning() --> error/waring (prints a message 
	              and continue)


Memory manipulation routines
_______________________________________________________________________________

mem.c/unx_memmgr.c:

	mem.c is the basic memory routines (malloc/free).

	Slow systems or systems with few MBs of memory must do not use the
	unx_memmgr.c (memory manager).
    
	Without the unx_memmgr.c, the SB has no handle-style memory 
	routines. So, if your system does not supports memory handles,
	you'll need to add MALLOC_LIMITED (which is a very fast emulation
	of memory-handles by simply using malloc/free).


device.c:
_______________________________________________________________________________

That is the shell which is calling the OSD routines.
You'll need to made some modifications here.


fs_stream.c/fs_serial.c:
_______________________________________________________________________________

	File I/O, FileSystem Manager, Serial I/O


blib_func.c: system depended RTL functions
_______________________________________________________________________________

kwRND			- random numbers
kwFRE			- info about memory
kwTIMER			- seconds (and ticks)
kwTICKS			- ticks
kwTICKSPERSEC	- ticks per second
kwDATE			- date string
kwTIME			- time string


blib.c: system depended RTL procedures
_______________________________________________________________________________

cmd_randomize()	- random numbers