The following information was kindly contributed by our forum member Lydux.

So I've decided to share with you some of my study and work. Here is small zip archive containing some part of my DDK and (unfinished) samples : http://nfggames.com/x68000/Development/libraries/human68k-ddk-0.1.zip

It does not contain everything I've written ! (My hard drive is a mess of source codes… :p ) Also, it's more linux friendly than Code::Blocks, but I remember having compiled the WINDRV sample on Code::Blocks. At least, files are correctly commented and you should find the necessary to build a simple driver. So, consider this as a reference actually. I'll try to create a repository on my github page soon.

Note : the following contains very hard stuff ! I might be confusing sometimes, sorry in advance. Don't hesitate to ask for help if you do not understand something. Thank you.

Terminology :

• Byte : 1 byte (8 bits)
• Word : 2 bytes (16 bits)
• Long : 4 bytes (32 bits)
• Char : 1 character = 1 byte
• All data types are CPU specific : M68K family. So, byte ordering is always “Big Endian” and a pointer is 32 bits (long).

Normally, any traditional executable requires some initializations step before reaching the “main” subroutine such as the process memory allocator, environment variables, command line processing, etc… This code object (crt0.o) is transparent for you, is provided by the libc (newlib) and automatically linked with the whole final objects by the toolchain linker specs. However, such initialization step is meaningless for driver ! Well… At least for .SYS drivers. You might have noticed that drivers may also be .X files ? In fact they contain both driver AND executable code.

So depending on your wish :

• if you're going for .X containing both executable and driver, no need to change anything.
• if you're going for just a .SYS driver, you need to add “-nostartfiles” to the linker flags. This will avoid the link against crt0.o and will reduce the final executable size. However, the linker will complain about a missing “_start” symbol. Look at samples in my DDK archive, you'll find a “crtstub.S” that'll add a dummy _start one.

When Human68k load drivers by CONFIG.SYS, the kernel hasn't totally finished initializing itself. Some libc functions will not be available. For example, COMMAND.X is not loaded yet, so you'll lack “setenv” and “getenv” functions. Also, you can consider a driver as a part of the kernel ; that means the overall RAM consummed by the kernel is not yet known ! The libc memory allocator can't be used, so no malloc available !

Because many of such functions can't be used with driver, I recommand not to use my toolchain libc by adding “-nostdlib” to the linker flags.

The zip archive contains some stripped down version of usefull libc's functions to help you instead. (look at the include folder).

That's all about startup and libc.

About libraries, you'll probably find interest in iocscalls and doscalls, they remain fully valid with drivers. You can safelly add “-liocs -ldos” to library link.

First, please note that Human68k drivers really look like to MS-DOS ones. So chances are MS-DOS drivers documentations are also valid to Human68K !

When kernel try to load a driver, the very first thing it must encounter is an header containing informations on how to load it and which kind of driver it is. The very first driver header must be located right after the XFile header which is 0x40 bytes length. Here is this header structure :

