Foenix F256 / Wildbits/K2 Wiki - User contributions [en]

Template:Main2/How To

2026-03-13T05:29:13Z

Jfed:

* [[Use the CODEC]]
* [[Use the K2 LCD]]
* [[Use the LEDs]]
* [[Use the OPL3 YMF262]]
* [[Use the PS/2 Mouse]]
* [[Use the PSG]]
* [[Use the Sam2695 Dream MIDI chip]]
* [[Use the SNES/NES controllers]]
* [[Use the VS1053b chip]]
* [[Use the Core2x]]
* [[Use the W6100]]

W6100

2026-03-13T05:27:47Z

Jfed: Jfed moved page W6100 to Use the W6100: Needed to match other names in the HowTo Section

#REDIRECT [[Use the W6100]]

Use the W6100

2026-03-13T05:27:47Z

Jfed: Jfed moved page W6100 to Use the W6100: Needed to match other names in the HowTo Section

= W6100 Registers =
{| class="wikitable"
|+Bit 3:1 for Control Register
!Bit [3:1]
!
|-
|000
|Write single Transfer
|-
|001
|Write Burst Transfer
|-
|010
|Write MR Register
|-
|011
|RESERVED
|-
|100
|Read Single Transfer
|-
|101
|Read Burst Transfer
|-
|110
|Read MR Register
|-
|111
|RESERVED
|}
{| class="wikitable"
|+Control Register
!Bit
!Description
|-
|0
|Enable - 0: Block is disabled - 1: Block is Enabled
|-
|1
|See Above for value
|-
|2
|See Above for value
|-
|3
|See Above for value
|-
|4
|Reset FIFOs
|-
|5
|Start Transfer
|-
|6
|Enable FIFO Empty/FIFO Full Interrupt
|-
|7
|Transfer in Progress
|}
{| class="wikitable"
|+W6100 Registers
!Address
!R
!Read Description
!W
!Write Description
|-
|$F018C0
|RW
| colspan="3" |Control Register
|-
|$F018C1
|RW
| colspan="3" |MR VAlue
|-
|$F018C2
|
| colspan="3" |
|-
|$F018C3
|RW
| colspan="3" |Single Access Port
|-
|$F018C4
|RW
| colspan="3" |WizNet Address Lo
|-
|$F018C5
|RW
| colspan="3" |WizNet Address Hi
|-
|$F018C6
|R
|Rx FIFO Quanity Lo
|W
|WizNet Transfer Size Lo
|-
|$F018C7
|R
|Rx FIFO Quanity Hi
|W
|WizNet Transfer Size Hi
|-
|$F018C8
|RW
| colspan="3" |FIFO Port
|}

Use the W6100

2026-03-13T05:07:29Z

Jfed: Initial Page

Use the K2 LCD

2026-03-13T01:34:17Z

Jfed: /* Registers */ Added CTRL Register

== The LCD is part of the F256K2 enclosure ==

The LCD embedded in the enclosure is Sitronix ST7789.
The full resolution is 240 pixels wide, 320 pixels high. However, there's a 20 pixel high band at the top and a 20 pixel high band at the bottom which are covered, so the visible usable part is 240x280.

Its datasheet can be found in a goodies github repo: https://github.com/Mu0n/F256MiscGoodies/blob/main/datasheets/ST7789V.pdf

=== Registers ===

{| class="wikitable"
|+
!Register Name
!Address
!Description
|-
|LCD_CMD_CMD
|0xDD40
|Write Command Here
|-
|LCD_CMD_DTA
|0xDD41
|Write Data (For Command) Here; Always Write in pairs (to LCD_PIX_LO and LCD_PIX_HI), otherwise the State Machine will Lock
|-
|LCD_PIX_LO
|0xDD42
|{G[2:0], B[4:0]} (see below in the Compatible image format section for clarity)
|-
|LCD_PIX_HI
|0xDD43
|{R[4:0], G[5:3]}
|-
|LCD_CTRL_REG
|0xDD44
|CTRL Register
|}

=== Sending a command using LCD_CMD_CMD ===

{| class="wikitable"
|+
!Command Name
!Value
!Description
|-
|LCD_RST
|0x10
|0 to Reset (RSTn)
|-
|LCD_BL
|0x20
|1 = ON, 0 = OFF
|-
|LCD_WIN_X
|0x2A
|define window X
|-
|LCD_WIN_Y
|0x2B
|define window Y
|-
|LCD_WRI
|0x2C
|put in memory write mode (pixel writing)
|-
|LCD_RD
|0x2E
|put in memory read mode
|-
|LCD_MAD
|0x36
|MADCTL register, which controls in which direction pixel writing occurs
|-
|LCD_TE
|0x40
|Enable tear mode - avoid updating the display while the controller reads its value
|}
{| class="wikitable"
|+MADCTL Value Bits
!Bit
!Mask
!Name
!Description
|-
|0
|$01
|
|Always 0
|-
|1
|$02
|
|Always 0
|-
|2
|$04
|MH
|Scan right to left
|-
|3
|$08
|RGB
|0 = RGB order, 1 = BGR
|-
|4
|$10
|ML
|Scan bottom to top
|-
|5
|$20
|MV
|Rotate display scan by 90°
|-
|6
|$40
|MX
|Read/write right to left
|-
|7
|$80
|MY
|Read/write bottom to top
|}
The process for sending a command goes as:

1) send the appropriate command byte to LCD_CMD_CMD

2) write all of your appropriate data byte, in the correct sequence according to the documentation, to LCD_CMD_DTA

Example 1, setting a rectangular region on the LCD to receive pixel writes and managing how 'pixel write carriage returns' behave:<pre>
//assuming an 8-bit value x and width and a 16-bit value y and height
POKE(LCD_CMD_CMD, LCD_WIN_X);
POKE(LCD_CMD_DTA, 0); //xstart high, this will always be 0 since the width is 240 pixels wide
POKE(LCD_CMD_DTA, x); //xstart low
POKE(LCD_CMD_DTA, 0); //xend high
POKE(LCD_CMD_DTA, x+width); //xend low

POKE(LCD_CMD_CMD, LCD_WIN_Y);
POKE(LCD_CMD_DTA, (y&0xFF00)); //ystart high
POKE(LCD_CMD_DTA, 20 + (y&0x00FF)); //ystart low
POKE(LCD_CMD_DTA, (y+height)&0x00FF); //yend high
POKE(LCD_CMD_DTA, (y+height)&0x00FF); //yend low
</pre>Example 2, set pixel writing in reverse in the Y direction<pre>
POKE(LCD_CMD_CMD, LCD_MAD);
POKE(LCD_CMD_DTA, 0x80);
</pre>Example 3, writing pixels<pre>
POKE(LCD_CMD_CMD, LCD_WRI); //only set this once at the start of writing pixel data and redo it if you needed to get sidetracked and did other types of commands
//start of your loop
POKEW(LCD_PIX_LO,PIXEL_IN_R5G6B5); //send a word at once
//end of your loop, only the pixels declared in the rectangular region from example 1 will be affected
</pre>

=== Compatible image format ===

You can send in a .bmp image exported in R5 G6 B5 color palette, converted into a raw 2 byte/per/pixel binary file.
The R5 G6 B5 palette expects color information in this format:
{| class="wikitable"
!High byte
!Low byte
|-
|<code>R4 R3 R2 R1 R0 G5 G4 G3</code>
|<code>G2 G1 G0 B4 B3 B2 B1 B0</code>
|}
The process goes as:

1) Use gimp (or equivalent alternative) and export your image that's using Indexed color mode as a 'Windows BMP Image'

2) During the export process, go to advanced options and select 16 bit, R5 G6 B5 for the color

3) run my python script 'bmp2LCD.py' to convert it to a raw binary found at https://github.com/Mu0n/F256MiscGoodies/tree/main in /tools/

4) for every pixel, send 2 bytes of data to the LCD_PIX_LO and LCD_PIX_HI registers found in the table above

5) you can find some example code from my [https://github.com/Mu0n/F256KsimpleCdoodles/blob/main/lcd/src/lcd.c C github repo here], which sends an image to the LCD screen and then idles.

FNX6809 GraphicsVTIOCalls

2026-01-16T17:34:01Z

Jfed: /* Basic09 Calls (via the Foenix module) */ Change FOENIX calls to WILD

== Graphics Summary ==
Use the <code>fstatus</code> command in Level 2 to see the current status of the graphics registers.

There is a default clut memory module included called <code>xtclut</code> in CMDS. This has the xterm colors according to [https://www.ditig.com/publications/256-colors-cheat-sheet this chart]

== Basic09 Calls (via the WILD module) ==

=== INKEY ===
calling syntax: RUN WILD([path,],"INKEY",keyval)

=== MouseHR ===
returns 640x480 XY

calling syntax: RUN WILD([path,],"MouseHR",X,Y,Button)

=== Mouse ===
returns 320x240 XY

calling syntax: RUN WILD([path,],"Mouse",X,Y,Button)

=== Graphics On ===
calling syntax: RUN WILD([path,],"Gon")

=== Graphics Off ===
calling syntax: RUN WILD([path,],"Goff")

=== BMLoad ===
Load Bitmap file into allocated Bitmap

calling syntax: RUN WILD([path,],"BMLoad",bmblock,bitmappath)

=== BMClear ===
Clear image of allocated Bitmap

calling syntax: RUN WILD([path,],"BMClear",bmblock, color)

=== Bitmap ===
Allocate bitmap

calling syntax: RUN WILD([path,],"Bitmap",bitmap#,screenmode,bmblock,layer,clut#,clutname)

=== BMSave ===
Save current Bitmap

calling syntax: RUN WILD([path,],"BMClear",bmblock, filename)

=== Bitmap Status ===
Returns 0 bm(x) if disabled, returns 1 bm(x) enabled

calling syntax: RUN WILD([path,],"BMstatus",bm0,bm1,bm2)

=== Bitmap Off/Free ===
Disables bitmap and frees bitmap memory

calling syntax: RUN WILD([path,],"BMoff",bitmap#)

=== GFree ===
Calling syntax: RUN WILD([path,],"GFree",bitmap#)

=== ClutFree ===
Clut Unlink

calling syntax: RUN WILD([path,],"ClutFree",clutheader)

=== Pixel ===
Draw Pixel

takes X,Y and color and puts it in the bitmap bmblock

x=X, y=Y, a=color

calling syntax: RUN WILD([path,],"Pixel",X,Y,Color,bmblock)

=== GetPixel ===
Return the color of pixel at x,y

takes X,Y and color and puts it in the bitmap bmblock

x=X, y=Y, a=color

calling syntax: RUN WILD([path,],"GetPixel",X,Y,Color,bmblock)

=== Line ===
draw line between 2 coordinates

x=16 bit value, y=8 bit value

pc=01 x=23 y=4 x=56 y=7 c=8

calling syntax: RUN WILD([path,],"Line",X1,Y1,X2,Y2,color,bmblock)

=== Multiply ===
Multiply 2 16 bit integers

Calling syntax: RUN WILD([path,],"MULTIPLY", integer_A, integer_B,result_REAL)

=== GetDow ===
Get Day of week

Returns integer day of week

Calling syntax: RUN WILD([path,] "GetDow", dow)

=== GetTime ===
Get the current time.

Calling syntax: RUN WILD([path,] "GetTime", hour,minute,seconds)

=== GetDate ===
Get the current time.

RTC.Base $FE40

Calling syntax: RUN WILD([path,] "GetDate", month,day,year)

=== WINFO ===
Get window information.

Calling syntax: RUN WILD([path,] "WINFO", format, width, height, foreground, background, border)

=== DWSET ===
Define a device window.

Calling syntax: RUN WILD([path,] "DWSET", format, xcor, ycor, width, height, foreground, background, border)

=== COLOR ===
Set the window colors.

Calling syntax: RUN WILD([path,] "COLOR", foreground [,background] [,border])

=== SEED ===
Seeds the hardware-based random number.

Calling syntax: RUN WILD([path,] "SEED" ,value)

=== RANDOM ===
Returns a hardware-based random number.

Calling syntax: RUN WILD([path,] "RANDOM" ,value)

=== CURHOME ===
Home the cursor.

Calling syntax: RUN WILD([path,] "CURHOME")

=== CURXY ===
Move the cursor to a column and row.

Calling syntax: RUN WILD([path,] "CURXY", column, row)

=== ERLINE ===
Delete the line of text the cursor is on.

Calling syntax: RUN WILD([path,] "ERLINE")

=== EREOLINE ===
Delete text from the cursor to the end of the current line.

Calling syntax: RUN WILD([path,] "EREOLINE")

=== CUROFF ===
Make the cursor invisible

Calling syntax: RUN WILD([path,] "CUROFF")

=== CURRGT ===
Move the cursor one character to the right.

Calling syntax: RUN WILD([path,] "CURRGT")

=== BELL ===
Produce a beep through the terminal's speaker.

Calling syntax: RUN WILD([path,] "BELL")

=== CURLFT ===
Move the cursor one character to the left.

Calling syntax: RUN WILD([path,] "CURLFT")

=== CURUP ===
Move the cursor one line up.

Calling syntax: RUN WILD([path,] "CURUP")

=== CURDWN ===
Move the cursor one line down.

Calling syntax: RUN WILD([path,] "CURDWN")

=== EREOWNDW ===
Delete text from the current cursor position to the end of the window.

Calling syntax: RUN WILD([path,] "EREOWNDW")

=== Clear ===
Calling syntax: RUN WILD([path,] "CLEAR")

=== CRRTN ===
Send a carriage return.

Calling syntax: RUN WILD([path,] "CRRTN")

=== INSLIN ===
Insert a blank line at the current cursor.

Calling syntax: RUN WILD([path,] "INSLIN")

=== DELLIN ===
Delete the line at the current cursor.

Calling syntax: RUN WILD([path,] "DELLIN")

=== DEFCOL ===
Set palette registers to the default values.

Calling syntax: RUN WILD([path,] "DEFCOL"

== vtio Get/Set Stat Calls ==

=== SS.AScrn ===

Allocate a bitmap screen

Entry: R$Y = bitmap# (0-2)
R$X = screentype (0=320x240, 1=320x200)

Exit: B = A non-zero error code.
CC = Carry flag clear to indicate success
X = Starting Page# of bitmap address

=== SS.DScrn ===
Display Screen Settings

Set MCR to display text or graphics or both

Entry: R$X = Vicky_MCR Low Byte
R$Y = Vicky_MCR High Byte

Exit: Nothing. This just sets the register and updates driver variables

VICKY MASTER CONTROL REGISTER to enable graphics and capabilities
| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
| X | GAMMA | SPRITE | TILE | BITMAP | GRAPH | OVRLY | TEXT |
| ----- | FON_SET|FON_OV| MON_SLP| DBL_Y | DBL_X | CLK70|
$FFC0 MASTER_CTRL_REG_L, MASTER_CTRL_REG_H

********************************************************************
* vtio graphics constants (in f256.d)
********************************************************************
* Constants used in SS.DScrn to set the display screen type

FX_GAM equ %01000000 Gamma Correction On
FX_SPR equ %00100000 Sprites On
FX_TIL equ %00010000 Tile Maps On
FX_BM equ %00001000 Bitmaps On
FX_GRF equ %00000100 Graphics Mode On
FX_OVR equ %00000010 Overlay Text on Graphics
FX_TXT equ %00000001 Text Mode On
FT_FSET equ %00100000 Font Set 1 On (0=Font Set 0)
FT_FOVR equ %00010000 FG and BG colors displayed when overlay text 0=transparent
FT_MON equ %00001000 Turn off monitor sync and sleep monitor
FT_DBX equ %00000100 Double-wide text mode characters
FT_DBY equ %00000010 Double-high text mode characters
FT_CLK70 equ %00000001 70 Hz screen (640x400 txt,320x200 grf)
FX_OMIT equ %11111111 Setting for SS.DScrn don't change first byte in MCR
FT_OMIT equ %11111111 Setting for SS.DScrn don't change second byte in MCR

=== SS.PScrn ===
Position Screen Layers

Set layer to display a screen

Entry: R$X = layer (0-2)
R$Y = bitmap# (0-2), tilemap (4-6)

Exit: B = A non-zero error code.
CC = Carry flag clear to indicate success

=== SS.FScrn ===

Free a bitmap screen

Entry: R$Y = bitmap# (0-2)

Exit: B = A non-zero error code.
CC = Carry flag clear to indicate success

=== SS.DfPal ===
Define Palette and populate a CLUT from Memory Module

Entry: R$X = CLUT # (0-3)
R$Y = pointer to location of data in caller process
(Caller must load data module)

Exit: B = A non-zero error code.
CC = Carry flag clear to indicate success

FNX6809 Manuals

2025-08-29T15:19:05Z

Jfed: /* Memory Map */ add new memory map to wiki

== MMU Registers ==
{| class="wikitable" style="text-align:center;"
|+
!Address
!R/W
!Name
!7
!6
!5
!4
!3
!2
!1
!0
|-
|$FFA0
|RW
|MMU_MEM_CTRL
| -
| -
| colspan="2" |EDIT_LUT
| -
| -
| colspan="2" |ACT_LUT
|-
|$FFA1
|RW
|MMU_IO_CTRL
| -
| -
| -
| -
| -
|
|$FFF0-$FFFF
Enable
|$FD00-$FDFF
Enable
|}

There are 4 MLUTs (MMU Lookup Tables).

'''ACT_LUT''' these two bits specify which MLUT (0–3) is used to translate CPU bus address to system bus addresses.

'''EDIT_LUT''' these two bits will specify which MLUT (0 - 3) is being edited and will appear in memory addresses $FFA8-$FFAF.

These locations are defined in nitros9/defs/f256.d:

MMU_MEM_CTRL equ $FFA0

MMU_IO_CTRL equ $FFA1

MMU_SLOT_0 equ $FFA8 $0000-$1FFF

MMU_SLOT_1 equ $FFA9 $2000-$3FFF

MMU_SLOT_2 equ $FFAA $4000-$5FFF

MMU_SLOT_3 equ $FFAB $6000-$7FFF

MMU_SLOT_4 equ $FFAC $8000-$9FFF

MMU_SLOT_5 equ $FFAD $A000-$BFFF

MMU_SLOT_6 equ $FFAE $C000-$DFFF

MMU_SLOT_7 equ $FFAF $E000-$FFFF

<nowiki>*</nowiki> MMU_IO_CTRL bits

<nowiki>*</nowiki> $FFA1 has 2 bits:

<nowiki>*</nowiki> FFA1[0] =

<nowiki>*</nowiki> 1 = Enable internal RAM for segment $FD00-$FDFF.

<nowiki>*</nowiki> 0 = Disable; RAM/FLASH is accessible.

<nowiki>*</nowiki>

<nowiki>*</nowiki> FFA1[1] =

<nowiki>*</nowiki> 1 = Enable internal RAM for segment $FFF0-$FFFF

<nowiki>*</nowiki> 0 = Disable; RAM/FLASH is accessible.

<nowiki>*</nowiki> When enabled, the areas supersede RAM/flash, but will be disabled by RESET. When the system resets,

<nowiki>*</nowiki> those regions revert to RAM/flash. Also at RESET, the contents of RAM retain the old values until the

<nowiki>*</nowiki> system powers off.

'''NOTE:''' If you are writing an OS-9 program, use <code>F$MapBlk</code> and <code>F$ClrBlk</code> instead of directly accessing these addresses. NitrOS-9 keeps track of each process' MMU LUT (but only if you use <code>F$MapBlk</code> and <code>F$ClrBlk</code>). Addressing the MMU directly can create unpredictable results.

== Memory Map ==
[[File:K2MemoryMap.png|frameless|818x818px]]

== Memory Model ==
[[File:FNX6809-MemoryModel Page 1.png|thumb|430x430px|FNX6809 Memory Model Page 1|none]]
[[File:FNX6809-MemoryModel Page 2.png|none|thumb|430x430px|FNX6809 Memory Model Page 2]]
__FORCETOC__

File:K2MemoryMap.png

2025-08-29T15:14:09Z

Jfed:

Memory Map as of 2025-08

Wiznet

2025-08-16T19:56:35Z

Jfed: /* Updating the firmware */

== WIZnet WizFi360 ==
This chip for wireless and wired networking is found in both the F256Jr.2 and F256K2.

== Updating the firmware ==

Note from Stef: apparently not all modules are updated equal (one thought that by buying the latest module would == Latest Firmware) but unfortunately it isn't the case.

1) Get a cable like this (USB to Serial Interface, DTECH 3ft 3.3V USB to TTL Serial Adapter Debug Cable TX RX Signal 4 Pin Female Socket PL2303 Prolific Chip Windows 10 8 7 XP Vista) https://www.amazon.ca/dp/B08G1JTN4N?ref_=ppx_hzsearch_conn_dt_b_fed_asin_title_1&th=1

2) Connect the cable the following way: <gallery>
File:Wizfi360 pins.png|The firmware updating pins near the CR2032 battery on the F256K2 (black revision) board
File:Wiznet connected.png|3 leads from USB cable connected on the SP2 pin header adjacent to the Wiznet chip
File:Jrjr-wizfi360-pins.png|Pins for the WizFi360 on the Jr.Jr.
</gallery>

3) Download the latest firmware from here: https://github.com/wizfi/Release/tree/master/Binary

4) Download the wizfi360 manual from: https://github.com/Mu0n/F256MiscGoodies/tree/main/datasheets

5) Download Tera Term 5 from: https://github.com/TeraTermProject/teraterm/releases

6) Follow the instruction in the manual page (page 4 and on)

