x16community / x16-docs Goto Github PK
View Code? Open in Web Editor NEWCommander X16 Documentation (CC BY-SA)
Commander X16 Documentation (CC BY-SA)
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.
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.
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
These are bold, i.e. new compared to C64:
$08 BACKSPACE
$09 TAB
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?
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:
Some thoughts on handling the deprecation:
Warning: executed deprecated opcode xx
My thoughts are:
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
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:
; 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
; ******** 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.
6 coding best practices for beginner programmers here
Comment (computer programming here
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.
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.
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.
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:
x16-docs/VERA Programmer's Reference.md
Line 187 in 531f528
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:
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.
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
x16-docs/VERA Programmer's Reference.md
Lines 577 to 580 in 531f528
This is contradicted by text further down that indicates (correctly!) that it flips palette bit 7, see line 681.
x16-docs/VERA Programmer's Reference.md
Lines 675 to 682 in 531f528
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
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:
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
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).
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.