neo6502 API words

[IanWitham]

I'm currently attempting to implement the block storage on neo6502.

I used the "draw line" API function a proof of concept for compiling a word that calls the API.

This made me wonder, would it be a good idea to implement some, all, or a bare minimum of other neo6502 API functions?

A few of them would be really convenient, like "clear screen". Having the graphics functions could be fun. However, this will all take space of course, so I thought I'd ask first!

[SamCoVT]

This is excellent! I have a neo6502 and I just got it drawing rectangles on the screen from TaliForth2 yesterday. I have been pondering block support for it but haven't had the time to dig in, so I'll be happy if you make some progress on that front. I don't have a compatible USB hub, so I can't have a USB thumb drive and a keyboard at the same time on my hardware, but the simulator works fine. I also wanted to figure out how to use the built in editor (it's a little weird as it operates line by line with callbacks where you have to feed it whatever line it's on - it also has virtually zero documentation).

For quick prototyping, you can write test words in Forth and place them in forth_code/user_words.fs or forth_code/forth_words.fs. These two files are added into the binary (as a string) and compiled when Tali first boots. Do note that there is less than 1K left with Tali starting at $a000 (that was chosen so you could return to neobasic with bye). If you need more room, you can always lower the starting address. $8000 is the more normal starting address for Tali. You could also turn off some of the features you don't need using TALI_OPTIONAL_WORDS in the platform file.

It looks like you are already writing new forth words in assembly. Because those words will be neo6502 specific, the best place to put them will be in the platform file. There are a few minor changes that need to take place to have words in the platform file, and I've created a branch platform/neo6502 that you can check out with those changes and an example word (you may want to check this out in a different location as it will replace/remove changes you have already made while experimenting). There is a testword (named testword, of course) already created that just puts 5 on the data stack so you can see how it works. Your new words will need to have their headers created BEFORE you include taliforth.asm in the platform file. You are welcome to remove the testword once you start adding your own words.

If you want to issue pull requests against the platform/neo6502 branch, then we can work together there until you like it and then I can merge everything into the master branch. We can use this issue for general discussion, so I'll leave it open for now.
If you need any help with anything (Tali, tass65, git) just let me know.

[IanWitham]

Thanks. That's an amazing orientation!

By the way, there seems to be an API function for loading BASIC. It may not be necessary to keep it resident in memory while TaliForth is running.

[SamCoVT]

I found that API function. It looks like it loads basic at $0800 and also puts the starting vector into zero page at locations 00 and 01. You could/should modify Tali's kernel_bye routine in the platform file (which currently just runs the brk instruction) to invoke that API function and then do a jmp (0) to start it.

One other detail to consider - loading Tali using basic requires the load and sys command to work properly, meaning load cannot load Tali on top of BASIC in a way that would prevent sys from working as the next command. You can give the simulator an image and starting address, but on the real hardware you'll use neoBASIC to do the loading and then sys to jump to the starting address. A quick search of the code shows that neoBASIC currently loads between $800 and something less than $5000, so it's likely safe to just load at $8000 (Tali's standard location on most platforms). The $A000 used in the current platform file looks like it is being overly cautious.

[SamCoVT]

I checked the BRK handler, and it already loads basic and jumps to it, so on second though, just leave the BRK for kernel_bye in the platform file. That routine lives at $FC00, so it's unlikely to be clobbered by BASIC or Tali.

[IanWitham]

Quick question..,.

When I load Taliforth the X register contains $76, according to the emulator's debug monitor.

I push a value onto the stack and now the X register contains $74. By looking at how words are implemented I would expect the value I just pushed to be at addresses $74--$75.

However, it is at addresses $76--$77 (confirmed with @ .) Is this correct and I'm missing something about the implementation, or could this be a bug in the Emulator's built in monitor? (i.e. reporting the wrong contents of the X register). Cheers

[SamCoVT]

What Tali starts, the X register should have $78. When you place a value on the stack, it should decrement X twice (to $76) and then place the value there in little endian format, so the value will be at $76 and $77.

There's a diagram in the manual (I'll recommend using docs/manual.pdf). You can search for "How Tali Forth Works" and shortly after the memory map is the "The Data Stack" section that has a description and diagram. It's on page 70 of the PDF (which is page 74 in my PDF reader).

It sounds like everything is behaving as expected except the X register is somehow showing $76 at start. That's the only odd thing from your description.

If you have placed things in user_words.fs or forth_words.fs to have them autoload when Tali starts, then it's possible something got left on the stack. You can use .s to print the depth of the stack and it's contents. With an empty stack, it should respond <0> ok

How do you get into the debugger while Tali is running? I just created a word and compiled opcode 3 to get into it, if I remember correctly.

: debug [ 3 c, ] ;

[SamCoVT]

Also, here's a word named .x to print the current value of x directly from Tali.

assembler-wordlist >order  \ Bring in the assembler.
: .x txa push-a . ;
previous                   \ Remove the assembler wordlist from the search order.

You'll probably want to switch to hex first. With an empty stack, I get:

.x 78  ok

[IanWitham]

.x says $78. The debugger says $76. It looks like it is indeed a bug in the debugger(!)

To launch the debug view, hit F6 in the emulator. Hit F5 to escape.

Hold shift and enter a 16-bit hex address to view that area of memory.

[SamCoVT]

It looks like the neo6502 kernel might use X, but I can't see exactly where in the expected code path used to wait for a keypress. I do see some locations where phx and plx are used in the kernel. Check the address you are on. If it's $FC00 or greater, you are in the kernel.