Connect your cable
* White Lead to the SP2 3 pins Header (RxD) (next to the CR2032 battery)
* Black Lead to the middle post (gnd)
* Green lead to the third pin (TxD)
* Short the J16 empty header footprint and leave it there (CN1 on the Jr.Jr. - just below the WizFi header pins)

<gallery>
wizfi360_J16.png|The J16 header footprints are near the WizFi360 chip.
</gallery>

* In Tera Term, establish a Serial connection (according to the right COM port that is associated with this USB cable) and set it to 115,200
* In Tera Term, press and hold ESC
* Power On the unit
* You should see some 'CCCCC...' in Tera Term, let go of ESC when you do and remove the shorting cable from the J16 header footprint.
* then do a Xmodem transfer with latest firmware, wait until it tells you that the module is ready...
* Power off the unit
* Disconnect the cable
* It should be updated!

Wiznet

2025-08-16T19:53:47Z

Jfed:

== WIZnet WizFi360 ==
This chip for wireless and wired networking is found in both the F256Jr.2 and F256K2.

== Updating the firmware ==

Note from Stef: apparently not all modules are updated equal (one thought that by buying the latest module would == Latest Firmware) but unfortunately it isn't the case.

1) Get a cable like this (USB to Serial Interface, DTECH 3ft 3.3V USB to TTL Serial Adapter Debug Cable TX RX Signal 4 Pin Female Socket PL2303 Prolific Chip Windows 10 8 7 XP Vista) https://www.amazon.ca/dp/B08G1JTN4N?ref_=ppx_hzsearch_conn_dt_b_fed_asin_title_1&th=1

2) Connect the cable the following way: <gallery>
File:Wizfi360 pins.png|The firmware updating pins near the CR2032 battery on the F256K2 (black revision) board
File:Wiznet connected.png|3 leads from USB cable connected on the SP2 pin header adjacent to the Wiznet chip
File:Jrjr-wizfi360-pins.png|Pins for the WizFi360 on the Jr.Jr.
</gallery>

3) Download the latest firmware from here: https://github.com/wizfi/Release/tree/master/Binary

4) Download the wizfi360 manual from: https://github.com/Mu0n/F256MiscGoodies/tree/main/datasheets

5) Download Tera Term 5 from: https://github.com/TeraTermProject/teraterm/releases

6) Follow the instruction in the manual page (page 4 and on)

Connect your cable
* White Lead to the SP2 3 pins Header (RxD) (next to the CR2032 battery)
* Black Lead to the middle post (gnd)
* Green lead to the third pin (TxD)
* Short the J16 empty header footprint and leave it there

<gallery>
wizfi360_J16.png|The J16 header footprints are near the WizFi360 chip.
</gallery>

* In Tera Term, establish a Serial connection (according to the right COM port that is associated with this USB cable) and set it to 115,200
* In Tera Term, press and hold ESC
* Power On the unit
* You should see some 'CCCCC...' in Tera Term, let go of ESC when you do and remove the shorting cable from the J16 header footprint.
* then do a Xmodem transfer with latest firmware, wait until it tells you that the module is ready...
* Power off the unit
* Disconnect the cable
* It should be updated!

Wiznet

2025-08-16T19:50:09Z

Jfed: Added picture for pins for Jr.Jr.

== WIZnet WizFi360 ==
This chip for wireless and wired networking is found in both the F256Jr.2 and F256K2.

== Updating the firmware ==

Note from Stef: apparently not all modules are updated equal (one thought that by buying the latest module would == Latest Firmware) but unfortunately it isn't the case.

1) Get a cable like this (USB to Serial Interface, DTECH 3ft 3.3V USB to TTL Serial Adapter Debug Cable TX RX Signal 4 Pin Female Socket PL2303 Prolific Chip Windows 10 8 7 XP Vista) https://www.amazon.ca/dp/B08G1JTN4N?ref_=ppx_hzsearch_conn_dt_b_fed_asin_title_1&th=1

2) Connect the cable the following way: <gallery>
File:Index.php?title=File:Wizfi360 pins.png|The firmware updating pins near the CR2032 battery on the F256K2 (black revision) board
File:Index.php?title=File:Wiznet connected.png|3 leads from USB cable connected on the SP2 pin header adjacent to the Wiznet chip
File:Jrjr-wizfi360-pins.png|Pins for the WizFi360 on the Jr.Jr.
</gallery>

3) Download the latest firmware from here: https://github.com/wizfi/Release/tree/master/Binary

4) Download the wizfi360 manual from: https://github.com/Mu0n/F256MiscGoodies/tree/main/datasheets

5) Download Tera Term 5 from: https://github.com/TeraTermProject/teraterm/releases

6) Follow the instruction in the manual page (page 4 and on)

Connect your cable
* White Lead to the SP2 3 pins Header (RxD) (next to the CR2032 battery)
* Black Lead to the middle post (gnd)
* Green lead to the third pin (TxD)
* Short the J16 empty header footprint and leave it there

<gallery>
wizfi360_J16.png|The J16 header footprints are near the WizFi360 chip.
</gallery>

* In Tera Term, establish a Serial connection (according to the right COM port that is associated with this USB cable) and set it to 115,200
* In Tera Term, press and hold ESC
* Power On the unit
* You should see some 'CCCCC...' in Tera Term, let go of ESC when you do and remove the shorting cable from the J16 header footprint.
* then do a Xmodem transfer with latest firmware, wait until it tells you that the module is ready...
* Power off the unit
* Disconnect the cable
* It should be updated!

File:Jrjr-wizfi360-pins.png

2025-08-16T19:47:19Z

Jfed:

OS-9

2025-05-18T13:46:10Z

Jfed: Changes to add FoenixMgr configuration instructions

== Introduction ==
The FNX6809 combined with the F256 makes a great system for running OS-9/6809. [[wikipedia:OS-9|OS-9]] is a real-time, embedded operating system created by [[wikipedia:Microware|Microware Systems Corporation]]. While it was used in many areas of industry, home computer users know it best for its implementation on the [[wikipedia:TRS-80_Color_Computer|Tandy Color Computer]] sold by Radio Shack

