Human 68k: what changed

Revision 1 to 2. 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.
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	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	18
19	19		``` pascal
20	20		function h68kdos_write(fileno: word; buffer: pointer; len: longint): longint; syscall $ff40;
21	21		```
22	22
23	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	24
25	25		# Defaults
26	26
27	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	28
29	29		## CPU
30	30
31	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	32
33	33		## Alignment
34	34
35	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	36
37	37		## Stack
38	38
39	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	40
41	41		# External Dependencies
42	42
43	43		The Human 68k port depends on vasm and vlink, as external assembler and linker.
44	44
45	45		## Assembler
46	46
47	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	48
49	49		### Building vasm
50	50
51	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	52
53	53		``` bash
54	54		make CPU=m68k SYNTAX=std
55	55		```
56	56
57	57		The resulting vasmm68k_std executable file is the assembler Free Pascal needs.
58	58
59	59		## Linker
60	60
61	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	62
63	63		Please make sure you use vlink version 0.17a or newer. Earlier versions were never tested.
64	64
65	65		## Licensing
66	66
67	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	68
69	69		# Cross compiling
70	70
71	71		## Dependencies
72	72
73	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	74
75	75		## Building
76	76
77	77		To build a Human 68k cross-compiler, use the following steps:
78	78
79	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	80		2. Clone the FPC git repository.
81	81		3. Make sure you have vlink and vasm in the path
82	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	83
84	84		``` bash
85	85		make clean crossall crossinstall OS_TARGET=human68k CPU_TARGET=m68k INSTALL_PREFIX="<path/to/install>"
86	86		```
87	87
88	88		If you've done everything right, you should find a working Human 68k cross-compiler in the install path you've specified.
89	89
90	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	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`~~
	92	+	```text
	93	+	#IFDEF CPUM68K
	94	+	-Fu<path/to/install>/lib/fpc/$fpcversion/units/$FPCTARGET
	95	+	-Fu<path/to/install>/lib/fpc/$fpcversion/units/$FPCTARGET/*
	96	+	#IFDEF HUMAN68K
	97	+	-FD</path/to/human68k-binutils>
	98	+	-Cp68000
	99	+	#ENDIF
	100	+	#ENDIF
	101	+	```
100	102
101	103		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	104
103		-	~~`ppcross68k -Thuman68k <source.pas>`~~
	105	+	```text
	106	+	ppcross68k -Thuman68k <source.pas>
	107	+	```
104	108
105	109		# OS Bindings
106	110
107	111		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	112
109	113		# Other resources
110	114
111	115		- [GCC, binutils, and newlib port for Human 68k on GitHub by Lyderic "Lydux" Maillet](https://github.com/lydux)
112	116
113	117		---
114	118		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	119		Category: Operating Systems and Platforms

Back to history