Documentation for several kernal routines is missing / incomplete.

This issue is for the CBM kernal routines that the X16 inherited from the CBM/C64 kernal rom.
These are documented elsewhere on the internet, but should be documented here as well.

• provide a list of "accepted" reference docs urls for the original CBM rom documentation. There are a few links but people don't seem to find them/read them?
• provide at least a minimal description for every missing kernal routine @m00dawg
• precisely document the routines. mention any differences with the originals (for example MEMTOP)
• get rid of the origin column
• change the register columns in the kernal API table to inputs and outputs (and maybe preserves)? how?

Note that the Floating Point routines are excluded from this as well, they already have their own page.

Add the BASLOAD documentation to the PRG.

I'd do this right now, but I'm tied up at work.

Based on the report at https://cx16forum.com/forum/viewtopic.php?p=30996#p30996

The table at clock_set_date_time shows the weekday as 0-6. This is incorrect, and the clock requires a value of 1-7.

I remember having this same discussion before in another context. Doc here needs to be fixed to line up with the RTC's specifications.

Might need to do a quick pass of the C64 table to make sure we have everything.

ROM bank 13 and 14 are both in use and unused in the documentation

13-14 X16EDIT The built-in text editor
13-31 – [Currently unused]

I've never seen them displayed in that order. The emu and most online documentation show bit 0 (carry) on the right.

X16Community/x16-rom#276

Title. This was originally present in place of the current color chart - this would not remove said chart, but would be added alongside it, or at the end as an appendix, should it be too large to include inline.

PAGE DOWN and PAGE UP are new compared to C64, but are not bold.
$02 PAGE DOWN PAGE UP $82
https://github.com/X16Community/x16-docs/blob/master/X16%20Reference%20-%2002%20-%20Editor.md#new-control-characters

Including the hex value which is to be written to VRAM.

Eg:

These are bold, i.e. new compared to C64:

$08     BACKSPACE
$09     TAB

in https://github.com/X16Community/x16-docs/blob/master/X16%20Reference%20-%2002%20-%20Editor.md#new-control-characters

On input using 10 GET K$:PRINT HEX$(ASC(K$)):GOTO 10 the TAB key sends $09, but BS sends $14 (i.e. the old code), but on output using e.g. PRINT CHR$(8) they actually now work as the old codes:

$08     Disable Shift + C=
$09     Enable Shift + C=

I think both input and output should be documented for those control codes that do different things on input and output. The old codes are documented here:
https://www.c64-wiki.com/wiki/PETSCII_Codes_in_Listings

Control over which parts are written are chosen by the value written to DATA0 or DATA1. The value written is treated as a nibble mask where a 0-bit writes the data and a 1-bit masks the data from being written.In other words, writing a 0 will flush the entire 32-bit cache. Writing #%00001111 will write the second and third byte in the cache to VRAM in the second and third memory locations in the 4-byte-aligned region.

In the paragraph above some of the language implies something that isn't happening.

writing a 0 will flush the entire 32-bit cache

The word 'flush' implies that the cache will be empty, or reset after writing it.

Writing #%00001111 will write the second and third byte

Is 'second' and 'third' bytes the right language? Byte 0, 1, 2 or 3 would make sense, but the second byte isnt byte 2. Maybe using the same language as the table (so L, M, H, and U) would be easier to understand?

https://github.com/X16Community/x16-docs/blob/master/X16%20Reference%20-%2010%20-%20VERA%20FX%20Reference.md#writing-the-cache-to-vram

See

X16Community/x16-rom#246

and for some explanation of the details: X16Community/x16-rom#233

This topic is mostly a place for discussion and input RE emulator handling of the Rockwell instructons.

The specific instructions are: BBS0-BBS7, BBR0-BBR7, RMB0-RMB7, and SMB0-SMB7. They are easy to identify: if an opcode ends in 7 or F, it's one of these groups. These are collectively known as the Rockwell instructions.

The questions are:

