Initial commit
[minimigmac.git] / README
1 Minimigmac v0.1
2 ---------------
3
4 Copyright 2011 Ben Herrenschmidt <benh@kernel.crashing.org>
5
6 Licenced under the GPL, see COPYING file.
7
8 ! Warning !
9
10 A bunch of stuff aren't quite working yet, the whole thing actually
11 has some stability issues when "hot", see the TODO file and help
12 is welcome :-)
13
14 This currently requires a 4M minimig to emulate a 2M MacPlus. I
15 will probably try to make it work on a 2M minimig at some point.
16
17 Build/Install instructions
18 --------------------------
19
20 * Build the FPGA using Xilinx tools, project file not included,
21   and put the result in a file named "MIMIGMAC.BIN" on the sd-card.
22
23   The toplevel module is "minimigmac" in minimigmac. The sim_*
24   modules and the Makefile are for simulation with iverilog.
25   This requires m68k_vpi.vpi amd m68k.v (my VERY CRUDE) VPI
26   module containing Hampa Hug's 68k emulator. It can be found
27   at http://ozlabs.org/~benh/m68k-vpi-0.1.tar.bz2
28
29   Or use my prebuilt binaries
30
31 * Build the PIC code using sdcc (I use piklab as a front-end) and
32   download that to the PIC
33
34   Or use my prebuild binaries
35
36 * Get your (legitimate) copy of the MacPlus ROM onto the sd-card
37   in a file named "MIMIGMAC.ROM"
38
39 * Make a 20M (I used 21M just in case, see below) file to use as a
40   SCSI disk image on the sd-card, name it "MACHD.IMG"
41
42 Hard disk image notes:
43 ----------------------
44
45 Since we don't emulate floppies yet, you need to have a pre-installed
46 hard disk image.
47
48 This is not a raw filesystem image as used by most Mac emulators out
49 there, but instead needs to be a raw image of a Mac formatted SCSI
50 disk, more specifically a Seagate ST 225N :-) I've built such an image
51 using the "pce" emulator from Hampa Hug, I'll put some instructions
52 below. Eventually, when floppy emulation is implemented, things will
53 be easier to install.
54
55 The reason for that is that the Macintosh ROM doesn't contain a proper
56 SCSI disk driver. Instead, it uses the low level SCSI Manager routines
57 in "polled" mode at boot to load such a driver from the disk itself.
58
59 Since I don't have at this point a free driver I can make visible there
60 (by simulating the partition map etc...) we need to make things look
61 good enough for Apple's own driver to work. Unfortunately, Apple's
62 SCSI formatting/partitioning tool only works with "known" disks (well
63 there are versions that work with any disk but not the one I've used
64 so far).
65
66 Note also that SCSI emulation is incomplete. It works with the driver
67 coming with System 4.2 Finder 5.5, which doesn't do anything but
68 READ6/WRITE6 (not even a GET_CAPACITY or INQUIRY) but you may have
69 problems with other variants. I will fix that eventually.
70
71 So to create the disk image, first I've downloaded & built PCE which
72 you can find at http://www.hampa.ch/
73
74 I've then modified the default MacPlus config file so that its scsi
75 device section looks like:
76
77         device {
78                 # The SCSI ID
79                 id = 6
80
81                 # The drive number. This number is used to identify
82                 # a "disk" section. The number itself is meaningless.
83                 drive = 128
84
85                 # The vendor and product strings are returned by
86                 # the SCSI Inquiry command.
87                 vendor = " SEAGATE"
88                 product = "          ST225N"
89         }
90
91 (This is the same vendor/product strings that our PIC code passes
92 to the Macintosh upon INQUIRY commands).
93
94 I've created a 21MB disk image (in case the disk is a bit more than
95 20MB though it's probably a bit less, ie, the Apple tool afaik uses
96 a hard wired size from a table)
97
98 I've then used System 4.2 floppy images to install a MacOS onto
99 that disk image & copied it to my sd-card.
100