Area 73

Writing a kernel from scratch is a big project, and it’s even more challenging when you are doing it in pure assembly language. It’s not that any one particular thing is necessarily hard, so much as it is verbose and repetitive. Fortunately it’s not necessary to keep repeating the same code over and over. Any decent assembler will support macros, and the one I am using (as65) has some pretty decent macro support. I’ve used this to create a number of macros that alleviate the most common pain points I have encountered. Let’s take a look at a couple of examples.

Walking a Linked List

Something I am doing quite a bit in my new code is walking linked lists. This is pretty basic data structures task; in C it’s just one line:

        ptr = ptr->next;

In 65816 assembly it looks like this:

        ldyw #OFFSET_OF_NEXT
        lda [ptr],y
        tax
        iny
        iny
        lda [ptr],y
        sta ptr + 2
        stx ptr

Again, it’s not that this is hard, but it’s something I end up doing a lot. Fortunately, with a little macro work, this can be made fairly trivial:

.macro next_entry loc
        lda     [loc]
        tax
        ldyw    #2
        lda     [loc],y
        sta     loc + 2
        stx     loc
.endmacro

This macro makes one assumption; that the pointer to the next entry is always in the first four bytes of the structure. I could make the macro take an optional offset, but all of my structures are designed this way, so I didn’t feel it was necessary.

With this macro, the eight lines above are now one line:

        next_entry ptr

Function Stack Frame Management

Now let’s look at something more in-depth, something that stretches the limits of what’s possible in macros.

On the 65816 it is often desirable to set up a local direct page on the stack, both to make it easy to access stack-based parameters and to support local variables. Setting this all up is fairly boilerplate, so I wrote macros for it. First, let’s look at the macros themselves, which are a bit more involved than the trivial example above:

.macro _BeginDirectPage
        .struct
        .res 1
.endmacro

.macro _StackFrameRTS
        s_dreg    .word
        s_ret     .word
.endmacro

.macro _StackFrameRTL
        s_dreg    .word
        s_ret     .word
        s_bank    .byte
.endmacro

.macro _EndDirectPage
        _pend  .byte
        .endstruct

@lsize := s_dreg - 1
.endmacro

.macro _SetupDirectPage
        phd
        tsc
.if @lsize > 0
        sec
        sbcw    #@lsize
        tcs
.endif
        tcd
.endmacro

.macro _RemoveParams pend
.ifblank pend
          @pend := _pend
.else
          @pend := pend
.endif
.ifdef s_bank
          @psize := @pend - s_bank - 1
.else
          @psize := @pend - s_ret - 2
.endif
.if @psize > 0
.ifdef s_bank
        shortm
        lda     s_bank,s
        sta     s_bank + @psize,s
        longm
.endif
        lda     s_ret,s
        sta     s_ret + @psize,s
        lda     s_dreg,s
        sta     s_dreg + @psize,s
.endif
        tsc
        clc
        adcw    #@psize + @lsize
        tcs
.endmacro

There’s a lot going on here, but it just involves trying to automatically figure out how many bytes of parameters and local variables need to be set up, and how many bytes of stack need removed before returning to the caller.

Starting at the top, the _BeginDirectPage, _EndDirectPage, and _StackFrameRTx macros are defining a STRUCT that generates some function-scoped direct page labels. A struct is an as65 construct that acts sort of like a structure in C, except it’s not allocating memory. Instead, it just defines scoped labels whose values are their offsets in the structure. By default they start at 0, but since our DP actually starts at SP + 1, _BeginDirectPage starts off by reserving an unnamed byte at 0.

Next, the _SetupDirectPage macro takes care of saving the DP, moving the stack pointer down for local variables (if needed), and setting D to point to the new direct page. At this point all parameters and local variables are accessible.

Finally, _RemoveParams cleans up the stack in preparation for returning to the caller. It takes one optional parameter, which is the name of the first output parameter. This is needed to calculate where input parameters end so that the proper number of bytes can be removed from the stack.

Here’s a snippet of my kmalloc() function, takes a single WORD (16-bit) length parameter, and returns a DWORD (32-bit) pointer. It also has two local variables, one WORD and one DWORD.

.proc kmalloc
        _BeginDirectPage
          l_best_size   .word
          l_ptr         .dword
          _StackFrameRTS
          i_size        .word
          o_block       .dword
        _EndDirectPage

        _SetupDirectPage
        ... do stuff ...
        _RemoveParams o_block
        pld
        rts

The resulting assembly code looks like this:

        phd
        tsc
        sec
        sbcw  #0006
        tcs
        tcd
        ... do stuff ...
        lda   09,s
        sta   0B,s
        lda   07,s
        sta   09,s
        tsc
        clc
        adcw  #0008
        tcs
        pld
        rts                             

The first part is the result of _SetupDirectPage. It just moves the SP down by six bytes to account for our two local variables, then sets D to SP. If there were no local variables defined the SEC/SBC/TCS lines would be omitted.

At the end is the result of _RemoveParams. It first moves the saved D and return address on the stack up by two bytes, erasing the input parameters. It then moves SP up by eight bytes: 6 for local variables and 2 for the input parameter. After that the code restores DP and returns to the caller.

While these macros are much easier than doing this manually they are not perfect, and still have room for errors:

• The D register is saved for you, but you must remember to restore it yourself. This was needed for a particular use case I won’t go into here.
• You have to make sure to use the right _StackFrameRTx macro depending on whether your function returns with RTS or RTL.
• The ordering of params is vital. Local variables must be listed first, followed by the stack frame, then input parameters, and finally output parameters.
• If you have output parameters, and fail to pass the name of the first one to _RemoveParams, then it will remove the wrong number of bytes from the stack and the function will crash on RTS/RTL.

These shortcomings are largely due to the limitations of ca65’s macro definitions I have been considering adding a preprocessor step to my build process, either a generic C preprocessor for better macro support, or a custom one that can generate boilerplate code based on some directives in the source file.

Why not C?

Ideally I would write some of my code in a higher-level language such as C, and reserve the pure assembly for time-critical functions such as interrupt handlers. Unfortunately, the C compiler that’s part of my tool chain, cc65, does not generate native 65816 code at this time, making it unusable. In fact,, there are only two C compilers for the 65816 that I’m aware of: the WDC Tools and Calypsi. Both are free for personal use, closed-source tools. Additionally, the WDC Tools are Win32 binaries, so they must be executed via WINE, which makes things messier and slower.

In general I avoid closed source tools as much as possible. It’s not because I’m opposed to them in general (I am), so much as that they tend to become unmaintained. Once that happens it rapidly becomes difficult or impossible to make them run properly on newer Linux distributions. Frequently all that is needed is to recompile the tools against newer libraries, something that’s impossible when the tool is closed source.

In the end, just getting my existing code to assemble under a new tool chain would be a major undertaking, one that I’ve decided is just not worth the effort. if I ever were to make a change, it would probably be to Calypsi, simply because it has native Linux binaries.

(By the way, I have experimented with WDC’s C compiler, and the function setup/exit code it generates it nearly identical to what my macros are generating. I have not tried this yet with Calypsi.)

Conclusions

I am still hopeful that someday somebody will finally create a good, fully open-source C compiler for the 65816. There have been rumblings about adding 65816 support to the llvm-mos project, though to date nothing has been released. If and when this happens it would provide a great ecosystem for 65816 development, and I would be tempted to port my code over at that point.

In the mean time, clever and judicious use of macros has made my work much easier.

I’m happy to report that the JRC-1 boards arrived a few days ago, and exactly as I predicted I had a build up and running by Christmas. Here it is, in all of its black solder mask glory:

I guess the third time’s a charm, because this is my third full build, and the board booted up with no hardware issues. It’s currently running at 4 MHz; it should run faster but I have not tried yet.

The board is not perfect; there are a couple minor problems with the layout. The footprints for the DS1813s (the reset and NMI controllers) are reversed, and the footprints for the expansion slots don’t fit the slot connectors I have. Neither problem is critical and both have easy workarounds, so at this point I am considering this design final. All of the the hardware design files (KiCad project and CPLD Verilog project), as well as the latest firmware code, are in the JRC-1 GitHub repository.

With the board up and running I am turning my attention to the firmware. Currently I’m working on cleaning up the code so that I can start the major work. Next up is getting the SD card driver working, and then work on JR/OS. That’s where the real fun begins!

When I first start planning the JRC-1, my main goal was to produce a simple base design with which I could experiment with more advanced features down the road. Something akin to the original IBM PC, except with a 65816. Meeting that goal meant I needed some sort of expansion bus.

The Design

Before I started any design work I ran my original plans by the folks at the 6502 forums. There are a lot of very smart people there who have experience with these things, and I trust their advice. The recommendation was that I not bring the system buses out of the slots. Instead, I should create an expansion bus behind a 6522 VIA.

After a few iterations I settled on a bus design. My bus looked very similar to the typical bus you might find on a RAM or ROM chip. It has six address lines, eight data lines, a R/W signal, a slot enable, and an I/O strobe. A pulse on the I/O strobe signals the card to perform a transaction. This design was chosen to interface to as many available peripheral chips as possible with minimal additional logic. It also fits on a single VIA, so I could test the design on COLE-1+.

The Experiment

At this point I need to mention that the deal-breaker application for any expansion bus is that I can create a video card for it. Sp. I adapted the TIVI code that I wrote for the TinyFPGA board to run on my ULX3S and hooked it up to COLE-1+. The results were….less than encouraging.

The whole setup was terribly unreliable. Sustained writes would frequently result in missed or duplicated bus transactions and thus garbled frame buffer data. Hooking up a scope did not reveal anything wrong at the signal level. The signals were very clean, and there was very little ringing or cross-talk. Manually slowing things down in code did not help at all, either.

I have spent many hours in the past week trying to fix this issue without success. My working theory is that the relatively high rise/fall times on the strobe line may be problematic. At 50 ns it might very well be causing metastability issues inside the FPGA. Given enough time I could probably make this work, but my frustration level has reached maximum.

Moving Forward

After a lot of thought I’ve come to realization that my expansion bus is turning into the kind of project-killing feature that doomed COLE-2. The irony here is that I was trying to avoid this exact issue by having expansion slots in the first place!

If I want JRC-1 to actually be finished and built, then I need to move past this. Instead of trying to come up with the perfect design on my first try, I’m just going to build what I really want, and if it is unstable, or fails outright, then I learn from that and design a better version.

And so I have decided to go with an ISA-style bus that provides access to buffered versions of the main board buses. This should work fine for at least a couple of MHz, and anecdotal evidence from folks using RC2014 and ISA backplanes suggests I may be able to hit 8 MHz without too much trouble. The only way to tell for sure is to build the dang thing and see what happens!