Human 68k: what changed
Revision 2 to 3. Removed lines have a minus sign; added lines have a plus sign.
| Old | New | Line | |
|---|---|---|---|
| 1 | - | ||
| 1 | + | The Human 68k port is an experimental [[m68k]] target, mainly aimed at retro computer enthusiasts. It targets the Sharp X68000 line of computers, that existed from the mid-80s to the mid-90s as a Japanese-only home computer and gaming console, and their operating system, the MS-DOS-alike Human 68k by Hudson Soft. The initial version of the Human 68k port was implemented by [Karoly Balogh](</User:Chain-Q> "User:Chain-Q"). | |
| 2 | 2 | ||
| 3 | 3 | # Status | |
| 4 | 4 | ||
| 5 | - | ||
| 5 | + | This port is currently a cross-compiler only target. This is mostly due to hardware limitations of the original unexpanded platform. | |
| 6 | 6 | ||
| 7 | 7 | # Requirements | |
| 8 | 8 | ||
| 9 | - | ||
| 9 | + | The compiled binaries - depending on the size - should be able to run on any Sharp X68000. Memory expansion for more complex programs is highly recommended. | |
| 10 | 10 | ||
| 11 | 11 | # Identification | |
| 12 | 12 | ||
| 13 | - | ||
| 13 | + | To identify the Human 68k target compile-time, use **{$IFDEF HUMAN68K}**. | |
| 14 | 14 | ||
| 15 | 15 | # SysCalls | |
| 16 | 16 | ||
| 17 | - | ||
| 18 | - | ||
| 19 | - | ||
| 17 | + | Free Pascal supports generating Human 68k style system calls. Inline assembly code is not needed to call a system function. The syntax to declare Human 68k-style system calls is the following: | |
| 18 | + | ``` | |
| 20 | 19 | function h68kdos_write(fileno: word; buffer: pointer; len: longint): longint; syscall $ff40; | |
| 21 | 20 | ``` | |
| 22 | 21 | ||
| 23 | - | ||
| 22 | + | Note the syscall modifier in the function declaration. The argument to the syscall modifier is the DOS function number to call. All syscall parameters are passed on the stack in right-to-left order, and they're word (2 byte) aligned. For further examples, see _rtl/human68k/h68kdos.inc_ in the RTL source. | |
| 24 | 23 | ||
| 24 | + | ||
| 25 | + | ||
| 25 | 26 | # Defaults | |
| 26 | 27 | ||
| 27 | - | ||
| 28 | + | This section documents several compiler default settings, which are specific to the Human 68k target. Settings not documented here are usually the default for the m68k CPU architecture. | |
| 28 | 29 | ||
| 29 | 30 | ## CPU | |
| 30 | 31 | ||
| 31 | - | ||
| 32 | + | The default CPU target for the Human 68k target is the 68000. This is different from most other [[m68k]] targets where the default is the 68020. SoftFPU is enabled by default. | |
| 32 | 33 | ||
| 33 | 34 | ## Alignment | |
| 34 | 35 | ||
| 35 | - | ||
| 36 | + | Record elements are aligned to WORD (2 bytes) by default. Use the **{$PACKRECORDS n}** compiler directive, if you want to change the default aligment. For byte aligned records, a packed record is also possible. Free Pascal also has support for the 68000 [[m68k|special alignment requirements]]. | |
| 36 | 37 | ||
| 37 | 38 | ## Stack | |
| 38 | 39 | ||
| 39 | - | ||
| 40 | + | The default stack size is set to 16 KiB, which is quite small for a complex Pascal program. For more complex programs you'll probably need to increase it. To change the stack size, use the **{SMEMORY <stacksize>,<heapsize>}** directive, or the **-Cs** command line argument. See the details in the documentation. | |
| 40 | 41 | ||
| 42 | + | ||
| 43 | + | ||
| 41 | 44 | # External Dependencies | |
| 42 | 45 | ||
| 43 | - | ||
| 46 | + | The Human 68k port depends on **vasm** and **vlink** , as external assembler and linker. | |
| 44 | 47 | ||
| 45 | 48 | ## Assembler | |
| 46 | 49 | ||
| 47 | - | ||
| 50 | + | The only supported assembler for the Human 68k port is **vasm** , which is also the default. The Human 68k port uses **ELF** as the default object format. This means using **vasm** also requires **vlink** as linker. **vasm** is open source, and it is available [here](<http://sun.hasenbraten.de/vasm>). Only **vasm** versions 1.9f and newer were tested with the Human 68k port, older versions might not work. | |
| 48 | 51 | ||
| 49 | 52 | ### Building vasm | |
| 50 | 53 | ||
| 51 | - | ||
| 52 | - | ||
| 53 | - | ||
| 54 | - | ||
| 54 | + | Note that **vasm** for [[m68k]] needs to be built with the _standard_ syntax module to work with Free Pascal. This is not the default, as most programmers and compilers prefer the _Motorola_ syntax module. A **vasm** version with the _standard_ syntax module can be built with the following command, issued in the root of the **vasm** source tree: | |
| 55 | 55 | ``` | |
| 56 | + | make CPU=m68k SYNTAX=std | |
| 57 | + | ``` | |
| 56 | 58 | ||
| 57 | - | ||
| 59 | + | The resulting _vasmm68k_std_ executable file is the assembler Free Pascal needs. | |
| 58 | 60 | ||
| 59 | 61 | ## Linker | |
| 60 | 62 | ||
| 61 | - | ||
| 63 | + | The Human 68k port defaults to **vlink** by Frank Wille as the default linker, which is the only supported linker for this target. **vlink** is open source, and it is available [here](<http://sun.hasenbraten.de/vlink>). | |
| 62 | 64 | ||
| 63 | - | ||
| 65 | + | Please make sure you use **vlink** version 0.17a or newer. Earlier versions were never tested. | |
| 64 | 66 | ||
| 65 | 67 | ## Licensing | |
| 66 | 68 | ||
| 67 | - | ||
| 69 | + | Please note that the license of **vasm** and **vlink** does not allow development of commercial applications. If you plan to develop and sell a commercial application using these tools, you need their author's written consent. Please see the documentation of [vasm](<http://sun.hasenbraten.de/vasm/release/vasm.html>) and [vlink](<http://sun.hasenbraten.de/vlink/release/vlink.pdf>) for details. | |
| 68 | 70 | ||
| 71 | + | ||
| 72 | + | ||
| 69 | 73 | # Cross compiling | |
| 70 | 74 | ||
| 71 | 75 | ## Dependencies | |
| 72 | 76 | ||
| 73 | - | ||
| 77 | + | Free Pascal needs **vlink** and **vasm** for the Human 68k target. Using GNU binutils is not supported for now. To get vlink and vasm built, see the relevant sections above. | |
| 74 | 78 | ||
| 75 | 79 | ## Building | |
| 76 | 80 | ||
| 77 | - | ||
| 81 | + | To build a Human 68k cross-compiler, use the following steps: | |
| 78 | 82 | ||
| 79 | - | ||
| 80 | - | ||
| 81 | - | ||
| 82 | - | ||
| 83 | + | 1. Install the latest stable FPC version, at the time of the writing of this article this is FPC 3.2.2. This will be used as the startup compiler. | |
| 84 | + | 2. Clone the FPC git repository. | |
| 85 | + | 3. Make sure you have vlink and vasm in the path | |
| 86 | + | 4. Go to the repository's directory, make sure you are on the **main** branch and use the following command to build an FPC cross-compiler: | |
| 83 | 87 | ||
| 84 | - | ||
| 85 | - | ||
| 86 | 88 | ``` | |
| 87 | - | ||
| 88 | - | ||
| 89 | + | make clean crossall crossinstall OS_TARGET=human68k CPU_TARGET=m68k INSTALL_PREFIX="<path/to/install>" | |
| 90 | + | ``` | |
| 89 | 91 | ||
| 90 | - | ||
| 92 | + | If you've done everything right, you should find a working Human 68k cross-compiler in the install path you've specified. | |
| 91 | 93 | ||
| 92 | - | ||
| 94 | + | Now, lets create a default fpc.cfg for Human 68k cross compiling. Create a file called **< path/to/install>/lib/fpc/etc/fpc.cfg**. Put the following lines into that file, and fix up the paths: | |
| 95 | + | ``` | |
| 93 | 96 | #IFDEF CPUM68K | |
| 94 | - | ||
| 95 | - | ||
| 96 | - | ||
| 97 | - | ||
| 98 | - | ||
| 99 | - | ||
| 100 | - | ||
| 97 | + | -Fu<path/to/install>/lib/fpc/$fpcversion/units/$FPCTARGET | |
| 98 | + | -Fu<path/to/install>/lib/fpc/$fpcversion/units/$FPCTARGET/* | |
| 99 | + | #IFDEF HUMAN68K | |
| 100 | + | -FD</path/to/human68k-binutils> | |
| 101 | + | -Cp68000 | |
| 102 | + | #ENDIF | |
| 103 | + | #ENDIF | |
| 101 | 104 | ``` | |
| 102 | 105 | ||
| 103 | - | ||
| 104 | - | ||
| 105 | - | ||
| 106 | + | Optionally add **< path/to/install>/lib/fpc/3.3.1/** directory to the PATH, so you'll have direct access to the cross-compiler. If you've done everything right, you now should be able to build Human 68k executables: | |
| 107 | + | ``` | |
| 106 | 108 | ppcross68k -Thuman68k <source.pas> | |
| 107 | 109 | ``` | |
| 108 | 110 | ||
| 111 | + | ||
| 112 | + | ||
| 109 | 113 | # OS Bindings | |
| 110 | 114 | ||
| 111 | - | ||
| 115 | + | There's a **h68units** package, that contains support code for calling OS functions and addressing the X68000 hardware directly. Currently this is mostly limited to DOS functions. The package is named **h68units** , and not **h68kunits** to support the 8+3 filename limitations of the target platform. This allows a future native compiler run, even if this is not possible at the moment. | |
| 112 | 116 | ||
| 113 | 117 | # Other resources | |
| 114 | 118 | ||
| 115 | - | ||
| 119 | + | * [GCC, binutils, and newlib port for Human 68k on GitHub by Lyderic "Lydux" Maillet](<https://github.com/lydux>) | |
| 120 | + | * [X68000 C programming tutorials on GitHub by Federico Roviralta](<https://github.com/FedericoTech/X68KTutorials>) | |
| 116 | 121 | ||
| 117 | 122 | --- | |
| 118 | - | ||
| 119 | - | ||
| 123 | + | *From the Free Pascal wiki, page "Human 68k", as the Internet Archive kept it on 2026-01-16, last changed on 2024-07-29. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).* |