• next header (long) : A single .SYS or .X file may contains more than one drivers, so this a pointer to the next driver header within this file. Set this member to -1 (0xFFFFFFFF) if this driver entry is the last one in the chain.
• attributes (word): This 16 bits (1 word) member are flags that give informations about the driver behavior. Valid flags are :
  • 0x8000 : Character device driver (any driver that'll NOT talk to storage device, generally a disk containing a FAT filesystem). Unset this for a block device driver.
  • 0x4000 : IOCTL capable device. IOCTL are device specific commands that the kernel do not understand, and do not care anyway. These commands are available to userspace for a dedicated application, the kernel act as a bridge between the driver and user application. A good example of a IOCTL command is a media ejection, available for us on floppy drives or CDROM, but not on hard drive. Thinks about an application like “eject a:”.
  • 0x2000 : Remote device driver. This flag is an unique Human68k feature. When communicating to a driver having this flag setted, the kernel will deploy alternate functions that work at an higher level than block devices : filesystems. This allow the developper to use alternate way to access file on a device that the kernel do not normally understand. Think about eventual FAT32, or drive mapping over RS232/TCP. Emulators WINDRV use this flag.
  • 0x0040 : Special IOCTL. (?)
  • 0x0020 : Raw mode. (?)
  • 0x0008 : Clock device. Use internally by the kernel to specify that the driver talk to an RTC or timer device.
  • 0x0004 : NUL device. Use internally by the kernel. A dummy driver.
  • 0x0002 : STDOUT device. The driver will redefine the stdout, for example : screen, serial output, printers,…
  • 0x0001 : STDIN device. The driver will redefine the stdin : keyboard or serial input.
• strategy routine (long): A pointer to the very first routine the kernel will execute ! This will initiate the driver loading.
• interrupt routine (long): A pointer to a routine that will perform the communication between the kernel and the device.
• driver name (8 chars): An unique identifier, also used by userspace application when executing IOCTL commands.

These 2 routines are the only ones used by the kernel to communicate with the driver.

Upon header validation, the kernel will allocate a few bytes in its own memory that'll be used later as a communication interface. This small memory block is fixed in size, will never move, and will remain forever during the OS lifetime. We call it the “Request Packet”. Once allocated, it's absolute location is set into cpu register A5 and will imediatly jump to the “Strategy routine”. On Human68k, the only purpose of this routine is to store the value contained in the register A5 somewhere in the driver uninitialized data space (the complex and long word to say a “variable” in C. :P Or BSS segment in binary terminology.) and return. Then, the strategy routine can totally be forgotten, it will never be reused.

Next is the “Interrupt routine”, and is the most important one. All kernel request to driver will be passed by modifying the request packet, and then execute the interrupt routine.

This routine is responsible of analyzing the request packet, and proceed the request.

The small allocated kernel memory area will change on every kernel request. Only the first 13 bytes is a fixed structure describing the request itself, and the remaining are the request parameters. Note that the some Request Packet structure members are filled by the kernel (input), others are by the drivers as the result of the request (output). Request packet structure header (fixed first 13 bytes) :

• Request length (byte, input) : This request packet length, while the full allocated request packet is fixed once and for all, the amount of parameters and their size change depending on the requested command code.
• Requested unit (byte, input) : The unit number this packet target. An unique loaded driver might handle more than one device. Ex : the FDD driver handle 2 or 4 floppy drives.
• Request command code (byte, input) : The kernel request command code that the interrupt routine MUST analyze and dispatch/proceed. See “Generic command codes and parameters” and “Extend command codes” bellow.
• Result status (word, output) : These are combination of return flags notifying the success or failure of the request. On failure, this manifest by the famous centered white box with a message, and the user is invited to type “A”bort, “R”etry or “I”gnore. A driver must always fill this member on every command execution ! See “Command execution result flags” bellow for a list of acceptable flags.
• Reserved (8 bytes) : Reserved area, don't touch it !

Command execution result flags :

This list contains all acceptable values to fill the result status flags in the request packet header. S_ flags will display (or hide) the “A”bort, “R”etry and “I”gnore line, and E_ will show an appropriate error message. “Result status” member can be any combination of S_ flags (ORed together), but only one E_ can be set.

• 0x1000 - S_ABORT : “A”bort the whole request.
• 0x2000 - S_RETRY : Allow to “R”etry the request.
• 0x4000 - S_IGNORE : The failed request can be safelly “I”gnored.
• 0x0000 - E_OK : No error
• 0x0001 - E_UNIT : The unit is unknown
• 0x0002 - E_NOTRDY : Unit isn't ready
• 0x0003 - E_CMD : Unknow command code
• 0x0004 - E_CRC : CRC error
• 0x0005 - E_LENGTH : Bad length
• 0x0006 - E_SEEK : Seek Error
• 0x0007 - E_MEDIA : Unknown Media
• 0x0008 - E_NOTFND : Sector Not Found
• 0x0009 - E_PAPER : No Paper
• 0x000A - E_WRITE : Write Fault
• 0x000B - E_READ : Read Fault
• 0x000C - E_FAILURE : General Failure
• 0x000D - E_WRPRT : Write Protect
• 0x000E - E_DISK : Disk Change