1. Is the 65C816 going to become standard equipment at some point? This seems like a question for David and Kevin, and we really need this answered before any other decisions can be made.
   a. If the 65C816 is made standard for Gen-2, then we need to gracefully deprecate the 65C02 instructions.
   b. If it is not made standard, then this whole discussion can be dismissed.

Some thoughts on handling the deprecation:

1. Disable the opcodes and crash the emu when an x7 or xF opcode is executed. This will help prevent people from including those instructions in new code, since it will fail in the emulator.
2. Warn the user via the console: Warning: executed deprecated opcode xx
3. Add a command line switch to either override or enable the above actions.
4. If 65C816 emulation is added to the emulator, should we consider flagging these opcodes in the 816 emulation, to help track down potential bugs in legacy code?

My thoughts are:

1. Never disable the instructions.
2. Flag the opcode use in 65C02 mode by writing a message to the console.
3. Add a "-testc02" flag that halts the CPU when a Rockwell instruction is executed.

The -testc02 flag should work the same, whether 65C02 or 65C816 emulation is active, helping developers look for this issue no matter which CPU they are running.

With so many retro computing enthusiasts out there wanting to use a steel miniAtx case is it possible to have the dimensions of the plug outlets so a I/O backplate can be created?

something like this
https://i.ebayimg.com/images/g/5w8AAOSweExjkp0V/s-l1600.jpg?fbclid=IwAR3CwwSlezxMCKPeSenXkcUFCdDxkxTBqlmZbupN_N6xjzqx8SVZ20SGd48

audio_init = $C09F

psg_init and ym_init already are in the docs
https://github.com/X16Community/x16-docs/blob/master/X16%20Reference%20-%2009%20-%20Sound%20Programming.md#audio-api-routines

Coding standards

I suggest that a coding standards document be created that will ensure that code written for use in educational purpurses be easy to read and understand the purpose of each function or routine.
for example:

• in assemblerly or ASM code

 ; acme -f cbm -o cx16maze.prg cx16-maze.asm

  !zone Main {
  *=$0801	        ; Assembled code should start at $0801
                        ; (where BASIC programs start)
		        ; The real program starts at $0810 = 2064
  !byte $0C,$08		; $080C - pointer to next line of BASIC code
  !byte $0A,$00		; 2-byte line number ($000A = 10)
  !byte $9E		; SYS BASIC token
  !byte $20		; [space]
  !byte $32,$30,$36,$34	; $32="2",$30="0",$36="6",$34="4"
			  ; (ASCII encoded nums for dec starting addr)
  !byte $00		; End of Line
  !byte $00,$00		; This is address $080C containing
			  ; 2-byte pointer to next line of BASIC code
			  ; ($0000 = end of program)
  *=$0810			; Here starts the real program

from cx16maze.asm by JimmyDansbo here

• the first line should be what assembler is used to compile and any switches
  because there are many compilers available not all of them work with the code making it difficult for the begginners to comprhend

• comment code that defines the purpose

• Use appropriate naming conventions.

• in BASIC
  File Header
  Start each file with a description of its contents.

Every file must have a top-level comment including a brief overview of its contents. A copyright notice and author information are optional.
Date of creation

10 REM ANIMATES N RANDOMLY COLORED BALLS BOUNCING AROUND THE SCREEN
20 REM THE SCREEN IS 40 BY 30 AND THE BALL IS TEXT CHARACTER 81
30 SCREEN 3                        : REM SWITCH SCREEN TO 40 CHARACTER MODE
40 PRINT "ENTER HOW MANY BALLS TO DRAW (1-255)?"
50 INPUT N
60 IF N<1 OR N>255 THEN 40         : REM IF INPUT IS OUT OF RANGE, ASK AGAIN
70 PRINT CHR$(147);                : REM CLEAR SCREEN, DO NOT MOVE CURSOR
80 REM INITIALIZE BALL INFO ARRAYS
90 DIM BX(N): DIM BY(N): DIM BC(N) : REM BALL POSITION AND COLOR
100 DIM DX(N): DIM DY(N)           : REM BALL DIRECTION
110 FOR B=0 TO N
120 BX(B)=INT(RND(1)*40)*2+1       : REM RANDOM COLUMN (X VALUE)
130 BY(B)=INT(RND(1)*30)*$100      : REM RANDOM ROW (Y VALUE)
140 BC(B)=INT(RND(1)*14)+1         : REM RANDOM BALL COLOR
150 DX(B)=INT(RND(1)*2)            : REM RANDOM X DIRECTION
160 DY(B)=1                        : REM MOVE DOWN
170 NEXT B

from balls.bas by David Murray

References

; ******** Kernal APIs - C64 API can be found here: *******
; http://sta.c64.org/cbm64krnfunc.html

from cx16maze.asm by JimmyDansbo here

References are important for begginners so that they can learn.

Sires

6 coding best practices for beginner programmers here
Comment (computer programming here

Credits

where available credits should be given to the code used or based upon

Appendix C says
BNE
Branch to LABEL if the negative flag is set.

Not right... Should say

BNE
Branch to LABEL if zero flag is not set.

BSOUT / CHROUT (and PRIMM since it calls BSOUT) will cli before returning. This is legacy C64 behavior. We should document that it does this.

C64 disasm rom addr $E6B3 @ https://www.pagetable.com/c64ref/c64disasm/ near the label LOP2

Comes up in Discord chat every so often.

I have seen the mentioning of the jumpers of various settings, what would be useful is a outline diagram displaying the jumper locations in a grid format on the motherboard.

I suggest that information about the default location of the text layer and the character set is added to the table "VRAM address space layout". You can make a VPEEK, you get bits 16-9 of the address, and then you can calculate this yourself. But why not write it in the documentation directly? This is what I miss:

$1B000 - $1EBFF Default location of screen memory for text layer (layer 1)
$1F000 - $1F7FF Default location of character set

The Vera fx documentation was very difficult to understand, especially what the different features were intended to do, and how to use them correctly.

Chapter 8's sole contribution is a memory map of the default VERA data layout, which can easily be folded into the VERA reference.

I suggest we remove chapter 8 and move chapters 2-7 up by one number, then move the "Getting started" into chapter 2's spot.

The behaviour of the LOAD command when loading into HiRam isn't described anywhere in the documentation

This probably needs its own heading \ section as it is under the 'transparency writes' heading.

When "one-byte cache cycling" is turned on and DATA0 or DATA1 is written to, the byte at the current cache index is written to VRAM. When "Cache write enable" is set as well, the byte is duplicated 4 times when writing to VRAM.

Does the byte written have any influence here? Does it get ignored? Follow the cache-write pattern? 'Duplicated' 4 times on a 4byte aligned boundary? Does it combine with the 'transparent' flag? Either way its worth explicitly stating what happens.

https://github.com/X16Community/x16-docs/blob/master/X16%20Reference%20-%2010%20-%20VERA%20FX%20Reference.md#transparency-writes

A long press of power (with the supporting code in a future release of the SMC) to power on will launch diags in bank #16 (#$10).

This capability depends on X16Community/x16-smc#32 being merged and published as a release

BANK n,16 : SYS $C000 will also start diagnostics on a working system

The behavior of the diagnostics itself will need to be mentioned in docs as well.

I've made a draft block diagram for the X16 to the best of my effort and with some help from the Discord community.

The diagram could be included in the docs.

I think it would help new users to quickly grasp what different parts there are and how they are linked to each other.

And, from time to time you read online people that claim that the X16 design is convoluted, unclean and more when in fact the system design is pretty simple and straightforward. Maybe at least some of that unfounded critique could go away if we show the simplicity of the system.

I have no previous experience of making block diagrams, and I expect that you might want to change it (a lot). It's also OK if someone else wants to redo it from scratch.

X16 Block Diagram.odg

X16 Block Diagram.pdf

Relates to #85 but I thought is more specific. Chapter 11 has great information on how to use CMDR-DOS in BAISC but lacks examples for use in assembly making it unclear for folks that may know assembly well but do not know BASIC since some knowledge is needed to know how to break apart the BASIC commands into what would be the assembly counterparts (SETLFS, SETNAM, OPEN, etc.).

Add the EDIT documentation to the PRG.

Also document what parts of memory EDIT uses, so that programmers can steer clear of those parts of memory if they need to interact with the editor. (Probably suggest stubbing out a "re-loader" in a place that doesn't get hammered.)

I can't find an obvious listing of the character sets in ISO, PETSCII, and Screen Code order.

Suggest adding all 3, with a simple algorithm to convert between PETSCII and Screen Codes for developers.

Using Super Famicom Developement wiki Controler port pinout as reference pin 5 and pin 6 should be connected to Data2 and IObit respectively.

Those two pins are used by non-joypad periperials such as lightguns (unlikely to work with todays lcd monitors) and multitaps. The latter allows for four joypads to be connected via it to the controler port. For Commander X16 this means that with four multitaps connected to the four SNES controler ports you can have a local 16 player games.

Only came across this potential issue recently when starting to dig into the documentation in earnest.

A lot of the Kernal API functions (especially concerning disk access) are described in a way that's not accessible to someone who has no idea how the C64 Kernal works.

Not sure which is right, would need to be checked on real hardware.

https://github.com/X16Community/x16-docs/blob/master/X16%20Reference%20-%2012%20-%20IO%20Programming.md#chapter-12-io-programming

Following discussions on Discord, it looks like the power LED is always lit, rather than having the 256 brightness levels I had inferred from this table.

For example:

X Increment (-2:-9) (signed)

I presumed that if it said something like (7:0) then each bit represents bits 7 to 0 of the larger number (ie the low byte).

I understand that the X Increment is signed, but I still have no idea what the numbers represent. I tried to understand it through the VERA FX Tutorial, but it's inconsistent, and it seems to set the slope increment to really large numbers (-110, 380). I believe the top 6 bits are used by the line helper maybe?

The documentation is very hard to understand.

The spec is over here: https://github.com/tildearrow/furnace/blob/9d4a900d81879a176e2b5256b742187625930f31/papers/zsm-format.md?plain=1#L35

Would be nice to mirror it as an appendix to x16-docs since it's essentially the standard for playback solution on the X16

Redirect from: #129

From @tallLeRoy :

Appendix C says
BNE
Branch to LABEL if the negative flag is set.

Not right... Should say

BNE
Branch to LABEL if zero flag is not set.

Given the many options available on the x16 to load and save files: write a separate paragraph (or chapter!?) to explain the file I/O routines in the kernal. Don't try to do this within the explanations of the various routines in the big list.

This paragraph/chapter could contain:

• explain the concepts of device numers, logical file numbers, secondary
• what is the general setup to load/save stuff (setnam, setlfs, blah blah)
• explain headerfull and headerless loads (by the way, there's only headerfull saves right now I think?)
• detailed description of the routines and their parameters
• how to detect errors (flags, READST, reading the disk status messages)
• describe the benefits of MACPTR and MCIOUT and how to use them in a separate paragraph. Note that LOAD/SAVE already uses them for you.
• do we need to describe the use of the other low level routines for IEC serial communication (TALK etc?)

Btw: I feel programming language examples could be helpful but should be restricted to assembly code (or BASIC) here. How to call kernal stuff from C (which compiler?!), pascal, prog8 or whatever else is not the task of the system documentation to explain?

I dont think this is correct, it seems like 7-62 act like dcsel is 63.

Important: unless DCSEL values of 2-6 are used, the behavior of VERA is exactly the same as it was before the FX update. This ensures that the FX update is backwards compatible with traditional non-FX uses of VERA.

https://github.com/X16Community/x16-docs/blob/master/X16%20Reference%20-%2010%20-%20VERA%20FX%20Reference.md#dcsel

I suggest that high rresolution images and graphics be included for the purposes of promotion, use in documents, software and hardware so that the a high standard and quality be maintained throught the prohect,

These shall be available to the community under a license that allows the usage.

The long list of all the different uses of 9f29 to 9f2c in the different dcsel modes make the vera reference address table very difficult to read. One idea would be to move all the fx registers to the fx documentation.

The documentation currently says "T256C causes bit 7 of the color index to become 1", but the actual behavior is that the most significant bit of the palette offset is forced to 1 instead.

In other words, the documentation as written implies that colors 0..127 will be remapped to 128..255, when in reality T256C only changes colors 1..15 by remapping palette offsets 0..7 to 8..15.

The wording's kinda tricky in general because it's bit 3 of the palette offset, which is bit 7 of the attribute byte.

The current docs for the kernel screen_mode call do not list the valid screen modes that can be set.
Currently, the list of valid modes is in the beginning of the Editor chapter of the docs.
It would be nice if the modes were listed in the Kernel docs here:
https://github.com/X16Community/x16-docs/blob/master/X16%20Reference%20-%2004%20-%20KERNAL.md#function-name-screen_mode

Or at least have a link there to them in the Editor chapter.

So, the current documentation still says than non-1bpp modes ignore the T256C bit, see the doc snippet below, see the end of line 579

This is contradicted by text further down that indicates (correctly!) that it flips palette bit 7, see line 681.

Probably a good idea to correct this before anyone gets confused.

PS: Why are PDFs no longer being added to versions?

Looks like we missed a bold formatting thing here.

https://github.com/X16Community/x16-docs/blob/master/X16%20Reference%20-%2004%20-%20BASIC.md#linput

• new extapi16 call - must call in native mode, emx=0
• new extapi call (not specific to 65C816 support but first implemented in the branch)
• 65C816 opcode documentation
• X16 platform-specific considerations
  • Intro - what parts of the 65C816 processor are used and which are not used
  • How to incorporate 65C816 code in your user programs
    • How to call the CBM API in such code
    • How to relocate the stack
  • How to write 65C816 native interrupt handlers

Discussion of 65C816 support for the built-in MONitor utility.

These changes seem less important if we do not support native mode execution, but the community seems pretty intent on making native mode work, so we have some things to consider:

1. MON will need a new command to select 65C02, 65C816-emulation and 65C816-native mode, due to the additional register count, wider registers, and changed flag labels.
2. MON needs a way to actively track .a and .i flags (Memory Width and Index Width) during disassembly. This will require a new command, as well, to set the expected state of those flags prior to disassembly.
3. The new 65C816 instructions will need to be added to the assembly/disassembly table
4. The new address modes will need to be added
5. The status line needs to be extended, with 2-byte words for the wider registers, the additional bank registers, and the new labels for the flags (which will vary depending on the emulation flag.) This includes extending the memory space used as a proxy for the register values.
6. When assembling and disassembling, MONITOR will need to track the expected state of the Accumulator Register Width (.a) and Index Register Width (.i) flags.

The toughest nut to crack might be the BRK issue. We can't simply BRK in native mode, which means we lose access to the 16-bit registers. If we add a ROM routine named "brk16", a dev can JSR brk16, which will

• Set aside a block of memory as a native mode register proxy space, with room for all registers and an extra byte for the register display mode.
• Push all registers to the stack. Push flags LAST. (because flags affect 8/16 bit mode and so change the number of bytes on the stack)
• Set .a and .i to 8 bit operation
• Set emulation mode
• Pull data from the stack into the register proxy space.
• Execute the BRK instruction
• MON inspects the register display flag and displays the CPU state in one of 3 modes:
  • 65C02 mode
  • 65C816 running in emulation mode (8 bit registers, "B" register, include banks and .e flag.)
  • 65C816 running in native mode (16 bit registers, include banks, and .a .i flags)

The most the documentation does is mention that you can enable the mouse cursor without initializing the pointer sprite, but it doesn't actually clarify what you need to do to customize the mouse cursor (i.e., configure sprite 0).