I didn't see a way to set a breakpoint at a particular location (it looks like you have to step to the spot and then press F9 to set the breakpoint there). That's annoying because you will be stuck in the kernel while waiting for a key, and you can't press a key to give to Tali while in the debugger. You are 100% going to end up in the kernel if you press F6 while Tali is waiting for a keypress because the KReadCharacter routine is blocking (it waits in the kernel for the key to arrive).

Using opcode 3 to enter the debugger directly from Tali seems to work and shows the correct value for X in the debugger. You can use the word debug I gave earlier and just put that into your word wherever you want the debugger to launch. If you haven't found it already, docs/neo6502-listing.txt can help determine where in the Tali source you are.

[SamCoVT]

Some other notes that may be useful for debugging from within Tali:
In the platform file, you can add "disassembler" to the optional words to allow disassembling words. It really should be there already, so that's my bad for not checking the other platform files when we made it optional.

TALI_OPTIONAL_WORDS := [ "ed", "editor", "ramdrive", "block", "environment?", "assembler", "disassembler", "wordlist" ]

Then you'll get a disassembly listing when you use see on a word. To make things easier to follow, you may want to turn off native compiling (where Tali copies the opcodes for a word directly into the word you are compiling). Disabling this will force all compiled words to be JSRs and that may make it easier to follow what's going on. You can disable the native compiling with: 0 nc-limit !

Here's an example session - your addresses may be different:

: testword  5 dup + . ;  ok
testword 10  ok
see testword 
nt: 800  xt: 80D  header: 01 08 08 C1 2A 
flags: HC 0 NN 0 AN 0 IM 0 CO 0 DC 0 LC 0 FP 1 | UF 0 ST 0 
size (decimal): 42 

080D  A9 05 CA CA 95 00 74 01  20 CB 80 CA CA B5 02 95  ......t.  .......
081D  00 B5 03 95 01 20 D0 80  18 B5 00 75 02 95 02 B5  ..... .. ...u....
082D  01 75 03 95 03 E8 E8 20  ED 85                    .u.....  ..

80D      5 lda.#
80F        dex
810        dex
811      0 sta.zx
813      1 stz.zx
815   80CB jsr     1 STACK DEPTH CHECK
818        dex
819        dex
81A      2 lda.zx
81C      0 sta.zx
81E      3 lda.zx
820      1 sta.zx
822   80D0 jsr     2 STACK DEPTH CHECK
825        clc
826      0 lda.zx
828      2 adc.zx
82A      2 sta.zx
82C      1 lda.zx
82E      3 adc.zx
830      3 sta.zx
832        inx
833        inx
834   85ED jsr     .
 ok
0 nc-limit !  ok
: testword2 5 dup + . ;  ok
see testword2 
nt: 838  xt: 845  header: 00 09 00 0E 
flags: HC 0 NN 0 AN 0 IM 0 CO 0 DC 0 LC 0 FP 0 | UF 0 ST 0 
size (decimal): 14 

0845  20 E8 89 05 00 20 5D 86  20 F4 8D 20 ED 85         .... ].  .. ..

845   89E8 jsr     LITERAL 5 
84A   865D jsr     dup
84D   8DF4 jsr     +
850   85ED jsr     .
 ok

If a JSR doesn't have the name of a Forth word after it, it's likely an internal routine and you should be able to find it in either the labelmap or listing file in the docs/ folder.

[SamCoVT]

Some notes about using the debugger built into the neo simulator:

• You CAN set a breakpoint at an arbitrary point (I was wrong on that point). Just type in the address without SHIFT or CTRL and then press F9. I must have misunderstood the instructions on that one, but looking at the code showed how it all works.
• Once a breakpoint is set, pressing F9 again on that address doesn't unset it.
  • Can use 0000 and then F9 to just move the breakpoint to an unused address
• There is only one breakpoint.
• When you type in numbers, such as to set the address, that input is also passed along to Tali Forth. Regular characters are passed along too, so you CAN press a key while debugging in the kernel's routine to read a character.

Regarding the strange value of X, I traced it out and the kernel doesn't touch X when just reading single characters. It's actually Tali using X, and it's because you are in the word ACCEPT while waiting for input. That word takes an address and length on the stack for where to put the input, and it returns the number of characters it accepted from the input. The value of X was two less than expected because it leaves room for the returned count on the data stack, even though it doesn't fill it in until the very end of the routine when ENTER is pressed or it has reached the end of the buffer it was given. Because that location on the data stack isn't updated until the end of ACCEPT, looking at the data on the stack isn't very useful to see what's going on. Using the debug word to execute opcode $03 doesn't have this offset because it's not in the word ACCEPT when the debugger is invoked.

[SamCoVT]

I got a USB hub compatible with the neo6502 (took a few tries to find one), so I can now load Tali from USB and use with USB keyboard on real neo6502 hardware.

[SamCoVT]

Hi @IanWitham ,
I just wanted to give you a heads-up that there are some changes in the master-64tass branch that might make your work a bit easier. The platform files have been modified to allow per-platform words written either in assembly or Forth. I don't know if you started any work based on a different branch, so I haven't messed with the other branches. If you are working off another branch, I'd be more than happy to rebase that branch to pick up the changes. Just let me know what you need.

If looking at the master-64tass branch, I'll recommend you look at the "skeleton" platform as that shows how to bring in additional words for the platform in both assembly and in Forth. Let me know if you get stuck on anything.