Human 68k: what changed

Revision 0 to 1. Removed lines have a minus sign; added lines have a plus sign.

Title: Human 68k

New		Line
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.
2	+
3	+	# Status
4	+
5	+	This port is currently a cross-compiler only target. This is mostly due to hardware limitations of the original unexpanded platform.
6	+
7	+	# Requirements
8	+
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	+
11	+	# Identification
12	+
13	+	To identify the Human 68k target compile-time, use {\$IFDEF HUMAN68K}.
14	+
15	+	# SysCalls
16	+
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	+
19	+	``` pascal
20	+	function h68kdos_write(fileno: word; buffer: pointer; len: longint): longint; syscall $ff40;
21	+	```
22	+
23	+	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	+
25	+	# Defaults
26	+
27	+	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	+	## CPU
30	+
31	+	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	+	## Alignment
34	+
35	+	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	+	## Stack
38	+
39	+	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	+	# External Dependencies
42	+
43	+	The Human 68k port depends on vasm and vlink, as external assembler and linker.
44	+
45	+	## Assembler
46	+
47	+	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	+
49	+	### Building vasm
50	+
51	+	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:
52	+
53	+	``` bash
54	+	make CPU=m68k SYNTAX=std
55	+	```
56	+
57	+	The resulting vasmm68k_std executable file is the assembler Free Pascal needs.
58	+
59	+	## Linker
60	+
61	+	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	+
63	+	Please make sure you use vlink version 0.17a or newer. Earlier versions were never tested.
64	+
65	+	## Licensing
66	+
67	+	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	+
69	+	# Cross compiling
70	+
71	+	## Dependencies
72	+
73	+	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	+
75	+	## Building
76	+
77	+	To build a Human 68k cross-compiler, use the following steps:
78	+
79	+	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.
80	+	2. Clone the FPC git repository.
81	+	3. Make sure you have vlink and vasm in the path
82	+	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	+
84	+	``` bash
85	+	make clean crossall crossinstall OS_TARGET=human68k CPU_TARGET=m68k INSTALL_PREFIX="<path/to/install>"
86	+	```
87	+
88	+	If you've done everything right, you should find a working Human 68k cross-compiler in the install path you've specified.
89	+
90	+	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:
91	+
92	+	`#IFDEF CPUM68K`\
93	+	`-Fu<path/to/install>/lib/fpc/$fpcversion/units/$FPCTARGET`\
94	+	`-Fu<path/to/install>/lib/fpc/$fpcversion/units/$FPCTARGET/*`\
95	+	`#IFDEF HUMAN68K`\
96	+	`-FD</path/to/human68k-binutils>`\
97	+	`-Cp68000`\
98	+	`#ENDIF`\
99	+	`#ENDIF`
100	+
101	+	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:
102	+
103	+	`ppcross68k -Thuman68k <source.pas>`
104	+
105	+	# OS Bindings
106	+
107	+	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.
108	+
109	+	# Other resources
110	+
111	+	- [GCC, binutils, and newlib port for Human 68k on GitHub by Lyderic "Lydux" Maillet](https://github.com/lydux)
112	+
113	+	---
114	+	From the Free Pascal wiki, page "Human 68k", as it stood on 2023-12-11 after a change by Chain-Q, out of the wiki's dump of 2024-05-26. 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).
115	+	Category: Operating Systems and Platforms

Back to history