Today, a community effort has led to the creation of [https://github.com/nitros9project/nitros9 NitrOS-9], an open source version of the OS-9 operating system. Throughout this page, I'll refer to NitrOS-9 as OS-9.

== A word about platforms ==
This page assumes you're running on Linux or macOS. If you're using Windows, these instructions don't apply, and someone will have to step up and write steps to develop on that platform.

== Tooling ==
Cross-hosted development is the fastest way to develop for the F256. For this you need the following:

* [http://www.lwtools.ca lwtools] - an assembler/linker package
* [https://github.com/nitros9project/toolshed ToolShed] - a set of tools for creating disk images
* [https://github.com/nitros9project/nitros9 NitrOS-9] - the NitrOS-9 operating system in source form
* [https://github.com/pweingar/FoenixMgr FoenixMgr] - tools to load code into RAM or Flash of the F256.

You can pull these down individually, or better yet, use [https://github.com/strickyak @strickyak]'s great [https://github.com/strickyak/coco-shelf/ CoCo Shelf repository]. It has a <code>Makefile</code> which gets all of the above and puts it in a convenient location (note that you'll have to update your shell script of choice to include the locations of the binaries in the <code>PATH</code> environment variable).

Here are the terminal commands for Linux and macOS to pull down all the required software:
cd
git clone <nowiki>https://github.com/strickyak/coco-shelf.git</nowiki>
cd coco-shelf
export PATH="$PATH:$HOME/coco-shelf/bin"
make ANON=1 nitros9/done FoenixMgr/done

(If you have a github account and your github ssh key is loaded,
you can omit `ANON=1` on the last command,
so it will check out git repositories using your github username,
in case you want to push changes.)

There is a special Make target for re-flashing the F256Jr or F256K,
but first time you run this command, it should fail.
Then you have to edit the `port=` line in `FoenixMgr/foenixmgr.ini`
and run the command again (with the cable plugged in):
make ANON=1 run-f256-flash # Old command for F256Jr that works?
or
make ANON=1 run-f256jr-flash # TODO fix this
or
make ANON=1 run-f256k-flash # TODO fix this

=== Configure FoenixMgr ===
The makefiles for f256 NitrOS-9 use the <code>bulk-flash</code> command from FoenixMgr. This command is in the <code>bin</code> directory of coco-shelf. The <code>bin</code> directory must be in your <code>PATH</code> in order for the flash procedure to work from the NitrOS-9 makefile. On linux, add a line to your <code>.profile</code> similar to:

PATH="$HOME/coco-shelf/bin:$PATH"

FoenixMgr's <code>foenixmgr.ini</code> file must also be configured with the correct port to flash the f256. The F256 Jr.Jr. and F256 K2 both have a USB-C serial port that requires no additional drivers. The F256 Jr. and F256-K have a USB debug port which requires a special driver to work. The procedure for the F256 Jr.Jr. and F256 K2: plug the usb cable to your computer and the F256 and turn on the F256. On linux, type lsusb to verify the connection. The output should show an FT4232 UART:

~/coco-shelf/FoenixMgr $ lsusb

Bus 002 Device 002: ID 174c:55aa ASMedia Technology Inc. ASM1051E SATA 6Gb/s bridge, ASM1053E SATA 6Gb/s bridge, ASM1153 SATA 3Gb/s bridge, ASM1153E SATA 6Gb/s bridge
Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
'''Bus 001 Device 017: ID 0403:6011 Future Technology Devices International, Ltd FT4232H Quad HS USB-UART/FIFO IC'''
Bus 001 Device 003: ID 248a:8367 Maxxter Telink Wireless Receiver
Bus 001 Device 002: ID 2109:3431 VIA Labs, Inc. Hub

Next change directory to coco-shelf/FoenixMgr and run python <code>FoenixMgr/FoenixMgr.py --list-ports</code>.

~/coco-shelf/FoenixMgr $ python FoenixMgr/fnxmgr.py --list-ports

++ python3 FoenixMgr/fnxmgr.py --list-ports
Description: n/a
Manufacturer: None
Product: None
/dev/ttyUSB3
Description: New Retro Computer - New Retro Computer
Manufacturer: Xilinx
Product: New Retro Computer
/dev/ttyUSB2
Description: New Retro Computer - New Retro Computer
Manufacturer: Xilinx
Product: New Retro Computer
/dev/ttyUSB1
Description: New Retro Computer - New Retro Computer
Manufacturer: Xilinx
Product: New Retro Computer
/dev/ttyUSB0</code>
Description: New Retro Computer - New Retro Computer
Manufacturer: Xilinx
Product: New Retro Computer

The second port,<code>/dev/ttyUSB1</code>, should be the correct port. Change the port line in <code>foenixmgr.ini</code> to this port and save it (you don't have to worry about the other settings):

~/coco-shelf/FoenixMgr/foenixmgr.ini

[DEFAULT]
'''port=/dev/ttyUSB1'''
labels=sample.lbl
flash_address=380000
chunk_size=1024
cpu=65816

FoenixMgr should now be configured to flash the <code>FEU</code>.

== Building FEU and OS-9 Level 1 from scratch ==
FEU is the Foenix Executive Utility. It resides in flash and hosts a debugger and booters that can bring up operating systems like OS-9. FEU runs under OS-9 Level 1, so go ahead and build the entire operating system:
cd nitros9
export NITROS9DIR=$PWD
cd level1/f256
make
cd feu
Now you can flash the image into the F256. You must have a USB cable connected to the system from your computer. Note: if you're using a Mac, you won't be able to upload code into the F256 due to the [https://www.maxlinear.com/support/design-tools/software-drivers driver manufacturer] being so behind on updates. You can use a Linux VM and FoenixMgr tools in bridge mode on the Mac.

There are distinct builds of FEU for the F256 Jr and the F256K. Power up the machine, then select the correct command:
cd feu
make flash_f256jr
or
cd feu
make flash_f256k

Then (this is in addition to make flash_f256jr or make flash_f256k):

make flash_f0

Once the flash completes, restart the machine and FEU should come up.

== Building OS-9 Level 2 ==
To build OS-9 Level 2, run these commands (this assumes you have added the NITROS9DIR environment variable as above: export NITROS9DIR=$PWD from the top level nitros9 directory):
cd ../../level2/f256
make dsk

This produces the following disk images for the F256 Jr and the F256K:

NOS9_6809_L2_v030300_f256jr_dw.dsk
NOS9_6809_L2_v030300_f256jr_sd.dsk
NOS9_6809_L2_v030300_f256k_dw.dsk
NOS9_6809_L2_v030300_f256k_sd.dsk

The ''dw'' disk images are for booting from DriveWire. The ''sd'' disk image are for booting from the SD card. You need to write the images onto an SD card, then insert the SD card into the F256 and restart.

Here's how to image the SD card.

==== Linux ====
On Linux, insert the SD card into your computer. Ttype <code>lsblk</code> to find the correct device and replace ''sdx'' on the command line below with it:

dd if=NOS9_6809_L2_v030300_f256k_sd.dsk of=/dev/''sdx''

==== macOS ====
On macOS, insert the SD card into your Mac. A dialog will likely appear telling you that the disk you attached isn't readable. Click the "ignore" button, then type <code>diskutil list external</code> to obtain the device name of the SD card and replace ''diskx'' on the command line below with it:
sudo dd if=NOS9_6809_L2_v030300_f256k_sd.dsk of=/dev/''diskx''
Once the command completes, type:
diskutil eject /dev/''diskx''
You can then safely remove the SD card.

OS-9

2025-05-18T13:23:40Z

Jfed: /* Tooling */ Add configuring FoenixMgr

== Introduction ==
The FNX6809 combined with the F256 makes a great system for running OS-9/6809. [[wikipedia:OS-9|OS-9]] is a real-time, embedded operating system created by [[wikipedia:Microware|Microware Systems Corporation]]. While it was used in many areas of industry, home computer users know it best for its implementation on the [[wikipedia:TRS-80_Color_Computer|Tandy Color Computer]] sold by Radio Shack

Today, a community effort has led to the creation of [https://github.com/nitros9project/nitros9 NitrOS-9], an open source version of the OS-9 operating system. Throughout this page, I'll refer to NitrOS-9 as OS-9.

== A word about platforms ==
This page assumes you're running on Linux or macOS. If you're using Windows, these instructions don't apply, and someone will have to step up and write steps to develop on that platform.

== Tooling ==
Cross-hosted development is the fastest way to develop for the F256. For this you need the following:

* [http://www.lwtools.ca lwtools] - an assembler/linker package
* [https://github.com/nitros9project/toolshed ToolShed] - a set of tools for creating disk images
* [https://github.com/nitros9project/nitros9 NitrOS-9] - the NitrOS-9 operating system in source form
* [https://github.com/pweingar/FoenixMgr FoenixMgr] - tools to load code into RAM or Flash of the F256.

You can pull these down individually, or better yet, use [https://github.com/strickyak @strickyak]'s great [https://github.com/strickyak/coco-shelf/ CoCo Shelf repository]. It has a <code>Makefile</code> which gets all of the above and puts it in a convenient location (note that you'll have to update your shell script of choice to include the locations of the binaries in the <code>PATH</code> environment variable).

Here are the terminal commands for Linux and macOS to pull down all the required software:
cd
git clone <nowiki>https://github.com/strickyak/coco-shelf.git</nowiki>
cd coco-shelf
export PATH="$PATH:$HOME/coco-shelf/bin"
make ANON=1 nitros9/done FoenixMgr/done

(If you have a github account and your github ssh key is loaded,
you can omit `ANON=1` on the last command,
so it will check out git repositories using your github username,
in case you want to push changes.)

There is a special Make target for re-flashing the F256Jr or F256K,
but first time you run this command, it should fail.
Then you have to edit the `port=` line in `FoenixMgr/foenixmgr.ini`
and run the command again (with the cable plugged in):
make ANON=1 run-f256-flash # Old command for F256Jr that works?
or
make ANON=1 run-f256jr-flash # TODO fix this
or
make ANON=1 run-f256k-flash # TODO fix this

=== Configure FoenixMgr ===
The makefiles for f256 NitrOS-9 use the <code>bulk-flash</code> command from FoenixMgr. This command is in the <code>bin</code> directory of coco-shelf. The <code>bin</code> directory must be in your <code>PATH</code> in order for the flash procedure to work from the NitrOS-9 makefile. On linux, you can add a line to your <code>.profile</code> similar to:

<code>PATH="$HOME/coco-shelf/bin:$PATH"</code>

FoenixMgr's <code>foenixmgr.ini</code> file must also be configured with the correct port to flash the f256. The F256 Jr.Jr. and F256 K2 both have a USB-C serial port that requires no additional drivers. The F256 Jr. and F256-K have a USB debug port which requires a special driver to work. The procedure for the F256 Jr.Jr. and F256 K2: plug the usb cable to your computer and the F256 and turn on the F256. On linux, type lsusb to verify the connection. The output should show an FT4232 UART:

<code>~/coco-shelf/FoenixMgr $ lsusb</code>

<code>Bus 002 Device 002: ID 174c:55aa ASMedia Technology Inc. ASM1051E SATA 6Gb/s bridge, ASM1053E SATA 6Gb/s bridge, ASM1153 SATA 3Gb/s bridge, ASM1153E SATA 6Gb/s bridge</code>

<code>Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub</code>

<code>B'''us 001 Device 017: ID 0403:6011 Future Technology Devices International, Ltd FT4232H Quad HS USB-UART/FIFO IC'''</code>

<code>Bus 001 Device 003: ID 248a:8367 Maxxter Telink Wireless Receiver</code>

<code>Bus 001 Device 002: ID 2109:3431 VIA Labs, Inc. Hub</code>

Next change directory to coco-shelf/FoenixMgr and run python <code>FoenixMgr/FoenixMgr.py --list-ports</code>.

<code>~/projects/coco-shelf/FoenixMgr $ python FoenixMgr/fnxmgr.py --list-ports</code>

<code>++ python3 FoenixMgr/fnxmgr.py --list-ports</code>

<code>/dev/ttyS0</code>

<code> Description: n/a</code>

<code> Manufacturer: None</code>

<code> Product: None</code>

<code>/dev/ttyUSB3</code>

<code> Description: New Retro Computer - New Retro Computer</code>

<code> Manufacturer: Xilinx</code>

<code> Product: New Retro Computer</code>

<code>/dev/ttyUSB2</code>

<code> Description: New Retro Computer - New Retro Computer</code>

<code> Manufacturer: Xilinx</code>

<code> Product: New Retro Computer</code>

<code>/dev/ttyUSB1</code>

<code> Description: New Retro Computer - New Retro Computer</code>

<code> Manufacturer: Xilinx</code>

<code> Product: New Retro Computer</code>

<code>/dev/ttyUSB0</code>

<code> Description: New Retro Computer - New Retro Computer</code>

<code> Manufacturer: Xilinx</code>

<code> Product: New Retro Computer</code>

The second port,<code>/dev/ttyUSB1</code>, should be the correct port. Change the port line in <code>foenixmgr.ini</code> to this port and save it (you don't have to worry about the other settings):

<code>~/coco-shelf/FoenixMgr/foenixmgr.ini</code>

<code>[DEFAULT]</code>

<code>port=/dev/ttyUSB1</code>

<code>labels=sample.lbl</code>

<code>flash_address=380000</code>

<code>chunk_size=1024</code>

<code>cpu=65816</code>

FoenixMgr should now be configured to flash the <code>FEU</code>.

== Building FEU and OS-9 Level 1 from scratch ==
FEU is the Foenix Executive Utility. It resides in flash and hosts a debugger and booters that can bring up operating systems like OS-9. FEU runs under OS-9 Level 1, so go ahead and build the entire operating system:
cd nitros9
export NITROS9DIR=$PWD
cd level1/f256
make
cd feu
Now you can flash the image into the F256. You must have a USB cable connected to the system from your computer. Note: if you're using a Mac, you won't be able to upload code into the F256 due to the [https://www.maxlinear.com/support/design-tools/software-drivers driver manufacturer] being so behind on updates. You can use a Linux VM and FoenixMgr tools in bridge mode on the Mac.

There are distinct builds of FEU for the F256 Jr and the F256K. Power up the machine, then select the correct command:
cd feu
make flash_f256jr
or
cd feu
make flash_f256k

Then (this is in addition to make flash_f256jr or make flash_f256k):

make flash_f0

Once the flash completes, restart the machine and FEU should come up.

== Building OS-9 Level 2 ==
To build OS-9 Level 2, run these commands (this assumes you have added the NITROS9DIR environment variable as above: export NITROS9DIR=$PWD from the top level nitros9 directory):
cd ../../level2/f256
make dsk

This produces the following disk images for the F256 Jr and the F256K:

NOS9_6809_L2_v030300_f256jr_dw.dsk
NOS9_6809_L2_v030300_f256jr_sd.dsk
NOS9_6809_L2_v030300_f256k_dw.dsk
NOS9_6809_L2_v030300_f256k_sd.dsk

The ''dw'' disk images are for booting from DriveWire. The ''sd'' disk image are for booting from the SD card. You need to write the images onto an SD card, then insert the SD card into the F256 and restart.

Here's how to image the SD card.

==== Linux ====
On Linux, insert the SD card into your computer. Ttype <code>lsblk</code> to find the correct device and replace ''sdx'' on the command line below with it:

dd if=NOS9_6809_L2_v030300_f256k_sd.dsk of=/dev/''sdx''

==== macOS ====
On macOS, insert the SD card into your Mac. A dialog will likely appear telling you that the disk you attached isn't readable. Click the "ignore" button, then type <code>diskutil list external</code> to obtain the device name of the SD card and replace ''diskx'' on the command line below with it:
sudo dd if=NOS9_6809_L2_v030300_f256k_sd.dsk of=/dev/''diskx''
Once the command completes, type:
diskutil eject /dev/''diskx''
You can then safely remove the SD card.

FNX6809 GraphicsVTIOCalls

2025-01-25T20:51:17Z

Jfed: /* Bitmap Off/Free */

== Graphics Summary ==
Use the <code>fstatus</code> command in Level 2 to see the current status of the graphics registers.

There is a default clut memory module included called <code>xtclut</code> in CMDS. This has the xterm colors according to [https://www.ditig.com/publications/256-colors-cheat-sheet this chart]

== Basic09 Calls (via the Foenix module) ==

=== INKEY ===
calling syntax: RUN FOENIX([path,],"INKEY",keyval)

=== MouseHR ===
returns 640x480 XY

calling syntax: RUN FOENIX([path,],"MouseHR",X,Y,Button)

=== Mouse ===
returns 320x240 XY

calling syntax: RUN FOENIX([path,],"Mouse",X,Y,Button)

=== Graphics On ===
calling syntax: RUN FOENIX([path,],"Gon")

=== Graphics Off ===
calling syntax: RUN FOENIX([path,],"Goff")

=== BMLoad ===
Load Bitmap file into allocated Bitmap

calling syntax: RUN FOENIX([path,],"BMLoad",bmblock,bitmappath)

=== BMClear ===
Clear image of allocated Bitmap

calling syntax: RUN FOENIX([path,],"BMClear",bmblock, color)

=== Bitmap ===
Allocate bitmap

calling syntax: RUN FOENIX([path,],"Bitmap",bitmap#,screenmode,bmblock,layer,clut#,clutname)

=== BMSave ===
Save current Bitmap

calling syntax: RUN FOENIX([path,],"BMClear",bmblock, filename)

=== Bitmap Status ===
Returns 0 bm(x) if disabled, returns 1 bm(x) enabled

calling syntax: RUN FOENIX([path,],"BMstatus",bm0,bm1,bm2)

=== Bitmap Off/Free ===
Disables bitmap and frees bitmap memory

calling syntax: RUN FOENIX([path,],"BMoff",bitmap#)

=== GFree ===
Calling syntax: RUN FOENIX([path,],"GFree",bitmap#)

=== ClutFree ===
Clut Unlink

calling syntax: RUN FOENIX([path,],"ClutFree",clutheader)

=== Pixel ===
Draw Pixel

takes X,Y and color and puts it in the bitmap bmblock

x=X, y=Y, a=color

calling syntax: RUN FOENIX([path,],"Pixel",X,Y,Color,bmblock)

=== GetPixel ===
Return the color of pixel at x,y

takes X,Y and color and puts it in the bitmap bmblock

x=X, y=Y, a=color

calling syntax: RUN FOENIX([path,],"GetPixel",X,Y,Color,bmblock)

=== Line ===
draw line between 2 coordinates

x=16 bit value, y=8 bit value

pc=01 x=23 y=4 x=56 y=7 c=8

calling syntax: RUN FOENIX([path,],"Line",X1,Y1,X2,Y2,color,bmblock)

=== Multiply ===
Multiply 2 16 bit integers

Calling syntax: RUN FOENIX([path,],"MULTIPLY", integer_A, integer_B,result_REAL)

=== GetDow ===
Get Day of week

Returns integer day of week

Calling syntax: RUN FOENIX([path,] "GetDow", dow)

=== GetTime ===
Get the current time.

Calling syntax: RUN FOENIX([path,] "GetTime", hour,minute,seconds)

=== GetDate ===
Get the current time.

RTC.Base $FE40

Calling syntax: RUN FOENIX([path,] "GetDate", month,day,year)

=== WINFO ===
Get window information.

Calling syntax: RUN FOENIX([path,] "WINFO", format, width, height, foreground, background, border)

=== DWSET ===
Define a device window.

Calling syntax: RUN FOENIX([path,] "DWSET", format, xcor, ycor, width, height, foreground, background, border)

=== COLOR ===
Set the window colors.

Calling syntax: RUN FOENIX([path,] "COLOR", foreground [,background] [,border])

=== SEED ===
Seeds the hardware-based random number.

Calling syntax: RUN FOENIX([path,] "SEED" ,value)

=== RANDOM ===
Returns a hardware-based random number.

Calling syntax: RUN FOENIX([path,] "RANDOM" ,value)

=== CURHOME ===
Home the cursor.

Calling syntax: RUN FOENIX([path,] "CURHOME")

=== CURXY ===
Move the cursor to a column and row.

Calling syntax: RUN FOENIX([path,] "CURXY", column, row)

=== ERLINE ===
Delete the line of text the cursor is on.

Calling syntax: RUN FOENIX([path,] "ERLINE")

=== EREOLINE ===
Delete text from the cursor to the end of the current line.

Calling syntax: RUN FOENIX([path,] "EREOLINE")

=== CUROFF ===
Make the cursor invisible

Calling syntax: RUN FOENIX([path,] "CUROFF")

=== CURRGT ===
Move the cursor one character to the right.

Calling syntax: RUN FOENIX([path,] "CURRGT")

=== BELL ===
Produce a beep through the terminal's speaker.

Calling syntax: RUN FOENIX([path,] "BELL")

=== CURLFT ===
Move the cursor one character to the left.

Calling syntax: RUN FOENIX([path,] "CURLFT")

=== CURUP ===
Move the cursor one line up.

Calling syntax: RUN FOENIX([path,] "CURUP")

=== CURDWN ===
Move the cursor one line down.

Calling syntax: RUN FOENIX([path,] "CURDWN")

=== EREOWNDW ===
Delete text from the current cursor position to the end of the window.

Calling syntax: RUN FOENIX([path,] "EREOWNDW")

=== Clear ===
Calling syntax: RUN FOENIX([path,] "CLEAR")

=== CRRTN ===
Send a carriage return.

Calling syntax: RUN FOENIX([path,] "CRRTN")

=== INSLIN ===
Insert a blank line at the current cursor.

Calling syntax: RUN FOENIX([path,] "INSLIN")

=== DELLIN ===
Delete the line at the current cursor.

Calling syntax: RUN FOENIX([path,] "DELLIN")

=== DEFCOL ===
Set palette registers to the default values.

Calling syntax: RUN FOENIX([path,] "DEFCOL"

== vtio Get/Set Stat Calls ==

=== SS.AScrn ===

Allocate a bitmap screen

Entry: R$Y = bitmap# (0-2)
R$X = screentype (0=320x240, 1=320x200)

Exit: B = A non-zero error code.
CC = Carry flag clear to indicate success
X = Starting Page# of bitmap address

=== SS.DScrn ===
Display Screen Settings

Set MCR to display text or graphics or both

Entry: R$X = Vicky_MCR Low Byte
R$Y = Vicky_MCR High Byte

Exit: Nothing. This just sets the register and updates driver variables

VICKY MASTER CONTROL REGISTER to enable graphics and capabilities
| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
| X | GAMMA | SPRITE | TILE | BITMAP | GRAPH | OVRLY | TEXT |
| ----- | FON_SET|FON_OV| MON_SLP| DBL_Y | DBL_X | CLK70|
$FFC0 MASTER_CTRL_REG_L, MASTER_CTRL_REG_H

********************************************************************
* vtio graphics constants (in f256.d)
********************************************************************
* Constants used in SS.DScrn to set the display screen type

FX_GAM equ %01000000 Gamma Correction On
FX_SPR equ %00100000 Sprites On
FX_TIL equ %00010000 Tile Maps On
FX_BM equ %00001000 Bitmaps On
FX_GRF equ %00000100 Graphics Mode On
FX_OVR equ %00000010 Overlay Text on Graphics
FX_TXT equ %00000001 Text Mode On
FT_FSET equ %00100000 Font Set 1 On (0=Font Set 0)
FT_FOVR equ %00010000 FG and BG colors displayed when overlay text 0=transparent
FT_MON equ %00001000 Turn off monitor sync and sleep monitor
FT_DBX equ %00000100 Double-wide text mode characters
FT_DBY equ %00000010 Double-high text mode characters
FT_CLK70 equ %00000001 70 Hz screen (640x400 txt,320x200 grf)
FX_OMIT equ %11111111 Setting for SS.DScrn don't change first byte in MCR
FT_OMIT equ %11111111 Setting for SS.DScrn don't change second byte in MCR

=== SS.PScrn ===
Position Screen Layers

Set layer to display a screen

Entry: R$X = layer (0-2)
R$Y = bitmap# (0-2), tilemap (4-6)

Exit: B = A non-zero error code.
CC = Carry flag clear to indicate success

=== SS.FScrn ===

Free a bitmap screen

Entry: R$Y = bitmap# (0-2)

Exit: B = A non-zero error code.
CC = Carry flag clear to indicate success

=== SS.DfPal ===
Define Palette and populate a CLUT from Memory Module

Entry: R$X = CLUT # (0-3)
R$Y = pointer to location of data in caller process
(Caller must load data module)

Exit: B = A non-zero error code.
CC = Carry flag clear to indicate success

FNX6809 GraphicsVTIOCalls

2025-01-25T20:09:43Z

Jfed: Added additional B09 calls

== Graphics Summary ==
Use the <code>fstatus</code> command in Level 2 to see the current status of the graphics registers.

There is a default clut memory module included called <code>xtclut</code> in CMDS. This has the xterm colors according to [https://www.ditig.com/publications/256-colors-cheat-sheet this chart]

== Basic09 Calls (via the Foenix module) ==

=== INKEY ===
calling syntax: RUN FOENIX([path,],"INKEY",keyval)

=== MouseHR ===
returns 640x480 XY

calling syntax: RUN FOENIX([path,],"MouseHR",X,Y,Button)

=== Mouse ===
returns 320x240 XY

calling syntax: RUN FOENIX([path,],"Mouse",X,Y,Button)

=== Graphics On ===
calling syntax: RUN FOENIX([path,],"Gon")

=== Graphics Off ===
calling syntax: RUN FOENIX([path,],"Goff")

=== BMLoad ===
Load Bitmap file into allocated Bitmap

calling syntax: RUN FOENIX([path,],"BMLoad",bmblock,bitmappath)

=== BMClear ===
Clear image of allocated Bitmap

calling syntax: RUN FOENIX([path,],"BMClear",bmblock, color)

=== Bitmap ===
Allocate bitmap

calling syntax: RUN FOENIX([path,],"Bitmap",bitmap#,screenmode,bmblock,layer,clut#,clutname)

=== BMSave ===
Save current Bitmap

calling syntax: RUN FOENIX([path,],"BMClear",bmblock, filename)

=== Bitmap Status ===
Returns 0 bm(x) if disabled, returns 1 bm(x) enabled

calling syntax: RUN FOENIX([path,],"BMstatus",bm0,bm1,bm2)

=== Bitmap Off/Free ===
calling syntax: RUN FOENIX([path,],"BMoff",bitmap#)

=== GFree ===
Calling syntax: RUN FOENIX([path,],"GFree",bitmap#)

=== ClutFree ===
Clut Unlink

calling syntax: RUN FOENIX([path,],"ClutFree",clutheader)

=== Pixel ===
Draw Pixel

takes X,Y and color and puts it in the bitmap bmblock

x=X, y=Y, a=color

calling syntax: RUN FOENIX([path,],"Pixel",X,Y,Color,bmblock)

=== GetPixel ===
Return the color of pixel at x,y

takes X,Y and color and puts it in the bitmap bmblock

x=X, y=Y, a=color

calling syntax: RUN FOENIX([path,],"GetPixel",X,Y,Color,bmblock)

=== Line ===
draw line between 2 coordinates

x=16 bit value, y=8 bit value

pc=01 x=23 y=4 x=56 y=7 c=8

calling syntax: RUN FOENIX([path,],"Line",X1,Y1,X2,Y2,color,bmblock)

=== Multiply ===
Multiply 2 16 bit integers

Calling syntax: RUN FOENIX([path,],"MULTIPLY", integer_A, integer_B,result_REAL)

=== GetDow ===
Get Day of week

Returns integer day of week

Calling syntax: RUN FOENIX([path,] "GetDow", dow)

=== GetTime ===
Get the current time.

Calling syntax: RUN FOENIX([path,] "GetTime", hour,minute,seconds)

=== GetDate ===
Get the current time.

RTC.Base $FE40

Calling syntax: RUN FOENIX([path,] "GetDate", month,day,year)

=== WINFO ===
Get window information.

Calling syntax: RUN FOENIX([path,] "WINFO", format, width, height, foreground, background, border)

=== DWSET ===
Define a device window.

Calling syntax: RUN FOENIX([path,] "DWSET", format, xcor, ycor, width, height, foreground, background, border)

=== COLOR ===
Set the window colors.

Calling syntax: RUN FOENIX([path,] "COLOR", foreground [,background] [,border])

=== SEED ===
Seeds the hardware-based random number.

Calling syntax: RUN FOENIX([path,] "SEED" ,value)

=== RANDOM ===
Returns a hardware-based random number.

Calling syntax: RUN FOENIX([path,] "RANDOM" ,value)

=== CURHOME ===
Home the cursor.

Calling syntax: RUN FOENIX([path,] "CURHOME")

=== CURXY ===
Move the cursor to a column and row.

Calling syntax: RUN FOENIX([path,] "CURXY", column, row)

=== ERLINE ===
Delete the line of text the cursor is on.

Calling syntax: RUN FOENIX([path,] "ERLINE")

=== EREOLINE ===
Delete text from the cursor to the end of the current line.

Calling syntax: RUN FOENIX([path,] "EREOLINE")

=== CUROFF ===
Make the cursor invisible

Calling syntax: RUN FOENIX([path,] "CUROFF")

=== CURRGT ===
Move the cursor one character to the right.

Calling syntax: RUN FOENIX([path,] "CURRGT")

=== BELL ===
Produce a beep through the terminal's speaker.

Calling syntax: RUN FOENIX([path,] "BELL")

=== CURLFT ===
Move the cursor one character to the left.

Calling syntax: RUN FOENIX([path,] "CURLFT")

=== CURUP ===
Move the cursor one line up.

Calling syntax: RUN FOENIX([path,] "CURUP")

=== CURDWN ===
Move the cursor one line down.

Calling syntax: RUN FOENIX([path,] "CURDWN")

=== EREOWNDW ===
Delete text from the current cursor position to the end of the window.

Calling syntax: RUN FOENIX([path,] "EREOWNDW")

=== Clear ===
Calling syntax: RUN FOENIX([path,] "CLEAR")

=== CRRTN ===
Send a carriage return.

Calling syntax: RUN FOENIX([path,] "CRRTN")

=== INSLIN ===
Insert a blank line at the current cursor.

Calling syntax: RUN FOENIX([path,] "INSLIN")

=== DELLIN ===
Delete the line at the current cursor.

Calling syntax: RUN FOENIX([path,] "DELLIN")

=== DEFCOL ===
Set palette registers to the default values.

Calling syntax: RUN FOENIX([path,] "DEFCOL"

== vtio Get/Set Stat Calls ==

=== SS.AScrn ===

Allocate a bitmap screen

Entry: R$Y = bitmap# (0-2)
R$X = screentype (0=320x240, 1=320x200)

Exit: B = A non-zero error code.
CC = Carry flag clear to indicate success
X = Starting Page# of bitmap address

=== SS.DScrn ===
Display Screen Settings

Set MCR to display text or graphics or both

Entry: R$X = Vicky_MCR Low Byte
R$Y = Vicky_MCR High Byte

Exit: Nothing. This just sets the register and updates driver variables

VICKY MASTER CONTROL REGISTER to enable graphics and capabilities
| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
| X | GAMMA | SPRITE | TILE | BITMAP | GRAPH | OVRLY | TEXT |
| ----- | FON_SET|FON_OV| MON_SLP| DBL_Y | DBL_X | CLK70|
$FFC0 MASTER_CTRL_REG_L, MASTER_CTRL_REG_H

********************************************************************
* vtio graphics constants (in f256.d)
********************************************************************
* Constants used in SS.DScrn to set the display screen type

FX_GAM equ %01000000 Gamma Correction On
FX_SPR equ %00100000 Sprites On
FX_TIL equ %00010000 Tile Maps On
FX_BM equ %00001000 Bitmaps On
FX_GRF equ %00000100 Graphics Mode On
FX_OVR equ %00000010 Overlay Text on Graphics
FX_TXT equ %00000001 Text Mode On
FT_FSET equ %00100000 Font Set 1 On (0=Font Set 0)
FT_FOVR equ %00010000 FG and BG colors displayed when overlay text 0=transparent
FT_MON equ %00001000 Turn off monitor sync and sleep monitor
FT_DBX equ %00000100 Double-wide text mode characters
FT_DBY equ %00000010 Double-high text mode characters
FT_CLK70 equ %00000001 70 Hz screen (640x400 txt,320x200 grf)
FX_OMIT equ %11111111 Setting for SS.DScrn don't change first byte in MCR
FT_OMIT equ %11111111 Setting for SS.DScrn don't change second byte in MCR

=== SS.PScrn ===
Position Screen Layers

Set layer to display a screen

Entry: R$X = layer (0-2)
R$Y = bitmap# (0-2), tilemap (4-6)

Exit: B = A non-zero error code.
CC = Carry flag clear to indicate success

=== SS.FScrn ===

Free a bitmap screen

Entry: R$Y = bitmap# (0-2)

Exit: B = A non-zero error code.
CC = Carry flag clear to indicate success

=== SS.DfPal ===
Define Palette and populate a CLUT from Memory Module

Entry: R$X = CLUT # (0-3)
R$Y = pointer to location of data in caller process
(Caller must load data module)

Exit: B = A non-zero error code.
CC = Carry flag clear to indicate success

FNX6809 GraphicsVTIOCalls

2025-01-25T19:53:07Z

Jfed: /* GFRee */

FNX6809 GraphicsVTIOCalls

2025-01-25T19:50:46Z

Jfed: Add Basic09 calls

FNX6809 DisplayCodes

2024-12-14T22:34:02Z

Jfed:

== Current List of Display Code for Nitros9 vtio: ==

* $00: NO-OP (null)
* $01: HOME cursor
* $02: CURSOR XY
* $03: ERASE LINE
* $04: CLEAR TO EOL
* $05: CURSOR ON/OFF/CHARACTER/RATE ($05 $21 / $05 $20 / $05 $22 XX / $05 $23 XX)
* $06: CURSOR RIGHT
* $07: BELL
* $08: CURSOR LEFT
* $09: CURSOR UP
* $0A: CURSOR DOWN
* $0B: ERASE TO EOS
* $0C: CLEAR SCREEN
* $0D: RETURN

* 1F 20 Turns on reverse video
* 1F 21 Turns off reverse video

== Escape Codes ==

* 1B 20 DW Set
* 1B 21 DW Select
* 1B 24 DW End
* 1B 30 DefColr
* 1B 32 Foreground Color
* 1B 33 Background Color
* 1B 34 Border Color
* 1B 60 Change Foreground Palette
* 1B 61 Change Background Palette
* 1B 62 Change to Font0
* 1B 63 Change to Font1

FNX6809 DisplayCodes

2024-12-14T22:30:20Z

Jfed: /* Current List of Display Code for Nitros9 vtio: */

== Current List of Display Code for Nitros9 vtio: ==

* $00: NO-OP (null)
* $01: HOME cursor
* $02: CURSOR XY
* $03: ERASE LINE
* $04: CLEAR TO EOL
* $05: CURSOR ON/OFF ($05 $21 / $05 $20)
* $06: CURSOR RIGHT
* $07: BELL
* $08: CURSOR LEFT
* $09: CURSOR UP
* $0A: CURSOR DOWN
* $0B: ERASE TO EOS
* $0C: CLEAR SCREEN
* $0D: RETURN

* 1F 20 Turns on reverse video
* 1F 21 Turns off reverse video

== Escape Codes ==

* 1B 20 DW Set
* 1B 21 DW Select
* 1B 24 DW End
* 1B 30 DefColr
* 1B 32 Foreground Color
* 1B 33 Background Color
* 1B 34 Border Color
* 1B 60 Change Foreground Palette
* 1B 61 Change Background Palette
* 1B 62 Change to Font0
* 1B 63 Change to Font1

FNX6809 DisplayCodes

2024-12-14T22:29:34Z

Jfed: /* Current List of Display Code for Nitros9 vtio: */

== Current List of Display Code for Nitros9 vtio: ==

* $00: NO-OP (null)
* $01: HOME cursor
* $02: CURSOR XY
* $03: ERASE LINE
* $04: CLEAR TO EOL
* $05: CURSOR ON/OFF
* $06: CURSOR RIGHT
* $07: BELL
* $08: CURSOR LEFT
* $09: CURSOR UP
* $0A: CURSOR DOWN
* $0B: ERASE TO EOS
* $0C: CLEAR SCREEN
* $0D: RETURN

* 1F 20 Turns on reverse video
* 1F 21 Turns off reverse video

== Escape Codes ==

* 1B 20 DW Set
* 1B 21 DW Select
* 1B 24 DW End
* 1B 30 DefColr
* 1B 32 Foreground Color
* 1B 33 Background Color
* 1B 34 Border Color
* 1B 60 Change Foreground Palette
* 1B 61 Change Background Palette
* 1B 62 Change to Font0
* 1B 63 Change to Font1

FNX6809 DisplayCodes

2024-12-14T22:28:04Z

Jfed: /* Current List of Display Code for Nitros9 vtio: */

== Current List of Display Code for Nitros9 vtio: ==

* $00: NO-OP (null)
* $01: HOME cursor
* $02: CURSOR XY
* $03: ERASE LINE
* $04: CLEAR TO EOL
* $05: CURSOR CONTROL
* $06: CURSOR RIGHT
* $07: BELL
* $08: CURSOR LEFT
* $09: CURSOR UP
* $0A: CURSOR DOWN
* $0B: ERASE TO EOS
* $0C: CLEAR SCREEN
* $0D: RETURN

* 1F 20 Turns on reverse video
* 1F 21 Turns off reverse video

== Escape Codes ==

* 1B 20 DW Set
* 1B 21 DW Select
* 1B 24 DW End
* 1B 30 DefColr
* 1B 32 Foreground Color
* 1B 33 Background Color
* 1B 34 Border Color
* 1B 60 Change Foreground Palette
* 1B 61 Change Background Palette
* 1B 62 Change to Font0
* 1B 63 Change to Font1

Template:Main2/FNX6809 Processor

2024-12-14T21:25:43Z

Jfed:

'''FNX6809 Processor'''
* [[FNX6809 Overview]]
* [[OS-9]]
* [[OS-9 Assembly Code Development]]
* [[OS-9_C_Code_Development|OS-9 C Code Development]]
* [[FNX6809_Manuals|FNX6809 Manuals]]
* [[FNX6809_GraphicsVTIOCalls|FNX6809 Graphics vtio calls]]
* [[FNX6809_DisplayCodes|FNX6809 Display Codes]]

FNX6809 DisplayCodes

2024-12-14T21:20:51Z

Jfed: Created page with "== Current List of Display Code for Nitros9 vtio: == * $00: NO-OP (null) * $01: HOME cursor * $02: CURSOR XY * $03: ERASE LINE * $04: CLEAR TO EOL * $05: CURSOR CONTROL * $06: CURSOR RIGHT * $07: BELL * $08: CURSOR LEFT * $09: CURSOR UP * $0A: CURSOR DOWN * $0B: ERASE TO EOS * $0C: CLEAR SCREEN * $0D: RETURN * 1F 20 Turns on reverse video * 1F 21 Turns off reverse video * 1F 22 Turns on underlining. * 1F 23 Turns off underlining. * 1F 24 Turns on blinking. * 1F 25 Turn..."

== Current List of Display Code for Nitros9 vtio: ==

* $00: NO-OP (null)
* $01: HOME cursor
* $02: CURSOR XY
* $03: ERASE LINE
* $04: CLEAR TO EOL
* $05: CURSOR CONTROL
* $06: CURSOR RIGHT
* $07: BELL
* $08: CURSOR LEFT
* $09: CURSOR UP
* $0A: CURSOR DOWN
* $0B: ERASE TO EOS
* $0C: CLEAR SCREEN
* $0D: RETURN

* 1F 20 Turns on reverse video
* 1F 21 Turns off reverse video
* 1F 22 Turns on underlining.
* 1F 23 Turns off underlining.
* 1F 24 Turns on blinking.
* 1F 25 Turns off blinking.
* 1F 30 Inserts a line at the current cursor position.
* 1F 31 Deletes the current line.

== Escape Codes ==

* 1B 20 DW Set
* 1B 21 DW Select
* 1B 24 DW End
* 1B 30 DefColr
* 1B 32 Foreground Color
* 1B 33 Background Color
* 1B 34 Border Color
* 1B 60 Change Foreground Palette
* 1B 61 Change Background Palette
* 1B 62 Change to Font0
* 1B 63 Change to Font1

OS-9

2024-10-22T13:01:10Z

Jfed: /* Building OS-9 Level 2 */

OS-9

2024-10-22T13:00:31Z

Jfed: /* Building OS-9 Level 2 */

OS-9

2024-10-22T12:53:51Z

Jfed:

OS-9

2024-10-22T12:52:16Z

Jfed: /* Building FEU and OS-9 Level 1 from scratch */

OS-9 Assembly Code Development

2024-10-08T11:43:35Z

Jfed: /* Single Source File Format */

== Overview ==
Each process in NitrOS-9 is allocated its own 64K address space. When run, the program object code is loaded into the end of the memory space, and the variables and data structures are loaded into the beginning. In addition, NitrOS-9 keeps an separate per-process MMU table (DAT Image), so you must use <code>F$MapBlk</code> to map and <code>F$ClrBlk</code> to unmap 8K blocks in your process' address space. The operating system has its own 64K address space as well.

When a new process is created, registers U, Y, DP and SP are set with U = start of data area, Y = end of data area, DP = page # of beginning page, SP = end of data area + 1. Each process includes its own execution and data directories, along with <code>std in</code>, <code>std out</code> and <code>std err</code>.

=== Memory and DAT Image ===
<code>mmap</code> and <code>pmap</code> output the current status of the memory in the system. <code>mmap</code> shows which memory blocks are currently in use. <code>pmap</code> shows the blocks that are mapped in the DAT Image for a particular process.
[[File:Mmappmap.png|none|thumb]]

== Program and Data Module Structure ==

There are 9 different types of modules in 4 possible languages:
{| class="wikitable"
|+
! colspan="3" |Module Types
!
! colspan="2" |Language
|-
|'''Code'''
|'''Module Type'''
|'''Name'''
|
|'''Code'''
|'''Language'''
|-
|$1x
|Program Module
|Prgm
|
|$x0
|Data (non-executable)
|-
|$2x
|Subroutine Module
|Sbrtn
|
|$x1
|6809 Object Code
|-
|$3x
|Multi-module
|Multi
|
|$x2
|BASIC09 I-Code
|-
|$4x
|Data Module
|Data
|
|$x3
|PASCAL I-Code
|-
|$5x-$Bx
|User-definable module
|
|
|$x4-$xF
|Reserved for Future Use
|-
|$Cx
|OS-9 System Module
|Systm
|
|
|
|-
|$Dx
|OS-9 File Manager Module
|FlMgr
|
|
|
|-
|$Ex
|OS-9 Device Driver Module
|Drivr
|
|
|
|-
|$Fx
|OS-9 Device Descriptor Module
|Devic
|
|
|
|}
The two most used will be Program Modules and Data Modules.

=== Program Modules ===
The format of a program module varies depending on whether you have a single source file for your program or multiple source files.

Note: multiple source files format cannot use direct page addressing due to the way they are compiled.

==== Single Source File Format ====
The following is a skeleton for a single source file memory module (program).
<code>********************************************************************</code>
<code>* [Program Name]</code>
<code>* [Description]</code>
<code>*</code>
<code>* by [Author Name]</code>
<code>*</code>
<code>* Edt/Rev YYYY/MM/DD Modified by</code>
<code>* Comment</code>
<code>* ------------------------------------------------------------------</code>
<code> nam [executablename]</code>
<code> ttl [Full Program Name]</code>

<code> ifp1</code>
<code> use defsfile</code>
<code> endc</code>

<code>tylg set Prgrm+Objct</code>
<code>atrv set ReEnt+rev</code>
<code>rev set $00</code>
<code>edition set 1</code>

<code> '''mod eom,name,tylg,atrv,start,size'''</code>

<code> [Data Section - Variables and Data Structures Here]</code>

<code>size equ .</code>
<code>name fcs /[executablename]/</code>
<code> fcb edition</code>

<code>start</code>

<code> [Program Section - Program Code Here]</code>
<code> </code>
<code> os9 F$Exit</code>

<code> '''emod'''</code>
<code>eom equ *</code>
<code> end</code>
OS9 can load programs (modules) only if they are in module header format. A module (program) is defined between the '''mod''' and '''emod''' pseudo instructions.

* '''mod:''' Creates the module header and starts CRC check. '''mod''' has 6 attributes:

# Module size (computed from the ''eom'' label at the end of the code - 2 bytes)
# Module name offset (offset where the string of the name is contained, here that is defined at the ''name'' label with the ''fcs'' pseudo instruction - 2 bytes
# Module type & language (in this case a Program in 6809 object code - 1 byte)
# Module attribute-revision (1 byte). Attributes are reentrant (ReEnt) or not reentrant (0). Revision is a number 0-15. If two or more modules with the same name are in the module directory, then OS-9 only keeps the highest revision number module.
# Module execution offset (here that is defined with the ''start'' label - 2 bytes)
# Module variable storage size (defined by the ''size'' label immediately after the variable area, includes stack space - 2 bytes)

* '''emod''': Outputs the correct 3 byte CRC. This is generated by the assembler over the entire module.

For more information about memory modules, see OS-9 Fundamentals:

[https://www.youtube.com/watch?v=YpoqTyrty8k OS-9 Fundamentals on YouTube by Boisy Pitre]

==== Multiple Source File Format ====

=== Data Modules ===
Here is a portion of the font module, which is a data module in NitrOS-9.

<code> nam font</code>
<code> ttl F256 font</code>
</code>
<code> use defsfile</code>
</code>
<code>tylg set Data</code>
<code>atrv set ReEnt+rev</code>
<code>rev set $01</code>
</code>
<code> mod eom,name,tylg,atrv,start,0</code>
<code>name fcs /font/</code>
</code>
<code>start</code>
<code>L0000 fcb $00,$00,$00,$00,$00,$00,$00,$00 </code>
<code>L0008 fcb $7C,$82,$AA,$82,$BA,$92,$82,$7C </code>
</code>
<code>*More data here</code>
</code>
<code> emod</code>
<code>eom equ *</code>
<code> end</code>

== Writing Position Independent Code ==
All code in NitrOS-9 must be position independent. Addresses are not known until a program module is loaded and executed. All addressing must be "program counter relative addressing". All branch and long branch instructions are program counter relative.

Rules:

Use <code>BRA</code> and <code>LBRA</code> instead of <code>JMP</code>

Use <code>BSR</code> and <code>LBSR</code> instead of <code>JSR</code>

Use program counter relative indexed addressing for all load, store, arithmetic and logical instructions.

== Accessing Variables and Data Structures ==

== Accessing Table Data with PCR ==
__FORCETOC__

OS-9 C Code Development

2024-10-08T11:13:48Z

Jfed: /* Cross-Compiler Development */

=Cross-Compiler Development=

See also the NitrOS-9 wiki on [https://github.com/nitros9project/nitros9/wiki/Writing-your-first-C-Program-for-NitrOS%E2%80%909 Writing your first C Program].
=Native Development=

Template:Main2/FNX6809 Processor

2024-10-08T11:07:46Z

Jfed:

OS-9 C Code Development

2024-10-08T11:05:48Z

Jfed: Created page with "=Cross-Compiler Development= =Native Development="

=Cross-Compiler Development=

=Native Development=

FNX6809 GraphicsVTIOCalls

2024-10-06T16:51:16Z

Jfed: /* Graphics Summary */

FNX6809 GraphicsVTIOCalls

2024-10-06T16:42:13Z

Jfed: /* Graphics Summary */

== Graphics Summary ==
Use the <code>fstatus</code> command in Level 2 to see the current status of the graphics registers.

== vtio Get/Set Stat Calls ==

=== SS.AScrn ===

Allocate a bitmap screen

Entry: R$Y = bitmap# (0-2)
R$X = screentype (0=320x240, 1=320x200)

Exit: B = A non-zero error code.
CC = Carry flag clear to indicate success
X = Starting Page# of bitmap address

=== SS.DScrn ===
Display Screen Settings

Set MCR to display text or graphics or both

Entry: R$X = Vicky_MCR Low Byte
R$Y = Vicky_MCR High Byte

Exit: Nothing. This just sets the register and updates driver variables

VICKY MASTER CONTROL REGISTER to enable graphics and capabilities
| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
| X | GAMMA | SPRITE | TILE | BITMAP | GRAPH | OVRLY | TEXT |
| ----- | FON_SET|FON_OV| MON_SLP| DBL_Y | DBL_X | CLK70|
$FFC0 MASTER_CTRL_REG_L, MASTER_CTRL_REG_H

********************************************************************
* vtio graphics constants (in f256.d)
********************************************************************
* Constants used in SS.DScrn to set the display screen type

FX_GAM equ %01000000 Gamma Correction On
FX_SPR equ %00100000 Sprites On
FX_TIL equ %00010000 Tile Maps On
FX_BM equ %00001000 Bitmaps On
FX_GRF equ %00000100 Graphics Mode On
FX_OVR equ %00000010 Overlay Text on Graphics
FX_TXT equ %00000001 Text Mode On
FT_FSET equ %00100000 Font Set 1 On (0=Font Set 0)
FT_FOVR equ %00010000 FG and BG colors displayed when overlay text 0=transparent
FT_MON equ %00001000 Turn off monitor sync and sleep monitor
FT_DBX equ %00000100 Double-wide text mode characters
FT_DBY equ %00000010 Double-high text mode characters
FT_CLK70 equ %00000001 70 Hz screen (640x400 txt,320x200 grf)
FX_OMIT equ %11111111 Setting for SS.DScrn don't change first byte in MCR
FT_OMIT equ %11111111 Setting for SS.DScrn don't change second byte in MCR

=== SS.PScrn ===
Position Screen Layers

Set layer to display a screen

Entry: R$X = layer (0-2)
R$Y = bitmap# (0-2), tilemap (4-6)

Exit: B = A non-zero error code.
CC = Carry flag clear to indicate success

=== SS.FScrn ===

Free a bitmap screen

Entry: R$Y = bitmap# (0-2)

Exit: B = A non-zero error code.
CC = Carry flag clear to indicate success

=== SS.DfPal ===
Define Palette and populate a CLUT from Memory Module

Entry: R$X = CLUT # (0-3)
R$Y = pointer to location of data in caller process
(Caller must load data module)

Exit: B = A non-zero error code.
CC = Carry flag clear to indicate success

Template:Main2/FNX6809 Processor

2024-10-06T16:32:27Z

Jfed:

'''FNX6809 Processor'''
* [[FNX6809 Overview]]
* [[OS-9]]
* [[OS-9 Assembly Code Development]]
* [[FNX6809_Manuals|FNX6809 Manuals]]
* [[FNX6809_GraphicsVTIOCalls|FNX6809 Graphics vtio calls]]

FNX6809 GraphicsVTIOCalls

2024-10-06T16:19:06Z

Jfed:

== Graphics Summary ==

== vtio Get/Set Stat Calls ==

=== SS.AScrn ===

Allocate a bitmap screen

Entry: R$Y = bitmap# (0-2)
R$X = screentype (0=320x240, 1=320x200)

Exit: B = A non-zero error code.
CC = Carry flag clear to indicate success
X = Starting Page# of bitmap address

=== SS.DScrn ===
Display Screen Settings

Set MCR to display text or graphics or both

Entry: R$X = Vicky_MCR Low Byte
R$Y = Vicky_MCR High Byte

Exit: Nothing. This just sets the register and updates driver variables

VICKY MASTER CONTROL REGISTER to enable graphics and capabilities
| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
| X | GAMMA | SPRITE | TILE | BITMAP | GRAPH | OVRLY | TEXT |
| ----- | FON_SET|FON_OV| MON_SLP| DBL_Y | DBL_X | CLK70|
$FFC0 MASTER_CTRL_REG_L, MASTER_CTRL_REG_H

********************************************************************
* vtio graphics constants (in f256.d)
********************************************************************
* Constants used in SS.DScrn to set the display screen type

FX_GAM equ %01000000 Gamma Correction On
FX_SPR equ %00100000 Sprites On
FX_TIL equ %00010000 Tile Maps On
FX_BM equ %00001000 Bitmaps On
FX_GRF equ %00000100 Graphics Mode On
FX_OVR equ %00000010 Overlay Text on Graphics
FX_TXT equ %00000001 Text Mode On
FT_FSET equ %00100000 Font Set 1 On (0=Font Set 0)
FT_FOVR equ %00010000 FG and BG colors displayed when overlay text 0=transparent
FT_MON equ %00001000 Turn off monitor sync and sleep monitor
FT_DBX equ %00000100 Double-wide text mode characters
FT_DBY equ %00000010 Double-high text mode characters
FT_CLK70 equ %00000001 70 Hz screen (640x400 txt,320x200 grf)
FX_OMIT equ %11111111 Setting for SS.DScrn don't change first byte in MCR
FT_OMIT equ %11111111 Setting for SS.DScrn don't change second byte in MCR

=== SS.PScrn ===
Position Screen Layers

Set layer to display a screen

Entry: R$X = layer (0-2)
R$Y = bitmap# (0-2), tilemap (4-6)

Exit: B = A non-zero error code.
CC = Carry flag clear to indicate success

=== SS.FScrn ===

Free a bitmap screen

Entry: R$Y = bitmap# (0-2)

Exit: B = A non-zero error code.
CC = Carry flag clear to indicate success

=== SS.DfPal ===
Define Palette and populate a CLUT from Memory Module

Entry: R$X = CLUT # (0-3)
R$Y = pointer to location of data in caller process
(Caller must load data module)

Exit: B = A non-zero error code.
CC = Carry flag clear to indicate success

FNX6809 GraphicsVTIOCalls

2024-10-06T16:17:35Z

Jfed: Created page with "== Graphics Summary == == vtio Get/Set Stat Calls == === SS.AScrn === Allocate a bitmap screen Entry: R$Y = bitmap# (0-2) R$X = screentype (0=320x240, 1=320x200) Exit: B = A non-zero error code. CC = Carry flag clear to indicate success X = Starting Page# of bitmap address === SS.DScrn === Display Screen Settings Set MCR to display text or graphics or both Entry: R$X = Vicky_MCR Low Byte R$Y = Vicky_MCR High Byte Exit: Nothin..."

OS-9 Assembly Code Development

2024-10-01T04:18:33Z

Jfed: /* Single Source File Format */

== Overview ==
Each process in NitrOS-9 is allocated its own 64K address space. When run, the program object code is loaded into the end of the memory space, and the variables and data structures are loaded into the beginning. In addition, NitrOS-9 keeps an separate per-process MMU table (DAT Image), so you must use <code>F$MapBlk</code> to map and <code>F$ClrBlk</code> to unmap 8K blocks in your process' address space. The operating system has its own 64K address space as well.

When a new process is created, registers U, Y, DP and SP are set with U = start of data area, Y = end of data area, DP = page # of beginning page, SP = end of data area + 1. Each process includes its own execution and data directories, along with <code>std in</code>, <code>std out</code> and <code>std err</code>.

=== Memory and DAT Image ===
<code>mmap</code> and <code>pmap</code> output the current status of the memory in the system. <code>mmap</code> shows which memory blocks are currently in use. <code>pmap</code> shows the blocks that are mapped in the DAT Image for a particular process.
[[File:Mmappmap.png|none|thumb]]

== Program and Data Module Structure ==

There are 9 different types of modules in 4 possible languages:
{| class="wikitable"
|+
! colspan="3" |Module Types
!
! colspan="2" |Language
|-
|'''Code'''
|'''Module Type'''
|'''Name'''
|
|'''Code'''
|'''Language'''
|-
|$1x
|Program Module
|Prgm
|
|$x0
|Data (non-executable)
|-
|$2x
|Subroutine Module
|Sbrtn
|
|$x1
|6809 Object Code
|-
|$3x
|Multi-module
|Multi
|
|$x2
|BASIC09 I-Code
|-
|$4x
|Data Module
|Data
|
|$x3
|PASCAL I-Code
|-
|$5x-$Bx
|User-definable module
|
|
|$x4-$xF
|Reserved for Future Use
|-
|$Cx
|OS-9 System Module
|Systm
|
|
|
|-
|$Dx
|OS-9 File Manager Module
|FlMgr
|
|
|
|-
|$Ex
|OS-9 Device Driver Module
|Drivr
|
|
|
|-
|$Fx
|OS-9 Device Descriptor Module
|Devic
|
|
|
|}
The two most used will be Program Modules and Data Modules.

=== Program Modules ===
The format of a program module varies depending on whether you have a single source file for your program or multiple source files.

Note: multiple source files format cannot use direct page addressing due to the way they are compiled.

==== Single Source File Format ====
The following is a skeleton for a single source file memory module (program).
<code>********************************************************************</code>
<code>* [Program Name]</code>
<code>* [Description]</code>
<code>*</code>
<code>* by [Author Name]</code>
<code>*</code>
<code>* Edt/Rev YYYY/MM/DD Modified by</code>
<code>* Comment</code>
<code>* ------------------------------------------------------------------</code>
<code> nam [executablename]</code>
<code> ttl [Full Program Name]</code>

<code> ifp1</code>
<code> use defsfile</code>
<code> endc</code>

<code>tylg set Prgrm+Objct</code>
<code>atrv set ReEnt+rev</code>
<code>rev set $00</code>
<code>edition set 1</code>

<code> '''mod eom,name,tylg,atrv,start,size'''</code>

<code> [Data Section - Variables and Data Structures Here]</code>

<code>size equ .</code>
<code>name fcs /[executablename]/</code>
<code> fcb edition</code>

<code>start</code>

<code> [Program Section - Program Code Here]</code>
<code> </code>
<code> os9 F$Exit</code>

<code> '''emod'''</code>
<code>eom equ *</code>
<code> end</code>
OS9 can load programs (modules) only if they are in module header format. A module (program) is defined between the '''mod''' and '''emod''' pseudo instructions.

* '''mod:''' Creates the module header and starts CRC check. '''mod''' has 6 attributes:

# Module size (computed from the ''eom'' label at the end of the code - 2 bytes)
# Module name offset (offset where the string of the name is contained, here that is defined at the name label with the ''fcs'' pseudo instruction - 2 bytes
# Module type & language (in this case a Program in 6809 object code - 1 byte)
# Module attribute-revision (1 byte). Attributes are reentrant (ReEnt) or not reentrant (0). Revision is a number 0-15. If two or more modules with the same name are in the module directory, then OS-9 only keeps the highest revision number module.
# Module execution offset (here that is defined with the start label - 2 bytes)
# Module variable storage size (defined by the ''size'' label immediately after the variable area, includes stack space - 2 bytes)

* '''emod''': Outputs the correct 3 byte CRC. This is generated by the assembler over the entire module.

For more information about memory modules, see OS-9 Fundamentals:

[https://www.youtube.com/watch?v=YpoqTyrty8k OS-9 Fundamentals on YouTube by Boisy Pitre]

==== Multiple Source File Format ====

=== Data Modules ===
Here is a portion of the font module, which is a data module in NitrOS-9.

<code> nam font</code>
<code> ttl F256 font</code>
</code>
<code> use defsfile</code>
</code>
<code>tylg set Data</code>
<code>atrv set ReEnt+rev</code>
<code>rev set $01</code>
</code>
<code> mod eom,name,tylg,atrv,start,0</code>
<code>name fcs /font/</code>
</code>
<code>start</code>
<code>L0000 fcb $00,$00,$00,$00,$00,$00,$00,$00 </code>
<code>L0008 fcb $7C,$82,$AA,$82,$BA,$92,$82,$7C </code>
</code>
<code>*More data here</code>
</code>
<code> emod</code>
<code>eom equ *</code>
<code> end</code>

== Writing Position Independent Code ==
All code in NitrOS-9 must be position independent. Addresses are not known until a program module is loaded and executed. All addressing must be "program counter relative addressing". All branch and long branch instructions are program counter relative.

Rules:

Use <code>BRA</code> and <code>LBRA</code> instead of <code>JMP</code>

Use <code>BSR</code> and <code>LBSR</code> instead of <code>JSR</code>

Use program counter relative indexed addressing for all load, store, arithmetic and logical instructions.

== Accessing Variables and Data Structures ==

== Accessing Table Data with PCR ==
__FORCETOC__

OS-9 Assembly Code Development

2024-10-01T03:49:51Z

Jfed: /* Single Source File Format */

== Overview ==
Each process in NitrOS-9 is allocated its own 64K address space. When run, the program object code is loaded into the end of the memory space, and the variables and data structures are loaded into the beginning. In addition, NitrOS-9 keeps an separate per-process MMU table (DAT Image), so you must use <code>F$MapBlk</code> to map and <code>F$ClrBlk</code> to unmap 8K blocks in your process' address space. The operating system has its own 64K address space as well.

When a new process is created, registers U, Y, DP and SP are set with U = start of data area, Y = end of data area, DP = page # of beginning page, SP = end of data area + 1. Each process includes its own execution and data directories, along with <code>std in</code>, <code>std out</code> and <code>std err</code>.

=== Memory and DAT Image ===
<code>mmap</code> and <code>pmap</code> output the current status of the memory in the system. <code>mmap</code> shows which memory blocks are currently in use. <code>pmap</code> shows the blocks that are mapped in the DAT Image for a particular process.
[[File:Mmappmap.png|none|thumb]]

== Program and Data Module Structure ==

There are 9 different types of modules in 4 possible languages:
{| class="wikitable"
|+
! colspan="3" |Module Types
!
! colspan="2" |Language
|-
|'''Code'''
|'''Module Type'''
|'''Name'''
|
|'''Code'''
|'''Language'''
|-
|$1x
|Program Module
|Prgm
|
|$x0
|Data (non-executable)
|-
|$2x
|Subroutine Module
|Sbrtn
|
|$x1
|6809 Object Code
|-
|$3x
|Multi-module
|Multi
|
|$x2
|BASIC09 I-Code
|-
|$4x
|Data Module
|Data
|
|$x3
|PASCAL I-Code
|-
|$5x-$Bx
|User-definable module
|
|
|$x4-$xF
|Reserved for Future Use
|-
|$Cx
|OS-9 System Module
|Systm
|
|
|
|-
|$Dx
|OS-9 File Manager Module
|FlMgr
|
|
|
|-
|$Ex
|OS-9 Device Driver Module
|Drivr
|
|
|
|-
|$Fx
|OS-9 Device Descriptor Module
|Devic
|
|
|
|}
The two most used will be Program Modules and Data Modules.

=== Program Modules ===
The format of a program module varies depending on whether you have a single source file for your program or multiple source files.

Note: multiple source files format cannot use direct page addressing due to the way they are compiled.

==== Single Source File Format ====
The following is a skeleton for a single source file memory module (program).
<code>********************************************************************</code>
<code>* [Program Name]</code>
<code>* [Description]</code>
<code>*</code>
<code>* by [Author Name]</code>
<code>*</code>
<code>* Edt/Rev YYYY/MM/DD Modified by</code>
<code>* Comment</code>
<code>* ------------------------------------------------------------------</code>
<code> nam [executablename]</code>
<code> ttl [Full Program Name]</code>

<code> ifp1</code>
<code> use defsfile</code>
<code> endc</code>

<code>tylg set Prgrm+Objct</code>
<code>atrv set ReEnt+rev</code>
<code>rev set $00</code>
<code>edition set 1</code>

<code> '''mod eom,name,tylg,atrv,start,size'''</code>

<code> [Data Section - Variables and Data Structures Here]</code>

<code>size equ .</code>
<code>name fcs /[executablename]/</code>
<code> fcb edition</code>

<code>start</code>

<code> [Program Section - Program Code Here]</code>
<code> </code>
<code> os9 F$Exit</code>

<code> '''emod'''</code>
<code>eom equ *</code>
<code> end</code>
OS9 can load programs (modules) only if they are in module header format. A module (program) is defined between the '''mod''' and '''emod''' pseudo instructions.

* '''mod:''' Creates the module header and starts CRC check. '''mod''' has 6 attributes:

# Module size (computed from the ''eom'' label at the end of the code - 2 bytes)
# Module name offset (offset where the string of the name is contained, here that is defined at the name label with the ''fcs'' pseudo instruction - 2 bytes
# Module type & language (in this case a Program in 6809 object code - 1 byte)
# Module attribute-revision (1 byte). Attributes are reentrant (ReEnt) or not reentrant (0). Revision is a number 0-15. If two or more modules with the same name are in the module directory, then OS-9 only keeps the highest revision number module.
# Module execution offset (here that is defined with the start label - 2 bytes)
# Module variable storage size (defined by the ''size'' label immediately after the variable area, includes stack space - 2 bytes)

* '''emod''': Outputs the correct 3 byte CRC. This is generated by the assembler over the entire module.

For more information about memory modules, see OS-9 Fundamentals:

[https://www.youtube.com/watch?v=YpoqTyrty8k OS-9 Fundamentals on YouTube by Boisy Pitre]

==== Multiple Source File Format ====

=== Data Modules ===
Here is a portion of the font module, which is a data module in NitrOS-9.

<code> nam font</code>
<code> ttl F256 font</code>
</code>
<code> use defsfile</code>
</code>
<code>tylg set Data</code>
<code>atrv set ReEnt+rev</code>
<code>rev set $01</code>
</code>
<code> mod eom,name,tylg,atrv,start,0</code>
<code>name fcs /font/</code>
</code>
<code>start</code>
<code>L0000 fcb $00,$00,$00,$00,$00,$00,$00,$00 </code>
<code>L0008 fcb $7C,$82,$AA,$82,$BA,$92,$82,$7C </code>
</code>
<code>*More data here</code>
</code>
<code> emod</code>
<code>eom equ *</code>
<code> end</code>

== Writing Position Independent Code ==
All code in NitrOS-9 must be position independent. Addresses are not known until a program module is loaded and executed. All addressing must be "program counter relative addressing". All branch and long branch instructions are program counter relative.

Rules:

Use <code>BRA</code> and <code>LBRA</code> instead of <code>JMP</code>

Use <code>BSR</code> and <code>LBSR</code> instead of <code>JSR</code>

Use program counter relative indexed addressing for all load, store, arithmetic and logical instructions.

== Accessing Variables and Data Structures ==

== Accessing Table Data with PCR ==
__FORCETOC__

OS-9 Assembly Code Development

2024-09-30T02:59:46Z

Jfed: /* Program Modules */

== Overview ==
Each process in NitrOS-9 is allocated its own 64K address space. When run, the program object code is loaded into the end of the memory space, and the variables and data structures are loaded into the beginning. In addition, NitrOS-9 keeps an separate per-process MMU table (DAT Image), so you must use <code>F$MapBlk</code> to map and <code>F$ClrBlk</code> to unmap 8K blocks in your process' address space. The operating system has its own 64K address space as well.

When a new process is created, registers U, Y, DP and SP are set with U = start of data area, Y = end of data area, DP = page # of beginning page, SP = end of data area + 1. Each process includes its own execution and data directories, along with <code>std in</code>, <code>std out</code> and <code>std err</code>.

=== Memory and DAT Image ===
<code>mmap</code> and <code>pmap</code> output the current status of the memory in the system. <code>mmap</code> shows which memory blocks are currently in use. <code>pmap</code> shows the blocks that are mapped in the DAT Image for a particular process.
[[File:Mmappmap.png|none|thumb]]

== Program and Data Module Structure ==

There are 9 different types of modules in 4 possible languages:
{| class="wikitable"
|+
! colspan="3" |Module Types
!
! colspan="2" |Language
|-
|'''Code'''
|'''Module Type'''
|'''Name'''
|
|'''Code'''
|'''Language'''
|-
|$1x
|Program Module
|Prgm
|
|$x0
|Data (non-executable)
|-
|$2x
|Subroutine Module
|Sbrtn
|
|$x1
|6809 Object Code
|-
|$3x
|Multi-module
|Multi
|
|$x2
|BASIC09 I-Code
|-
|$4x
|Data Module
|Data
|
|$x3
|PASCAL I-Code
|-
|$5x-$Bx
|User-definable module
|
|
|$x4-$xF
|Reserved for Future Use
|-
|$Cx
|OS-9 System Module
|Systm
|
|
|
|-
|$Dx
|OS-9 File Manager Module
|FlMgr
|
|
|
|-
|$Ex
|OS-9 Device Driver Module
|Drivr
|
|
|
|-
|$Fx
|OS-9 Device Descriptor Module
|Devic
|
|
|
|}
The two most used will be Program Modules and Data Modules.

=== Program Modules ===
The format of a program module varies depending on whether you have a single source file for your program or multiple source files.

Note: multiple source files format cannot use direct page addressing due to the way they are compiled.

==== Single Source File Format ====
The following is a skeleton for a single source file memory module (program).
<code>********************************************************************</code>
<code>* [Program Name]</code>
<code>* [Description]</code>
<code>*</code>
<code>* by [Author Name]</code>
<code>*</code>
<code>* Edt/Rev YYYY/MM/DD Modified by</code>
<code>* Comment</code>
<code>* ------------------------------------------------------------------</code>
<code> nam [executablename]</code>
<code> ttl [Full Program Name]</code>

<code> ifp1</code>
<code> use defsfile</code>
<code> endc</code>

<code>tylg set Prgrm+Objct</code>
<code>atrv set ReEnt+rev</code>
<code>rev set $00</code>
<code>edition set 1</code>

<code> '''mod eom,name,tylg,atrv,start,size'''</code>

<code> [Data Section - Variables and Data Structures Here]</code>

<code>size equ .</code>
<code>name fcs /[executablename]/</code>
<code> fcb edition</code>

<code>start</code>

<code> [Program Section - Program Code Here]</code>
<code> </code>
<code> os9 F$Exit</code>

<code> '''emod'''</code>
<code>eom equ *</code>
<code> end</code>
OS9 can load programs (modules) only if they are in module header format. A module (program) is defined between the '''mod''' and '''emod''' pseudo instructions.

'''mod:''' Creates the module header and starts CRC check. '''mod''' has 6 attributes:

# Module size (computed from the ''eom'' label at the end of the code - 2 bytes)
# Module name offset (offset where the string of the name is contained, here that is defined at the name label with the ''fcs'' pseudo instruction - 2 bytes
# Module type & language (in this case a Program in 6809 object code - 1 byte)
# Module attribute-revision (1 byte). Attributes are reentrant (ReEnt) or not reentrant (0). Revision is a number 0-15. If two or more modules with the same name are in the module directory, then OS-9 only keeps the highest revision number module.
# Module execution offset (here that is defined with the start label - 2 bytes)
# Module variable storage size (defined by the ''size'' label immediately after the variable area, includes stack space - 2 bytes)

'''emod''': Outputs the correct 3 byte CRC. This is generated by the assembler over the entire module.

For more information about memory modules, see OS-9 Fundamentals:

[https://www.youtube.com/watch?v=YpoqTyrty8k OS-9 Fundamentals on YouTube by Boisy Pitre]

==== Multiple Source File Format ====

=== Data Modules ===
Here is a portion of the font module, which is a data module in NitrOS-9.

<code> nam font</code>
<code> ttl F256 font</code>
</code>
<code> use defsfile</code>
</code>
<code>tylg set Data</code>
<code>atrv set ReEnt+rev</code>
<code>rev set $01</code>
</code>
<code> mod eom,name,tylg,atrv,start,0</code>
<code>name fcs /font/</code>
</code>
<code>start</code>
<code>L0000 fcb $00,$00,$00,$00,$00,$00,$00,$00 </code>
<code>L0008 fcb $7C,$82,$AA,$82,$BA,$92,$82,$7C </code>
</code>
<code>*More data here</code>
</code>
<code> emod</code>
<code>eom equ *</code>
<code> end</code>

== Writing Position Independent Code ==
All code in NitrOS-9 must be position independent. Addresses are not known until a program module is loaded and executed. All addressing must be "program counter relative addressing". All branch and long branch instructions are program counter relative.

Rules:

Use <code>BRA</code> and <code>LBRA</code> instead of <code>JMP</code>

Use <code>BSR</code> and <code>LBSR</code> instead of <code>JSR</code>

Use program counter relative indexed addressing for all load, store, arithmetic and logical instructions.

== Accessing Variables and Data Structures ==

== Accessing Table Data with PCR ==
__FORCETOC__

OS-9 Assembly Code Development

2024-09-30T02:53:57Z

Jfed: Added intro sentence.

== Overview ==
Each process in NitrOS-9 is allocated its own 64K address space. When run, the program object code is loaded into the end of the memory space, and the variables and data structures are loaded into the beginning. In addition, NitrOS-9 keeps an separate per-process MMU table (DAT Image), so you must use <code>F$MapBlk</code> to map and <code>F$ClrBlk</code> to unmap 8K blocks in your process' address space. The operating system has its own 64K address space as well.

When a new process is created, registers U, Y, DP and SP are set with U = start of data area, Y = end of data area, DP = page # of beginning page, SP = end of data area + 1. Each process includes its own execution and data directories, along with <code>std in</code>, <code>std out</code> and <code>std err</code>.

=== Memory and DAT Image ===
<code>mmap</code> and <code>pmap</code> output the current status of the memory in the system. <code>mmap</code> shows which memory blocks are currently in use. <code>pmap</code> shows the blocks that are mapped in the DAT Image for a particular process.
[[File:Mmappmap.png|none|thumb]]

== Program and Data Module Structure ==

There are 9 different types of modules in 4 possible languages:
{| class="wikitable"
|+
! colspan="3" |Module Types
!
! colspan="2" |Language
|-
|'''Code'''
|'''Module Type'''
|'''Name'''
|
|'''Code'''
|'''Language'''
|-
|$1x
|Program Module
|Prgm
|
|$x0
|Data (non-executable)
|-
|$2x
|Subroutine Module
|Sbrtn
|
|$x1
|6809 Object Code
|-
|$3x
|Multi-module
|Multi
|
|$x2
|BASIC09 I-Code
|-
|$4x
|Data Module
|Data
|
|$x3
|PASCAL I-Code
|-
|$5x-$Bx
|User-definable module
|
|
|$x4-$xF
|Reserved for Future Use
|-
|$Cx
|OS-9 System Module
|Systm
|
|
|
|-
|$Dx
|OS-9 File Manager Module
|FlMgr
|
|
|
|-
|$Ex
|OS-9 Device Driver Module
|Drivr
|
|
|
|-
|$Fx
|OS-9 Device Descriptor Module
|Devic
|
|
|
|}
The two most used will be Program Modules and Data Modules.

=== Program Modules ===
The format of the program module varies depending on whether you have a single source file for your program or multiple source files.

Note: multiple source files format cannot use direct page addressing due to the way they are compiled.

==== Single Source File Format ====
The following is a skeleton for a single source file memory module (program).
<code>********************************************************************</code>
<code>* [Program Name]</code>
<code>* [Description]</code>
<code>*</code>
<code>* by [Author Name]</code>
<code>*</code>
<code>* Edt/Rev YYYY/MM/DD Modified by</code>
<code>* Comment</code>
<code>* ------------------------------------------------------------------</code>
<code> nam [executablename]</code>
<code> ttl [Full Program Name]</code>

<code> ifp1</code>
<code> use defsfile</code>
<code> endc</code>

<code>tylg set Prgrm+Objct</code>
<code>atrv set ReEnt+rev</code>
<code>rev set $00</code>
<code>edition set 1</code>

<code> '''mod eom,name,tylg,atrv,start,size'''</code>

<code> [Data Section - Variables and Data Structures Here]</code>

<code>size equ .</code>
<code>name fcs /[executablename]/</code>
<code> fcb edition</code>

<code>start</code>

<code> [Program Section - Program Code Here]</code>
<code> </code>
<code> os9 F$Exit</code>

<code> '''emod'''</code>
<code>eom equ *</code>
<code> end</code>
OS9 can load programs (modules) only if they are in module header format. A module (program) is defined between the '''mod''' and '''emod''' pseudo instructions.

'''mod:''' Creates the module header and starts CRC check. '''mod''' has 6 attributes:

# Module size (computed from the ''eom'' label at the end of the code - 2 bytes)
# Module name offset (offset where the string of the name is contained, here that is defined at the name label with the ''fcs'' pseudo instruction - 2 bytes
# Module type & language (in this case a Program in 6809 object code - 1 byte)
# Module attribute-revision (1 byte). Attributes are reentrant (ReEnt) or not reentrant (0). Revision is a number 0-15. If two or more modules with the same name are in the module directory, then OS-9 only keeps the highest revision number module.
# Module execution offset (here that is defined with the start label - 2 bytes)
# Module variable storage size (defined by the ''size'' label immediately after the variable area, includes stack space - 2 bytes)

'''emod''': Outputs the correct 3 byte CRC. This is generated by the assembler over the entire module.

For more information about memory modules, see OS-9 Fundamentals:

[https://www.youtube.com/watch?v=YpoqTyrty8k OS-9 Fundamentals on YouTube by Boisy Pitre]

==== Multiple Source File Format ====

=== Data Modules ===
Here is a portion of the font module, which is a data module in NitrOS-9.

<code> nam font</code>
<code> ttl F256 font</code>
</code>
<code> use defsfile</code>
</code>
<code>tylg set Data</code>
<code>atrv set ReEnt+rev</code>
<code>rev set $01</code>
</code>
<code> mod eom,name,tylg,atrv,start,0</code>
<code>name fcs /font/</code>
</code>
<code>start</code>
<code>L0000 fcb $00,$00,$00,$00,$00,$00,$00,$00 </code>
<code>L0008 fcb $7C,$82,$AA,$82,$BA,$92,$82,$7C </code>
</code>
<code>*More data here</code>
</code>
<code> emod</code>
<code>eom equ *</code>
<code> end</code>

== Writing Position Independent Code ==
All code in NitrOS-9 must be position independent. Addresses are not known until a program module is loaded and executed. All addressing must be "program counter relative addressing". All branch and long branch instructions are program counter relative.

Rules:

Use <code>BRA</code> and <code>LBRA</code> instead of <code>JMP</code>

Use <code>BSR</code> and <code>LBSR</code> instead of <code>JSR</code>

Use program counter relative indexed addressing for all load, store, arithmetic and logical instructions.

== Accessing Variables and Data Structures ==

== Accessing Table Data with PCR ==
__FORCETOC__

OS-9 Assembly Code Development

2024-09-30T02:49:22Z

Jfed: Added information about assembly pseudo instructions.

== Overview ==
Each process in NitrOS-9 is allocated its own 64K address space. When run, the program object code is loaded into the end of the memory space, and the variables and data structures are loaded into the beginning. In addition, NitrOS-9 keeps an separate per-process MMU table (DAT Image), so you must use <code>F$MapBlk</code> to map and <code>F$ClrBlk</code> to unmap 8K blocks in your process' address space. The operating system has its own 64K address space as well.

When a new process is created, registers U, Y, DP and SP are set with U = start of data area, Y = end of data area, DP = page # of beginning page, SP = end of data area + 1. Each process includes its own execution and data directories, along with <code>std in</code>, <code>std out</code> and <code>std err</code>.

=== Memory and DAT Image ===
<code>mmap</code> and <code>pmap</code> output the current status of the memory in the system. <code>mmap</code> shows which memory blocks are currently in use. <code>pmap</code> shows the blocks that are mapped in the DAT Image for a particular process.
[[File:Mmappmap.png|none|thumb]]

== Program and Data Module Structure ==

There are 9 different types of modules in 4 possible languages:
{| class="wikitable"
|+
! colspan="3" |Module Types
!
! colspan="2" |Language
|-
|'''Code'''
|'''Module Type'''
|'''Name'''
|
|'''Code'''
|'''Language'''
|-
|$1x
|Program Module
|Prgm
|
|$x0
|Data (non-executable)
|-
|$2x
|Subroutine Module
|Sbrtn
|
|$x1
|6809 Object Code
|-
|$3x
|Multi-module
|Multi
|
|$x2
|BASIC09 I-Code
|-
|$4x
|Data Module
|Data
|
|$x3
|PASCAL I-Code
|-
|$5x-$Bx
|User-definable module
|
|
|$x4-$xF
|Reserved for Future Use
|-
|$Cx
|OS-9 System Module
|Systm
|
|
|
|-
|$Dx
|OS-9 File Manager Module
|FlMgr
|
|
|
|-
|$Ex
|OS-9 Device Driver Module
|Drivr
|
|
|
|-
|$Fx
|OS-9 Device Descriptor Module
|Devic
|
|
|
|}
The two most used will be Program Modules and Data Modules.

=== Program Modules ===
The format of the program module varies depending on whether you have a single source file for your program or multiple source files.

Note: multiple source files format cannot use direct page addressing due to the way they are compiled.

==== Single Source File Format ====

<code>********************************************************************</code>
<code>* [Program Name]</code>
<code>* [Description]</code>
<code>*</code>
<code>* by [Author Name]</code>
<code>*</code>
<code>* Edt/Rev YYYY/MM/DD Modified by</code>
<code>* Comment</code>
<code>* ------------------------------------------------------------------</code>
<code> nam [executablename]</code>
<code> ttl [Full Program Name]</code>

<code> ifp1</code>
<code> use defsfile</code>
<code> endc</code>

<code>tylg set Prgrm+Objct</code>
<code>atrv set ReEnt+rev</code>
<code>rev set $00</code>
<code>edition set 1</code>

<code> '''mod eom,name,tylg,atrv,start,size'''</code>

<code> [Data Section - Variables Here]</code>

<code>size equ .</code>
<code>name fcs /[executablename]/</code>
<code> fcb edition</code>

<code>start</code>

<code> [Program Section - Program Code Here]</code>
<code> </code>
<code> os9 F$Exit</code>

<code> '''emod'''</code>
<code>eom equ *</code>
<code> end</code>
OS9 can load programs (modules) only if they are in module header format. A module (program) is defined between the '''mod''' and '''emod''' pseudo instructions.

'''mod:''' Creates the module header and starts CRC check. '''mod''' has 6 attributes:

# Module size (computed from the ''eom'' label at the end of the code - 2 bytes)
# Module name offset (offset where the string of the name is contained, here that is defined at the name label with the ''fcs'' pseudo instruction - 2 bytes
# Module type & language (in this case a Program in 6809 object code - 1 byte)
# Module attribute-revision (1 byte). Attributes are reentrant (ReEnt) or not reentrant (0). Revision is a number 0-15. If two or more modules with the same name are in the module directory, then OS-9 only keeps the highest revision number module.
# Module execution offset (here that is defined with the start label - 2 bytes)
# Module variable storage size (defined by the ''size'' label immediately after the variable area, includes stack space - 2 bytes)

'''emod''': Outputs the correct 3 byte CRC. This is generated by the assembler over the entire module.

For more information about memory modules, see OS-9 Fundamentals:

[https://www.youtube.com/watch?v=YpoqTyrty8k OS-9 Fundamentals on YouTube by Boisy Pitre]

==== Multiple Source File Format ====

=== Data Modules ===
Here is a portion of the font module, which is a data module in NitrOS-9.

<code> nam font</code>
<code> ttl F256 font</code>
</code>
<code> use defsfile</code>
</code>
<code>tylg set Data</code>
<code>atrv set ReEnt+rev</code>
<code>rev set $01</code>
</code>
<code> mod eom,name,tylg,atrv,start,0</code>
<code>name fcs /font/</code>
</code>
<code>start</code>
<code>L0000 fcb $00,$00,$00,$00,$00,$00,$00,$00 </code>
<code>L0008 fcb $7C,$82,$AA,$82,$BA,$92,$82,$7C </code>
</code>
<code>*More data here</code>
</code>
<code> emod</code>
<code>eom equ *</code>
<code> end</code>

== Writing Position Independent Code ==
All code in NitrOS-9 must be position independent. Addresses are not known until a program module is loaded and executed. All addressing must be "program counter relative addressing". All branch and long branch instructions are program counter relative.

Rules:

Use <code>BRA</code> and <code>LBRA</code> instead of <code>JMP</code>

Use <code>BSR</code> and <code>LBSR</code> instead of <code>JSR</code>

Use program counter relative indexed addressing for all load, store, arithmetic and logical instructions.

== Accessing Variables and Data Structures ==

== Accessing Table Data with PCR ==
__FORCETOC__

OS-9 Assembly Code Development

2024-09-29T21:55:30Z

Jfed: /* Data Modules */

== Overview ==
Each process in NitrOS-9 is allocated its own 64K address space. When run, the program object code is loaded into the end of the memory space, and the variables and data structures are loaded into the beginning. In addition, NitrOS-9 keeps an separate per-process MMU table (DAT Image), so you must use <code>F$MapBlk</code> to map and <code>F$ClrBlk</code> to unmap 8K blocks in your process' address space. The operating system has its own 64K address space as well.

When a new process is created, registers U, Y, DP and SP are set with U = start of data area, Y = end of data area, DP = page # of beginning page, SP = end of data area + 1. Each process includes its own execution and data directories, along with <code>std in</code>, <code>std out</code> and <code>std err</code>.

=== Memory and DAT Image ===
<code>mmap</code> and <code>pmap</code> output the current status of the memory in the system. <code>mmap</code> shows which memory blocks are currently in use. <code>pmap</code> shows the blocks that are mapped in the DAT Image for a particular process.
[[File:Mmappmap.png|none|thumb]]

== Program and Data Module Structure ==

There are 9 different types of modules in 4 possible languages:
{| class="wikitable"
|+
! colspan="3" |Module Types
!
! colspan="2" |Language
|-
|'''Code'''
|'''Module Type'''
|'''Name'''
|
|'''Code'''
|'''Language'''
|-
|$1x
|Program Module
|Prgm
|
|$x0
|Data (non-executable)
|-
|$2x
|Subroutine Module
|Sbrtn
|
|$x1
|6809 Object Code
|-
|$3x
|Multi-module
|Multi
|
|$x2
|BASIC09 I-Code
|-
|$4x
|Data Module
|Data
|
|$x3
|PASCAL I-Code
|-
|$5x-$Bx
|User-definable module
|
|
|$x4-$xF
|Reserved for Future Use
|-
|$Cx
|OS-9 System Module
|Systm
|
|
|
|-
|$Dx
|OS-9 File Manager Module
|FlMgr
|
|
|
|-
|$Ex
|OS-9 Device Driver Module
|Drivr
|
|
|
|-
|$Fx
|OS-9 Device Descriptor Module
|Devic
|
|
|
|}
The two most used will be Program Modules and Data Modules.

=== Program Modules ===
The format of the program module varies depending on whether you have a single source file for your program or multiple source files.

Note: multiple source files format cannot use direct page addressing due to the way they are compiled.

==== Single Source File Format ====

<code>********************************************************************</code>
<code>* [Program Name]</code>
<code>* [Description]</code>
<code>*</code>
<code>* by [Author Name]</code>
<code>*</code>
<code>* Edt/Rev YYYY/MM/DD Modified by</code>
<code>* Comment</code>
<code>* ------------------------------------------------------------------</code>
<code> nam [executablename]</code>
<code> ttl [Full Program Name]</code>
<code></code>
<code> ifp1</code>
<code> use defsfile</code>
<code> endc</code>
</code>
<code>tylg set Prgrm+Objct</code>
<code>atrv set ReEnt+rev</code>
<code>rev set $00</code>
<code>edition set 1</code>
</code>
<code> mod eom,name,tylg,atrv,start,size</code>
</code>
<code> [Variables Here]</code>
</code>
<code>size equ .</code>
<code>name fcs /executablename/</code>
<code> fcb edition</code>
</code>
<code>start</code>
</code>
<code> [Program Code Here]</code>
<code> </code>
<code> os9 F$Exit</code>
</code>
<code> emod</code>
<code>eom equ *</code>
<code> end</code>

==== Multiple Source File Format ====

=== Data Modules ===
Here is a portion of the font module, which is a data module in NitrOS-9.

<code> nam font</code>
<code> ttl F256 font</code>
</code>
<code> use defsfile</code>
</code>
<code>tylg set Data</code>
<code>atrv set ReEnt+rev</code>
<code>rev set $01</code>
</code>
<code> mod eom,name,tylg,atrv,start,0</code>
<code>name fcs /font/</code>
</code>
<code>start</code>
<code>L0000 fcb $00,$00,$00,$00,$00,$00,$00,$00 </code>
<code>L0008 fcb $7C,$82,$AA,$82,$BA,$92,$82,$7C </code>
</code>
<code>*More data here</code>
</code>
<code> emod</code>
<code>eom equ *</code>
<code> end</code>

== Writing Position Independent Code ==
All code in NitrOS-9 must be position independent. Addresses are not known until a program module is loaded and executed. All addressing must be "program counter relative addressing". All branch and long branch instructions are program counter relative.

Rules:

Use <code>BRA</code> and <code>LBRA</code> instead of <code>JMP</code>

Use <code>BSR</code> and <code>LBSR</code> instead of <code>JSR</code>

Use program counter relative indexed addressing for all load, store, arithmetic and logical instructions.

== Accessing Variables and Data Structures ==

== Accessing Table Data with PCR ==
__FORCETOC__

OS-9 Assembly Code Development

2024-09-29T21:51:34Z

Jfed: /* Single Source File Format */

== Overview ==
Each process in NitrOS-9 is allocated its own 64K address space. When run, the program object code is loaded into the end of the memory space, and the variables and data structures are loaded into the beginning. In addition, NitrOS-9 keeps an separate per-process MMU table (DAT Image), so you must use <code>F$MapBlk</code> to map and <code>F$ClrBlk</code> to unmap 8K blocks in your process' address space. The operating system has its own 64K address space as well.

When a new process is created, registers U, Y, DP and SP are set with U = start of data area, Y = end of data area, DP = page # of beginning page, SP = end of data area + 1. Each process includes its own execution and data directories, along with <code>std in</code>, <code>std out</code> and <code>std err</code>.

=== Memory and DAT Image ===
<code>mmap</code> and <code>pmap</code> output the current status of the memory in the system. <code>mmap</code> shows which memory blocks are currently in use. <code>pmap</code> shows the blocks that are mapped in the DAT Image for a particular process.
[[File:Mmappmap.png|none|thumb]]

== Program and Data Module Structure ==

There are 9 different types of modules in 4 possible languages:
{| class="wikitable"
|+
! colspan="3" |Module Types
!
! colspan="2" |Language
|-
|'''Code'''
|'''Module Type'''
|'''Name'''
|
|'''Code'''
|'''Language'''
|-
|$1x
|Program Module
|Prgm
|
|$x0
|Data (non-executable)
|-
|$2x
|Subroutine Module
|Sbrtn
|
|$x1
|6809 Object Code
|-
|$3x
|Multi-module
|Multi
|
|$x2
|BASIC09 I-Code
|-
|$4x
|Data Module
|Data
|
|$x3
|PASCAL I-Code
|-
|$5x-$Bx
|User-definable module
|
|
|$x4-$xF
|Reserved for Future Use
|-
|$Cx
|OS-9 System Module
|Systm
|
|
|
|-
|$Dx
|OS-9 File Manager Module
|FlMgr
|
|
|
|-
|$Ex
|OS-9 Device Driver Module
|Drivr
|
|
|
|-
|$Fx
|OS-9 Device Descriptor Module
|Devic
|
|
|
|}
The two most used will be Program Modules and Data Modules.

=== Program Modules ===
The format of the program module varies depending on whether you have a single source file for your program or multiple source files.

Note: multiple source files format cannot use direct page addressing due to the way they are compiled.

==== Single Source File Format ====

<code>********************************************************************</code>
<code>* [Program Name]</code>
<code>* [Description]</code>
<code>*</code>
<code>* by [Author Name]</code>
<code>*</code>
<code>* Edt/Rev YYYY/MM/DD Modified by</code>
<code>* Comment</code>
<code>* ------------------------------------------------------------------</code>
<code> nam [executablename]</code>
<code> ttl [Full Program Name]</code>
<code></code>
<code> ifp1</code>
<code> use defsfile</code>
<code> endc</code>
</code>
<code>tylg set Prgrm+Objct</code>
<code>atrv set ReEnt+rev</code>
<code>rev set $00</code>
<code>edition set 1</code>
</code>
<code> mod eom,name,tylg,atrv,start,size</code>
</code>
<code> [Variables Here]</code>
</code>
<code>size equ .</code>
<code>name fcs /executablename/</code>
<code> fcb edition</code>
</code>
<code>start</code>
</code>
<code> [Program Code Here]</code>
<code> </code>
<code> os9 F$Exit</code>
</code>
<code> emod</code>
<code>eom equ *</code>
<code> end</code>

==== Multiple Source File Format ====

=== Data Modules ===
Here is a portion of the font module, which is a data module in NitrOS-9.

<code> nam font</code>

<code> ttl F256 font</code>

<code> use defsfile</code>

<code>tylg set Data</code>

<code>atrv set ReEnt+rev</code>

<code>rev set $01</code>

<code> mod eom,name,tylg,atrv,start,0</code>

<code>name fcs /font/</code>

<code>start</code>

<code>L0000 fcb $00,$00,$00,$00,$00,$00,$00,$00 </code>

<code>L0008 fcb $7C,$82,$AA,$82,$BA,$92,$82,$7C </code>

<nowiki>*</nowiki>More data here

<code> emod</code>

<code>eom equ *</code>

<code> end</code>

== Writing Position Independent Code ==
All code in NitrOS-9 must be position independent. Addresses are not known until a program module is loaded and executed. All addressing must be "program counter relative addressing". All branch and long branch instructions are program counter relative.

Rules:

Use <code>BRA</code> and <code>LBRA</code> instead of <code>JMP</code>

Use <code>BSR</code> and <code>LBSR</code> instead of <code>JSR</code>

Use program counter relative indexed addressing for all load, store, arithmetic and logical instructions.

== Accessing Variables and Data Structures ==

== Accessing Table Data with PCR ==
__FORCETOC__

OS-9 Assembly Code Development

2024-09-29T21:50:34Z

Jfed: /* Single Source File Format */

== Overview ==
Each process in NitrOS-9 is allocated its own 64K address space. When run, the program object code is loaded into the end of the memory space, and the variables and data structures are loaded into the beginning. In addition, NitrOS-9 keeps an separate per-process MMU table (DAT Image), so you must use <code>F$MapBlk</code> to map and <code>F$ClrBlk</code> to unmap 8K blocks in your process' address space. The operating system has its own 64K address space as well.

When a new process is created, registers U, Y, DP and SP are set with U = start of data area, Y = end of data area, DP = page # of beginning page, SP = end of data area + 1. Each process includes its own execution and data directories, along with <code>std in</code>, <code>std out</code> and <code>std err</code>.

=== Memory and DAT Image ===
<code>mmap</code> and <code>pmap</code> output the current status of the memory in the system. <code>mmap</code> shows which memory blocks are currently in use. <code>pmap</code> shows the blocks that are mapped in the DAT Image for a particular process.
[[File:Mmappmap.png|none|thumb]]

== Program and Data Module Structure ==

There are 9 different types of modules in 4 possible languages:
{| class="wikitable"
|+
! colspan="3" |Module Types
!
! colspan="2" |Language
|-
|'''Code'''
|'''Module Type'''
|'''Name'''
|
|'''Code'''
|'''Language'''
|-
|$1x
|Program Module
|Prgm
|
|$x0
|Data (non-executable)
|-
|$2x
|Subroutine Module
|Sbrtn
|
|$x1
|6809 Object Code
|-
|$3x
|Multi-module
|Multi
|
|$x2
|BASIC09 I-Code
|-
|$4x
|Data Module
|Data
|
|$x3
|PASCAL I-Code
|-
|$5x-$Bx
|User-definable module
|
|
|$x4-$xF
|Reserved for Future Use
|-
|$Cx
|OS-9 System Module
|Systm
|
|
|
|-
|$Dx
|OS-9 File Manager Module
|FlMgr
|
|
|
|-
|$Ex
|OS-9 Device Driver Module
|Drivr
|
|
|
|-
|$Fx
|OS-9 Device Descriptor Module
|Devic
|
|
|
|}
The two most used will be Program Modules and Data Modules.

=== Program Modules ===
The format of the program module varies depending on whether you have a single source file for your program or multiple source files.

Note: multiple source files format cannot use direct page addressing due to the way they are compiled.

==== Single Source File Format ====

<code>********************************************************************</code>
<code>* [Program Name]</code>
<code>* [Description]</code>
<code>*</code>
<code>* by [Author Name]</code>
<code>*</code>
<code>* Edt/Rev YYYY/MM/DD Modified by</code>
<code>* Comment</code>
<code>* ------------------------------------------------------------------</code>
<code> nam [executablename]</code>
<code> ttl [Full Program Name]</code>
<code></code>
<code> ifp1</code>
<code> use defsfile</code>
<code> endc</code>
</code>
<code>tylg set Prgrm+Objct</code>
<code>atrv set ReEnt+rev</code>
<code>rev set $00</code>
<code>edition set 1</code>
</code>
<code> mod eom,name,tylg,atrv,start,size</code>
</code>
<code> [Variables go here]</code>
</code>
<code>size equ .</code>
<code>name fcs /executablename/</code>
<code> fcb edition</code>
</code>
<code>start</code>
</code>
<code> [Program Code Here]</code>
<code> </code>
<code> os9 F$Exit</code>
</code>
<code> emod</code>
<code>eom equ *</code>
<code> end</code>

==== Multiple Source File Format ====

=== Data Modules ===
Here is a portion of the font module, which is a data module in NitrOS-9.

<code> nam font</code>

<code> ttl F256 font</code>

<code> use defsfile</code>

<code>tylg set Data</code>

<code>atrv set ReEnt+rev</code>

<code>rev set $01</code>

<code> mod eom,name,tylg,atrv,start,0</code>

<code>name fcs /font/</code>

<code>start</code>

<code>L0000 fcb $00,$00,$00,$00,$00,$00,$00,$00 </code>

<code>L0008 fcb $7C,$82,$AA,$82,$BA,$92,$82,$7C </code>

<nowiki>*</nowiki>More data here

<code> emod</code>

<code>eom equ *</code>

<code> end</code>

== Writing Position Independent Code ==
All code in NitrOS-9 must be position independent. Addresses are not known until a program module is loaded and executed. All addressing must be "program counter relative addressing". All branch and long branch instructions are program counter relative.

Rules:

Use <code>BRA</code> and <code>LBRA</code> instead of <code>JMP</code>

Use <code>BSR</code> and <code>LBSR</code> instead of <code>JSR</code>

Use program counter relative indexed addressing for all load, store, arithmetic and logical instructions.

== Accessing Variables and Data Structures ==

== Accessing Table Data with PCR ==
__FORCETOC__

OS-9 Assembly Code Development

2024-09-29T21:41:45Z

Jfed: formatting

== Overview ==
Each process in NitrOS-9 is allocated its own 64K address space. When run, the program object code is loaded into the end of the memory space, and the variables and data structures are loaded into the beginning. In addition, NitrOS-9 keeps an separate per-process MMU table (DAT Image), so you must use <code>F$MapBlk</code> to map and <code>F$ClrBlk</code> to unmap 8K blocks in your process' address space. The operating system has its own 64K address space as well.

When a new process is created, registers U, Y, DP and SP are set with U = start of data area, Y = end of data area, DP = page # of beginning page, SP = end of data area + 1. Each process includes its own execution and data directories, along with <code>std in</code>, <code>std out</code> and <code>std err</code>.

=== Memory and DAT Image ===
<code>mmap</code> and <code>pmap</code> output the current status of the memory in the system. <code>mmap</code> shows which memory blocks are currently in use. <code>pmap</code> shows the blocks that are mapped in the DAT Image for a particular process.
[[File:Mmappmap.png|none|thumb]]

== Program and Data Module Structure ==

There are 9 different types of modules in 4 possible languages:
{| class="wikitable"
|+
! colspan="3" |Module Types
!
! colspan="2" |Language
|-
|'''Code'''
|'''Module Type'''
|'''Name'''
|
|'''Code'''
|'''Language'''
|-
|$1x
|Program Module
|Prgm
|
|$x0
|Data (non-executable)
|-
|$2x
|Subroutine Module
|Sbrtn
|
|$x1
|6809 Object Code
|-
|$3x
|Multi-module
|Multi
|
|$x2
|BASIC09 I-Code
|-
|$4x
|Data Module
|Data
|
|$x3
|PASCAL I-Code
|-
|$5x-$Bx
|User-definable module
|
|
|$x4-$xF
|Reserved for Future Use
|-
|$Cx
|OS-9 System Module
|Systm
|
|
|
|-
|$Dx
|OS-9 File Manager Module
|FlMgr
|
|
|
|-
|$Ex
|OS-9 Device Driver Module
|Drivr
|
|
|
|-
|$Fx
|OS-9 Device Descriptor Module
|Devic
|
|
|
|}
The two most used will be Program Modules and Data Modules.

=== Program Modules ===
The format of the program module varies depending on whether you have a single source file for your program or multiple source files.

Note: multiple source files format cannot use direct page addressing due to the way they are compiled.

==== Single Source File Format ====

<code>********************************************************************</code>

<code>* [Program Name]</code>

<code>* [Description]</code>

<code>*</code>

<code>* by [Author Name]</code>

<code>*</code>

<code>* Edt/Rev YYYY/MM/DD Modified by</code>

<code>* Comment</code>

<code>* ------------------------------------------------------------------</code>

<code> nam [executablename]</code>

<code> ttl [Full Program Name]</code>

 
<code> ifp1</code> 
<code> use defsfile</code> 
<code> endc</code> 
 
<code>tylg set Prgrm+Objct</code> 
<code>atrv set ReEnt+rev</code> 
<code>rev set $00</code> 
<code>edition set 1</code> 
 
<code> mod eom,name,tylg,atrv,start,size</code> 
 
<code>[Variables go here]</code> 
 
<code>size equ .</code> 
<code>name fcs /executablename/</code> 
<code> fcb edition</code> 
 
<code>start</code> 
 
<code> [Program Code Here]</code> 
<code> </code> 
<code> os9 F$Exit</code> 
 
 
<code> emod</code> 
<code>eom equ *</code> 
<code> end</code> 

==== Multiple Source File Format ====

=== Data Modules ===
Here is a portion of the font module, which is a data module in NitrOS-9.

<code> nam font</code>

<code> ttl F256 font</code>

<code> use defsfile</code>

<code>tylg set Data</code>

<code>atrv set ReEnt+rev</code>

<code>rev set $01</code>

<code> mod eom,name,tylg,atrv,start,0</code>

<code>name fcs /font/</code>

<code>start</code>

<code>L0000 fcb $00,$00,$00,$00,$00,$00,$00,$00 </code>

<code>L0008 fcb $7C,$82,$AA,$82,$BA,$92,$82,$7C </code>

<nowiki>*</nowiki>More data here

<code> emod</code>

<code>eom equ *</code>

<code> end</code>

== Writing Position Independent Code ==
All code in NitrOS-9 must be position independent. Addresses are not known until a program module is loaded and executed. All addressing must be "program counter relative addressing". All branch and long branch instructions are program counter relative.

Rules:

Use <code>BRA</code> and <code>LBRA</code> instead of <code>JMP</code>

Use <code>BSR</code> and <code>LBSR</code> instead of <code>JSR</code>

Use program counter relative indexed addressing for all load, store, arithmetic and logical instructions.

== Accessing Variables and Data Structures ==

== Accessing Table Data with PCR ==
__FORCETOC__

OS-9 Assembly Code Development

2024-09-29T21:39:10Z

Jfed: format source code

== Overview ==
Each process in NitrOS-9 is allocated its own 64K address space. When run, the program object code is loaded into the end of the memory space, and the variables and data structures are loaded into the beginning. In addition, NitrOS-9 keeps an separate per-process MMU table (DAT Image), so you must use <code>F$MapBlk</code> to map and <code>F$ClrBlk</code> to unmap 8K blocks in your process' address space. The operating system has its own 64K address space as well.

When a new process is created, registers U, Y, DP and SP are set with U = start of data area, Y = end of data area, DP = page # of beginning page, SP = end of data area + 1. Each process includes its own execution and data directories, along with <code>std in</code>, <code>std out</code> and <code>std err</code>.

=== Memory and DAT Image ===
<code>mmap</code> and <code>pmap</code> output the current status of the memory in the system. <code>mmap</code> shows which memory blocks are currently in use. <code>pmap</code> shows the blocks that are mapped in the DAT Image for a particular process.
[[File:Mmappmap.png|none|thumb]]

== Program and Data Module Structure ==

There are 9 different types of modules in 4 possible languages:
{| class="wikitable"
|+
! colspan="3" |Module Types
!
! colspan="2" |Language
|-
|'''Code'''
|'''Module Type'''
|'''Name'''
|
|'''Code'''
|'''Language'''
|-
|$1x
|Program Module
|Prgm
|
|$x0
|Data (non-executable)
|-
|$2x
|Subroutine Module
|Sbrtn
|
|$x1
|6809 Object Code
|-
|$3x
|Multi-module
|Multi
|
|$x2
|BASIC09 I-Code
|-
|$4x
|Data Module
|Data
|
|$x3
|PASCAL I-Code
|-
|$5x-$Bx
|User-definable module
|
|
|$x4-$xF
|Reserved for Future Use
|-
|$Cx
|OS-9 System Module
|Systm
|
|
|
|-
|$Dx
|OS-9 File Manager Module
|FlMgr
|
|
|
|-
|$Ex
|OS-9 Device Driver Module
|Drivr
|
|
|
|-
|$Fx
|OS-9 Device Descriptor Module
|Devic
|
|
|
|}
The two most used will be Program Modules and Data Modules.

=== Program Modules ===
The format of the program module varies depending on whether you have a single source file for your program or multiple source files.

Note: multiple source files format cannot use direct page addressing due to the way they are compiled.

==== Single Source File Format ====

<code>********************************************************************</code> 
<code>* [Program Name]</code> 
<code>* [Description]</code> 
<code>*</code> 
<code>* by [Author Name]</code> 
<code>*</code> 
<code>* Edt/Rev YYYY/MM/DD Modified by</code> 
<code>* Comment</code> 
<code>* ------------------------------------------------------------------</code> 
<code>nam [executablename]</nowiki></code> 
<code> ttl [Full Program Name]</code> 
 
<code> ifp1</code> 
<code> use defsfile</code> 
<code> endc</code> 
 
<code>tylg set Prgrm+Objct</code> 
<code>atrv set ReEnt+rev</code> 
<code>rev set $00</code> 
<code>edition set 1</code> 
 
<code> mod eom,name,tylg,atrv,start,size</code> 
 
<code>[Variables go here]</code> 
 
<code>size equ .</code> 
<code>name fcs /executablename/</code> 
<code> fcb edition</code> 
 
<code>start</code> 
 
<code> [Program Code Here]</code> 
<code> </code> 
<code> os9 F$Exit</code> 
 
 
<code> emod</code> 
<code>eom equ *</code> 
<code> end</code> 

==== Multiple Source File Format ====

=== Data Modules ===
Here is a portion of the font module, which is a data module in NitrOS-9.

<code> nam font</code>

<code> ttl F256 font</code>

<code> use defsfile</code>

<code>tylg set Data</code>

<code>atrv set ReEnt+rev</code>

<code>rev set $01</code>

<code> mod eom,name,tylg,atrv,start,0</code>

<code>name fcs /font/</code>

<code>start</code>

<code>L0000 fcb $00,$00,$00,$00,$00,$00,$00,$00 </code>

<code>L0008 fcb $7C,$82,$AA,$82,$BA,$92,$82,$7C </code>

<nowiki>*</nowiki>More data here

<code> emod</code>

<code>eom equ *</code>

<code> end</code>

== Writing Position Independent Code ==
All code in NitrOS-9 must be position independent. Addresses are not known until a program module is loaded and executed. All addressing must be "program counter relative addressing". All branch and long branch instructions are program counter relative.

Rules:

Use <code>BRA</code> and <code>LBRA</code> instead of <code>JMP</code>

Use <code>BSR</code> and <code>LBSR</code> instead of <code>JSR</code>

Use program counter relative indexed addressing for all load, store, arithmetic and logical instructions.

== Accessing Variables and Data Structures ==

== Accessing Table Data with PCR ==
__FORCETOC__

OS-9 Assembly Code Development

2024-09-29T21:32:25Z

Jfed: /* Single Source File Format */

OS-9 Assembly Code Development

2024-09-29T21:21:13Z

Jfed: /* Single Source File Format */

== Overview ==
Each process in NitrOS-9 is allocated its own 64K address space. When run, the program object code is loaded into the end of the memory space, and the variables and data structures are loaded into the beginning. In addition, NitrOS-9 keeps an separate per-process MMU table (DAT Image), so you must use <code>F$MapBlk</code> to map and <code>F$ClrBlk</code> to unmap 8K blocks in your process' address space. The operating system has its own 64K address space as well.

When a new process is created, registers U, Y, DP and SP are set with U = start of data area, Y = end of data area, DP = page # of beginning page, SP = end of data area + 1. Each process includes its own execution and data directories, along with <code>std in</code>, <code>std out</code> and <code>std err</code>.

=== Memory and DAT Image ===
<code>mmap</code> and <code>pmap</code> output the current status of the memory in the system. <code>mmap</code> shows which memory blocks are currently in use. <code>pmap</code> shows the blocks that are mapped in the DAT Image for a particular process.
[[File:Mmappmap.png|none|thumb]]

== Program and Data Module Structure ==

There are 9 different types of modules in 4 possible languages:
{| class="wikitable"
|+
! colspan="3" |Module Types
!
! colspan="2" |Language
|-
|'''Code'''
|'''Module Type'''
|'''Name'''
|
|'''Code'''
|'''Language'''
|-
|$1x
|Program Module
|Prgm
|
|$x0
|Data (non-executable)
|-
|$2x
|Subroutine Module
|Sbrtn
|
|$x1
|6809 Object Code
|-
|$3x
|Multi-module
|Multi
|
|$x2
|BASIC09 I-Code
|-
|$4x
|Data Module
|Data
|
|$x3
|PASCAL I-Code
|-
|$5x-$Bx
|User-definable module
|
|
|$x4-$xF
|Reserved for Future Use
|-
|$Cx
|OS-9 System Module
|Systm
|
|
|
|-
|$Dx
|OS-9 File Manager Module
|FlMgr
|
|
|
|-
|$Ex
|OS-9 Device Driver Module
|Drivr
|
|
|
|-
|$Fx
|OS-9 Device Descriptor Module
|Devic
|
|
|
|}
The two most used will be Program Modules and Data Modules.

=== Program Modules ===
The format of the program module varies depending on whether you have a single source file for your program or multiple source files.

Note: multiple source files format cannot use direct page addressing due to the way they are compiled.

==== Single Source File Format ====
<nowiki>********************************************************************</nowiki>

<nowiki>*</nowiki> [Program Name]

<nowiki>*</nowiki> test for mouse

<nowiki>*</nowiki>

<nowiki>*</nowiki> by [Author Name]

<nowiki>*</nowiki>

<nowiki>*</nowiki> Edt/Rev YYYY/MM/DD Modified by

<nowiki>*</nowiki> Comment

<nowiki>*</nowiki> ------------------------------------------------------------------

<code> nam [ExecutableName]</code>

<code> ttl [Full Program Name]</code>

<code> ifp1</code>

<code> use defsfile</code>

<code> endc</code>

<code>tylg set Prgrm+Objct</code>

<code>atrv set ReEnt+rev</code>

<code>rev set $00</code>

<code>edition set 1</code>

<code> mod eom,name,tylg,atrv,start,size</code>

<code>[Variables go here]</code>

<code>size equ .</code>

<code>name fcs /drawtest/</code>

<code> fcb edition</code>

<code>start

<code>[Program Code Here]</code>

<code> os9 F$Exit</code>

<code> emod</code>

<code>eom equ *</code>

<code> end</code>

==== Multiple Source File Format ====

=== Data Modules ===
Here is a portion of the font module, which is a data module in NitrOS-9.

<code> nam font</code>

<code> ttl F256 font</code>

<code> use defsfile</code>

<code>tylg set Data</code>

<code>atrv set ReEnt+rev</code>

<code>rev set $01</code>

<code> mod eom,name,tylg,atrv,start,0</code>

<code>name fcs /font/</code>

<code>start</code>

<code>L0000 fcb $00,$00,$00,$00,$00,$00,$00,$00 </code>

<code>L0008 fcb $7C,$82,$AA,$82,$BA,$92,$82,$7C </code>

<nowiki>*</nowiki>More data here

<code> emod</code>

<code>eom equ *</code>

<code> end</code>

== Writing Position Independent Code ==
All code in NitrOS-9 must be position independent. Addresses are not known until a program module is loaded and executed. All addressing must be "program counter relative addressing". All branch and long branch instructions are program counter relative.

Rules:

Use <code>BRA</code> and <code>LBRA</code> instead of <code>JMP</code>

Use <code>BSR</code> and <code>LBSR</code> instead of <code>JSR</code>

Use program counter relative indexed addressing for all load, store, arithmetic and logical instructions.

== Accessing Variables and Data Structures ==

== Accessing Table Data with PCR ==
__FORCETOC__

OS-9 Assembly Code Development

2024-09-29T21:14:49Z

Jfed: /* Single Source File Format */

== Overview ==
Each process in NitrOS-9 is allocated its own 64K address space. When run, the program object code is loaded into the end of the memory space, and the variables and data structures are loaded into the beginning. In addition, NitrOS-9 keeps an separate per-process MMU table (DAT Image), so you must use <code>F$MapBlk</code> to map and <code>F$ClrBlk</code> to unmap 8K blocks in your process' address space. The operating system has its own 64K address space as well.

When a new process is created, registers U, Y, DP and SP are set with U = start of data area, Y = end of data area, DP = page # of beginning page, SP = end of data area + 1. Each process includes its own execution and data directories, along with <code>std in</code>, <code>std out</code> and <code>std err</code>.

=== Memory and DAT Image ===
<code>mmap</code> and <code>pmap</code> output the current status of the memory in the system. <code>mmap</code> shows which memory blocks are currently in use. <code>pmap</code> shows the blocks that are mapped in the DAT Image for a particular process.
[[File:Mmappmap.png|none|thumb]]

== Program and Data Module Structure ==

There are 9 different types of modules in 4 possible languages:
{| class="wikitable"
|+
! colspan="3" |Module Types
!
! colspan="2" |Language
|-
|'''Code'''
|'''Module Type'''
|'''Name'''
|
|'''Code'''
|'''Language'''
|-
|$1x
|Program Module
|Prgm
|
|$x0
|Data (non-executable)
|-
|$2x
|Subroutine Module
|Sbrtn
|
|$x1
|6809 Object Code
|-
|$3x
|Multi-module
|Multi
|
|$x2
|BASIC09 I-Code
|-
|$4x
|Data Module
|Data
|
|$x3
|PASCAL I-Code
|-
|$5x-$Bx
|User-definable module
|
|
|$x4-$xF
|Reserved for Future Use
|-
|$Cx
|OS-9 System Module
|Systm
|
|
|
|-
|$Dx
|OS-9 File Manager Module
|FlMgr
|
|
|
|-
|$Ex
|OS-9 Device Driver Module
|Drivr
|
|
|
|-
|$Fx
|OS-9 Device Descriptor Module
|Devic
|
|
|
|}
The two most used will be Program Modules and Data Modules.

=== Program Modules ===
The format of the program module varies depending on whether you have a single source file for your program or multiple source files.

Note: multiple source files format cannot use direct page addressing due to the way they are compiled.

==== Single Source File Format ====
<nowiki>********************************************************************</nowiki>

<nowiki>*</nowiki> [Program Name]

<nowiki>*</nowiki> test for mouse

<nowiki>*</nowiki>

<nowiki>*</nowiki> by [Author Name]

<nowiki>*</nowiki>

<nowiki>*</nowiki> Edt/Rev YYYY/MM/DD Modified by

<nowiki>*</nowiki> Comment

<nowiki>*</nowiki> ------------------------------------------------------------------

<code> nam [ExecutableName]</code>
<code> ttl [Full Program Name]</code>
<code> ifp1</code>
<code> use defsfile</code>
<code> endc</code>

<code>tylg set Prgrm+Objct</code>

<code>atrv set ReEnt+rev</code>

<code>rev set $00</code>

<code>edition set 1</code>

<code> mod eom,name,tylg,atrv,start,size</code>

<code>[Variables go here]</code>

<code>size equ .</code>

<code>name fcs /drawtest/</code>

<code> fcb edition</code>

<code>start

<code>[Program Code Here]</code>

<code> os9 F$Exit</code>

<code> emod</code>

<code>eom equ *</code>

<code> end</code>

==== Multiple Source File Format ====

=== Data Modules ===
Here is a portion of the font module, which is a data module in NitrOS-9.

<code> nam font</code>

<code> ttl F256 font</code>

<code> use defsfile</code>

<code>tylg set Data</code>

<code>atrv set ReEnt+rev</code>

<code>rev set $01</code>

<code> mod eom,name,tylg,atrv,start,0</code>

<code>name fcs /font/</code>

<code>start</code>

<code>L0000 fcb $00,$00,$00,$00,$00,$00,$00,$00 </code>

<code>L0008 fcb $7C,$82,$AA,$82,$BA,$92,$82,$7C </code>

<nowiki>*</nowiki>More data here

<code> emod</code>

<code>eom equ *</code>

<code> end</code>

== Writing Position Independent Code ==
All code in NitrOS-9 must be position independent. Addresses are not known until a program module is loaded and executed. All addressing must be "program counter relative addressing". All branch and long branch instructions are program counter relative.

Rules:

Use <code>BRA</code> and <code>LBRA</code> instead of <code>JMP</code>

Use <code>BSR</code> and <code>LBSR</code> instead of <code>JSR</code>

Use program counter relative indexed addressing for all load, store, arithmetic and logical instructions.

== Accessing Variables and Data Structures ==

== Accessing Table Data with PCR ==
__FORCETOC__