magazine logo
Welcome to the official Attitude website - Europe's #1 C64 scene disk magazine
How To Compile Krill's Loader?
by DJ Gruby/Arsenic/Excess/Protovision

If thinking about compiling Krill's loader gives you a headache, you have come to the right place. I would like to share my experience with you, so that a task you might have considered complicated until now will shortly become a piece of cake for you.

In general compiling the code is not rocket science. The biggest difficulty probably comes from a necessity to carefully follow enclosed documentation, something that eager engineers often tend to skip too quickly.

If you are an experienced user you might as well ask, why do I at all insist on documenting a trivial task like IRQ loader compilation, which theoretically should have been within the reach of any mediocre C64 programmer. Well, it turns out that things considered to be obvious by some parties are not that obvious for others.

Since multiple complaints about difficulties were reaching me for a while now, I eventually decided to take a closer look and list all of the requirements that need to be fulfilled before accomplishing a successful compilation of this state-of-the-art tool.

Although the entire process of building Krill's loader is pretty well-documented for anyone to successfully generate target binaries themselves, I agree it may sometime take a little guidance to get started. I have already been asked for this tutorial by a few individuals a couple of times. If you are one of those seeking advice on how to get this thing done quickly and seamlessly, this article has been prepared just for you. In the end you will be surprised how simple an entire process is, and you will be able to use this excellent IRQ loader in your own productions.

While having my IRQ loader usage tutorial (which you can read in this issue of Attitude) reviewed, Ruk/Booze Design pointed out that "compiling Krill's loader is probably the hardest part to get this example up and running". A couple of months earlier Kronos/Arsenic noted: "I also tried it in the past, but quickly gave up, because of all the issues you already mentioned. I'm sure that if you publish an article in Attitude, you will bring happiness to many people." Encouraged by all of these words, I decided to finally put this tutorial together and bring some happiness into the lives of numerous C64 sceners.

You can download Krill's loader as a source code package, which is very convenient way of distributing this kind of software because of a multitude of possible options that affect configuration of an output binary file. When determining which options suit your needs best, you may choose between a prominent variety of features, e.g. data transfer protocol, file system type, number of recognised devices, pre-installed decompression routines, and many more. The important point here is that you are not required to modify anyone of them, as in most cases you are going to be completely fine with the default values.

By customising any of the countless options you can build your own flavour of an IRQ loader that perfectly suits your needs. If you value speed over compatibility, selecting the fastest loading protocol is entirely up to you. If you need an IDE64 support, you just get it. If you need to load data into any place in a memory, you simply do it. All the flexibility you can imagine has been provided.

Before you can proceed with the compilation process of an IRQ loader itself, the first thing you need to install is CC65 compiler, a freeware C compiler for 6502 based systems. It is as simple as:

$ git clone https://github.com/cc65/cc65.git

$ cd cc65
$ make
$ sudo make install prefix=/usr/local


With all of the prerequisites installed on your system, let us move on straight to the build process of an IRQ loader system.

The build process is straight-forward and fully-automated. It requires very little setup, which we are going to begin with. If you unpacked the downloaded archive onto your disk, you should now change your current working directory to a place where all configuration files are collected together and use your favourite plain text editor to edit configuration file defining your customised IRQ loader version:

$ cd loader/include

$ vi config.inc


As mentioned before applying individual settings is entirely up to you, but in case adapting configuration files is a nightmare to you, let me share a few tips from my own experience.

Most of the options affect the size of the generated output file. So basically the more features you cram into it, the larger a resulting binary file will be. Reading Krill's comment at the top of the config.inc file provides the following hints for minimisation of a compiled file size:
  • Set all parameters in the increase code size section to 0.

  • Set PROTOCOL to PROTOCOLS::TWO_BITS_ATN.

  • Load files from disk based on their track/sector location rather than their file names (set FILESYSTEM to FILESYSTEMS::TRACK_SECTOR).

  • Do not decompress loaded files (set DECOMPRESSOR to DECOMPRESSORS::NONE).
This is however not necessarily what we might want to achieve. I usually select options which significantly increase a compiled file size, but give me some extra desired features instead. I will not cover all of the available parameters here. I want to focus only on those options, which I find relevant myself, but you are of course encouraged to explore them all and pick the ones that best fit your own needs. Here is my personalised list:
  • Set LOAD_UNDER_D000_DFFF to 1 to enable loading (and optional decompression) to the RAM at $D000-$DFFF. This is especially crucial for releases requiring an easy access to an entire RAM memory, e.g. disk magazines, games or demos. Attitude articles are in fact loaded to the RAM stretching around $D000-$DFFF and our loader configuration has obviously this option set to 1.

  • Set LOAD_VIA_KERNAL_FALLBACK to 1 to enable loading via the KERNAL API. This option combined with a file name based loading is essential for creating releases working properly not only on 15xx family of disk drives, but also on different types of storage hardware, i.e. IDE64.

  • Set FILESYSTEM to FILESYSTEMS::DIRECTORY_NAME to enable loading files by their directory names rather than track/sector location (this might be a bit slower for long directory listings, however it allows your code to properly run on IDE64).

  • Set FILENAME_MAXLENGTH to 2 to identify loaded files by their first two characters only. This allows you to use the remaining 14 characters of all disk file names to create a nice directory listing.

  • Set LOAD_COMPD_API to 0 to disable an option to load and depack compressed files on the fly. Set DECOMPRESSOR to DECOMPRESSORS::NONE for the same reason.
What is left now is building the actual binaries. Your IRQ loader code will be compiled at specific memory locations. You need to consider the following three memory addresses first before proceeding:
  • installation routine (temporary code which can be removed after initialization)

  • loading routine (persistent code that is called every time a new file is loaded from disk)

  • zero-page variables (several bytes required by a loading procedure)
Assuming that the addresses of $4000, $0400, and $10 respectively have been chosen (this is how we do it in Attitude), you only need to invoke the following command in your shell:

$ cd loader/src

$ make prg INSTALL=4000 RESIDENT=0400 ZP=10


Once your IRQ loader binaries have been successfully compiled, it is time to use them.

To provide you with a quick start guide let me just tell you how simple using the compiled loader version is. You only need to binary-include install.prg and loader.prg files in your program (look into loader/build directory to find them). If you want to use generated loader labels, e.g. jsr loadraw, simply source-include loadersymbols.inc file in your code. After this the only thing that remains is to call the loader routine from somewhere in your program:

;------------------------

          jsr install
;------------------------
          clc
          ldx #<filename
          ldy #>filename
          jsr loadraw
;------------------------
          [...]
;------------------------
filename  .dp "01"
          .db $00
;------------------------


Since this topic is covered in more details in a separate chapter found in this issue of Attitude, I will end this text at this point with a hope that you managed to compile Krill's loader yourself by now.

DJ GRUBY/ARSENIC/DREAM/EXCESS/PROTOVISION

   Add/view comments on this article (comments: 0)

SCENE GROUPS
 
OPINION POLL
Do you believe we are
able to cope with
releasing "Attitude"
on a regular basis?

yes no

 YES: 282 (70.68%)
NO:117 (29.32%) 

NEWS COMMENTS

ART COMMENTS

STATISTICS
all visits:

visits today:


website started:
23/09/2004
 
Official Webpage
of Attitude
Copyright 2004-2018
 
DJ Gruby/TRIAD