From 5eaab32798eb2d10b4d7c93bc85e8690f8a7d64c Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Sat, 13 Dec 2025 00:19:10 +0000 Subject: [PATCH] Generate comprehensive documentation site for GitHub Pages - Created top-level `ARCHITECTURE.md`. - Replaced `README.txt` with `README.md` linking to docs. - Created `docs/` structure with guides for Architecture, Modules, Setup, and Development. - Added Mermaid diagrams for system overview and data flows. - Added Jekyll config for GitHub Pages. --- ARCHITECTURE.md | 62 ++++++++++++++++++++++ README.md | 23 ++++++++ README.txt | 5 -- docs/_config.yml | 4 ++ docs/architecture.md | 106 +++++++++++++++++++++++++++++++++++++ docs/configuration.md | 44 +++++++++++++++ docs/data-models.md | 83 +++++++++++++++++++++++++++++ docs/deployment.md | 49 +++++++++++++++++ docs/development-guide.md | 48 +++++++++++++++++ docs/getting-started.md | 86 ++++++++++++++++++++++++++++++ docs/index.md | 35 ++++++++++++ docs/modules/drivers.md | 37 +++++++++++++ docs/modules/index.md | 8 +++ docs/modules/interfaces.md | 26 +++++++++ docs/modules/internal.md | 30 +++++++++++ docs/modules/os.md | 47 ++++++++++++++++ docs/troubleshooting.md | 42 +++++++++++++++ 17 files changed, 730 insertions(+), 5 deletions(-) create mode 100644 ARCHITECTURE.md create mode 100644 README.md delete mode 100644 README.txt create mode 100644 docs/_config.yml create mode 100644 docs/architecture.md create mode 100644 docs/configuration.md create mode 100644 docs/data-models.md create mode 100644 docs/deployment.md create mode 100644 docs/development-guide.md create mode 100644 docs/getting-started.md create mode 100644 docs/index.md create mode 100644 docs/modules/drivers.md create mode 100644 docs/modules/index.md create mode 100644 docs/modules/interfaces.md create mode 100644 docs/modules/internal.md create mode 100644 docs/modules/os.md create mode 100644 docs/troubleshooting.md diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md new file mode 100644 index 0000000..ddaf67a --- /dev/null +++ b/ARCHITECTURE.md @@ -0,0 +1,62 @@ +# System Architecture + +## Overview + +This repository contains the source code for a reconstruction of Macintosh System Software 7.1. It is designed to be cross-compiled on Linux targeting the Motorola 680x0 (m68k) architecture. The system follows the classic Macintosh "Toolbox" architecture, where the Operating System serves as a foundation for a rich set of user interface and system service APIs. + +## High-Level Diagram + +```mermaid +graph TD + User[User] --> Finder[Finder / MiniFinder] + Finder --> Toolbox[Macintosh Toolbox] + Toolbox --> OS[Operating System Core] + OS --> Drivers[Device Drivers] + Drivers --> Hardware[Macintosh Hardware (m68k)] +``` + +## Core Components + +### 1. Operating System (OS) +The kernel of the system, located in the `OS/` directory. It manages hardware resources and provides fundamental services: +- **Memory Manager:** Manages the application heap and system memory. +- **Process Manager:** Implements cooperative multitasking. +- **File System (HFS):** Hierarchical File System support. +- **Trap Dispatcher:** The mechanism that routes Toolbox calls to their implementations. + +### 2. Toolbox +A collection of high-level APIs located across `OS/`, `Interfaces/`, and `Libs/`. It provides the building blocks for Macintosh applications: +- **Window Manager:** Manages on-screen windows. +- **Menu Manager:** Handles drop-down menus. +- **QuickDraw:** The graphics primitive library. +- **Event Manager:** Handles user input (mouse, keyboard). + +### 3. Drivers +Located in `Drivers/`, these modules handle low-level hardware interaction: +- **Sony:** Floppy disk driver. +- **Video:** Display drivers. +- **IOP/ADB:** Input/Output Processors and Apple Desktop Bus for peripherals. + +### 4. Build System +The project uses a cross-compilation strategy: +- **Host:** Linux. +- **Toolchain:** MPW (Macintosh Programmer's Workshop) running under `empw` emulation. +- **Configuration:** `.make` files in the `Make/` directory define dependencies and build rules. + +## Data Flow +The system operates primarily on an event-driven model: +1. **Hardware Interrupts:** Input devices trigger interrupts. +2. **OS Event Queue:** The OS places these events into a queue. +3. **Event Loop:** The active application (e.g., Finder) polls `WaitNextEvent`. +4. **Dispatch:** The application processes the event and calls Toolbox functions to update the display or state. + +## Key Directories + +| Directory | Description | +|-----------|-------------| +| `OS/` | Core system components (Memory, Process, HFS). | +| `Drivers/` | Hardware drivers. | +| `Interfaces/` | Public SDK headers (C, Pascal, Assembly). | +| `Internal/` | Private headers and stub implementations. | +| `Make/` | Build configuration files. | +| `Libs/` | Static libraries linked into the final system. | diff --git a/README.md b/README.md new file mode 100644 index 0000000..882dfff --- /dev/null +++ b/README.md @@ -0,0 +1,23 @@ +# Apple Mac OS 7.1 Source Code + +This repository contains the source code of Macintosh System Software 7.1 (m68k architecture). It is a reconstruction aimed at enabling cross-compilation on modern Linux systems. + +**Disclaimer:** This code is for research and educational purposes only. + +## Documentation + +Full documentation for this project is available in the `docs/` directory and can be browsed online (once GitHub Pages is enabled). + +* [**Home**](docs/index.md) +* [**Getting Started**](docs/getting-started.md) +* [**Architecture**](docs/architecture.md) +* [**Development Guide**](docs/development-guide.md) + +## Quick Start + +1. **Clone** this repository. +2. **Install Prerequisites:** `empw`, `hfsutils`, `build-essential`. +3. **Setup:** Run `./cross_compile.sh` to prepare the environment. +4. **Build:** Run `./build_system7.sh` to compile the system. + +See [Getting Started](docs/getting-started.md) for detailed instructions. diff --git a/README.txt b/README.txt deleted file mode 100644 index 3d6ad0f..0000000 --- a/README.txt +++ /dev/null @@ -1,5 +0,0 @@ -Apple Mac OS 7.1 Source Code - -Leaked source code of Macintosh System Software 7.1 (m68k + some PPC architecture). Dates back to early 2010's. - -I do not own this source code, it is published only for research purposes. diff --git a/docs/_config.yml b/docs/_config.yml new file mode 100644 index 0000000..f4b2c6f --- /dev/null +++ b/docs/_config.yml @@ -0,0 +1,4 @@ +# Simple Jekyll configuration +theme: jekyll-theme-minimal +title: Mac OS 7.1 Source Docs +description: Documentation for the Mac OS 7.1 Source Code Reconstruction diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..7256f22 --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,106 @@ +# System Architecture + +This document provides a detailed overview of the Macintosh System 7.1 architecture as implemented in this repository. + +## Architectural Style + +The system follows a **Monolithic Kernel** design combined with a **Toolbox** API layer. +- **Monolithic:** The core OS services (Memory, Process, File System) run in a single address space (privileged mode on 680x0). +- **Toolbox:** A rich library of high-level services (Windows, Menus, Controls) that applications link against or call via the Trap Dispatcher. +- **Cooperative Multitasking:** The Process Manager switches tasks only when an application explicitly yields control (e.g., calling `WaitNextEvent`). + +## Component Diagram + +```mermaid +graph TB + subgraph User Space + App[Application] + Finder[Finder / MiniFinder] + end + + subgraph Toolbox Layer + WM[Window Manager] + MM[Menu Manager] + QD[QuickDraw] + Dlg[Dialog Manager] + end + + subgraph OS Layer + Trap[Trap Dispatcher] + PM[Process Manager] + Mem[Memory Manager] + HFS[File System (HFS)] + Res[Resource Manager] + end + + subgraph Hardware Abstraction + Drivers[Device Drivers] + ADB[ADB Manager] + SCSI[SCSI Manager] + end + + subgraph Hardware + CPU[m68k CPU] + RAM[Memory] + Disk[Disk Drive] + Video[Video Card] + end + + App --> WM + App --> MM + App --> QD + Finder --> WM + + WM --> Trap + MM --> Trap + + Trap --> PM + Trap --> Mem + Trap --> Res + + Res --> HFS + HFS --> SCSI + SCSI --> Drivers + Drivers --> Hardware +``` + +## Key Data Flows + +### Application Launch +1. **User Action:** User double-clicks an icon in the Finder. +2. **Finder:** Calls `LaunchApplication`. +3. **Process Manager:** + * Allocates a partition in memory for the new application. + * Loads the code segments (CODE resources) from the executable file. + * Sets up the A5 world (globals and jump table). + * Transfers control to the application's entry point. + +### Event Processing +1. **Hardware:** Mouse move or Key press triggers an interrupt. +2. **ISR:** Interrupt Service Routine stores raw event data. +3. **OS Event Manager:** Converts raw data into an `EventRecord` and places it in the System Event Queue. +4. **Application:** Calls `WaitNextEvent`. +5. **OS:** Moves the event from the System Queue to the Application's Event Queue and returns it to the app. +6. **Application:** Dispatches the event to the appropriate handler (e.g., `HandleClick`). + +## Module Interaction + +* **Trap Dispatcher:** The central hub. All Toolbox calls (A-Traps) go through the dispatch table to find the implementation address in ROM or RAM. +* **Memory Manager:** Fundamental dependency. Almost every other module (Drivers, Toolbox, Process Mgr) needs to allocate memory blocks (pointers or handles). +* **Resource Manager:** The primary data loading mechanism. Code, dialogs, strings, and fonts are all loaded as resources. + +## Build Architecture + +The build system transforms source code into a "System" file (technically a suitcase of resources). + +```mermaid +graph LR + Src[Source Code (.c, .p, .a)] --> Compiler[MPW Compilers] + Compiler --> Obj[Object Files (.o)] + Obj --> Linker[MPW Linker] + Linker --> CodeRes[CODE Resources] + ResSrc[Resource Definitions (.r)] --> Rez[Rez Compiler] + Rez --> Rsrc[Resource Files (.rsrc)] + CodeRes --> System[System File] + Rsrc --> System +``` diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..c9182ee --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,44 @@ +# Configuration + +This document explains the build configuration system for the repository. + +## Build System Overview +The build is driven by MPW `Make` tools. Configuration is primarily defined in `.make` files located in the `Make/` directory. + +## Key Configuration Files + +### `Make/MainCode.Make` / `Make/Universal.make` +The master makefile. +* **Defines:** Source directories, include paths, build options. +* **Rules:** How to compile C, Pascal, and Assembly files. +* **Link List:** The list of object files to link into the final system image. + +### `Make/Build.txt` +Likely defines build versioning or specific build targets. + +## Environment Variables + +The `cross_compile.sh` and `build_system7.sh` scripts set up the following environment variables for `empw`: + +| Variable | Description | +|----------|-------------| +| `MPW` | Root of the MPW tools directory. | +| `KS_MPW` | Alias for `MPW` (used by `empw`). | +| `BuildResults` | Output directory for artifacts (`Build/`). | +| `ObjDir` | Directory for intermediate object files. | +| `AIncludes` | Path to public Assembly includes. | +| `CIncludes` | Path to public C includes. | +| `IntAIncludes` | Path to internal Assembly includes. | + +## Feature Flags and Defines +Conditional compilation is handled via compiler flags passed in the Makefile (e.g., `-d DEBUG`). + +* **debug:** Enables debug symbols and assertions. +* **uni:** Likely refers to "Universal" build (supporting multiple machines). + +## Patching +The `patch_makefile.sh` script dynamically modifies `Make/MainCode.Make` to inject dependencies. +* **Mechanism:** Appends lines to the end of the file. +* **Purpose:** To add `MiniFinder.c.o`, `VirtualMemoryStub.c.o`, etc., without manually editing the complex makefile. + +To change the configuration manually, you can edit `Make/MainCode.Make` (carefully, preserving line endings and encoding) or modify the `patch_makefile.sh` script. diff --git a/docs/data-models.md b/docs/data-models.md new file mode 100644 index 0000000..22464b2 --- /dev/null +++ b/docs/data-models.md @@ -0,0 +1,83 @@ +# Data Models + +This document outlines key data structures and memory models used in System 7.1. + +## Memory Models + +### The Heap +Memory is divided into heaps. +* **System Heap:** Persistent memory for OS and Drivers. +* **Application Heap:** Volatile memory for the currently running application. + +**Data Types:** +* **Ptr:** A direct pointer to a block of memory. +* **Handle:** A pointer to a master pointer. Allows the Memory Manager to move the underlying block (relocate it) to reduce fragmentation without invalidating references. + +### Resources +Data is often stored in the Resource Fork of a file. +* **Map:** Index of resources in the file. +* **Data:** The actual binary data. +* **Types:** 4-character codes (e.g., `'CODE'`, `'DLOG'`, `'WIND'`). + +## Core Entities + +### WindowRecord (`WindowPtr`) +Represents a window on the screen. +* `port`: The graphics port (GrafPort) for drawing. +* `windowKind`: Type of window (dialog, desk accessory, etc.). +* `visible`: Boolean visibility flag. +* `refCon`: Arbitrary data storage for the application. + +### DialogRecord (`DialogPtr`) +Extends WindowRecord for dialog boxes. +* `items`: Handle to the item list (controls, text). +* `textH`: Handle to the current text edit record. + +### EventRecord +Represents a user or system event. +* `what`: Event type (mouseDown, keyDown, updateEvt). +* `message`: Event-specific data (key code, window pointer). +* `when`: Timestamp (ticks since boot). +* `where`: Mouse coordinates. +* `modifiers`: State of Shift, Cmd, Option keys. + +### File System Catalog +* **CatNode:** A node in the HFS B-Tree (File or Folder). +* **FInfo:** File metadata (Type, Creator, location). + +## Schema Diagram (Conceptual) + +```mermaid +classDiagram + class EventRecord { + +int what + +long message + +long when + +Point where + +int modifiers + } + + class WindowRecord { + +GrafPort port + +short windowKind + +boolean visible + +boolean hilited + +long refCon + } + + class DialogRecord { + +WindowRecord window + +Handle items + +TEHandle textH + } + + class FileInfo { + +OSType fdType + +OSType fdCreator + +short fdFlags + +Point fdLocation + } + + DialogRecord --|> WindowRecord : Extends + EventRecord ..> WindowRecord : References +``` diff --git a/docs/deployment.md b/docs/deployment.md new file mode 100644 index 0000000..b8ddff2 --- /dev/null +++ b/docs/deployment.md @@ -0,0 +1,49 @@ +# Deployment + +This guide explains how to deploy the built system artifacts. + +## Build Artifacts +After a successful build, the `Build/` directory will contain: +* **System:** The main system file (resource suitcase). +* **Finder:** The Finder application (or MiniFinder if linked). +* **ROM Images:** (If applicable) ROM builds. + +## Deployment Targets + +### 1. Macintosh Emulator (Recommended) +You can test the build using emulators like **Mini vMac**, **BasiliskII**, or **MAME**. + +**Steps:** +1. Create a blank HFS disk image using `hfsutils` (or `dd` and `mkfs.hfs`). + ```bash + dd if=/dev/zero of=System7.img bs=1M count=10 + /usr/sbin/hformat -l "System 7" System7.img + ``` +2. Copy the built `System` and `Finder` binaries into the image. + ```bash + hmount System7.img + hmkdir "System Folder" + hcopy Build/System ":System Folder:System" + hcopy Build/Finder ":System Folder:Finder" + # Bless the System Folder + hattrib -b ":System Folder" + humount + ``` +3. Configure your emulator to mount `System7.img` as the boot drive. + +### 2. Real Hardware +To deploy to a real Macintosh (e.g., SE/30, IIci): +1. Write the disk image to a floppy disk or SD card (scsi2sd). +2. Or, use a bridge machine to copy the files over LocalTalk/Ethernet. + +## Publishing Documentation +This documentation site is designed to be published via **GitHub Pages**. + +### Setup +1. Go to the repository **Settings** on GitHub. +2. Navigate to **Pages**. +3. Under **Source**, select **Deploy from a branch**. +4. Select the **main** branch and the **/docs** folder. +5. Click **Save**. + +The site will be available at `https://.github.io//`. diff --git a/docs/development-guide.md b/docs/development-guide.md new file mode 100644 index 0000000..a57a573 --- /dev/null +++ b/docs/development-guide.md @@ -0,0 +1,48 @@ +# Development Guide + +This guide describes the workflow for contributing to the project and understanding the codebase structure. + +## Directory Layout + +* `OS/`: Kernel and core services. +* `Drivers/`: Hardware drivers. +* `Interfaces/`: Public API headers. +* `Internal/`: Private headers and stubs. +* `Make/`: Build configuration. +* `Build/`: Generated artifacts (created during build). + +## Code Style +The codebase follows Apple's internal style from the early 90s. +* **Languages:** Pascal, C, Assembly (68k). +* **Naming:** PascalCase is dominant (e.g., `InitWindows`, `NewPtr`). +* **Comments:** mostly `/* ... */` in C, `(* ... *)` in Pascal, `;` in Assembly. + +## Workflow + +### 1. Adding a New Feature +1. Identify the appropriate module in `OS/` or `Drivers/`. +2. Add your source file (e.g., `.c` or `.a`). +3. Update the `Make/MainCode.Make` file to include your new object in the link list. + * *Tip:* You can use `patch_makefile.sh` logic to append it if you don't want to edit the makefile directly. + +### 2. Modifying Existing Code +1. Locate the source file. +2. Edit the code. +3. Run `./build_system7.sh` to rebuild. + +### 3. Debugging +Since this is a cross-compiled OS kernel, debugging is challenging. +* **Emulation:** Run the built image in a Macintosh emulator (e.g., Mini vMac, BasiliskII, MAME). +* **Debug Output:** You can write to a specific memory address or use a serial driver (if implemented) to log messages. +* **Stubs:** Use `Internal/C/MiniFinder.c` to create simple test harnesses that run immediately after boot. + +## Testing +There is no unit test framework in the modern sense. Testing involves: +1. Building the system. +2. Booting the image in an emulator. +3. Verifying behavior manually or via the `MiniFinder` logic. + +## Tools +* **empw:** The core tool for running the compiler. +* **ResEdit:** (On a real Mac/Emulator) Useful for inspecting resource files (`.rsrc`). +* **Disassemblers:** Tools like IDA Pro or Ghidra (with m68k support) are useful for analyzing binary blobs if source is missing. diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 0000000..b8fef1e --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,86 @@ +# Getting Started + +This guide will help you set up your development environment to cross-compile Macintosh System 7.1 on Linux. + +## Prerequisites + +Before you begin, ensure you have the following installed on your Linux machine (e.g., Ubuntu/Debian): + +* **Bash:** The shell used for build scripts. +* **Git:** Version control. +* **Wget & Unrar:** For downloading and extracting reference binaries. +* **HFSUtils:** For manipulating HFS disk images. +* **Build Essentials:** `make`, `gcc` (standard Linux build tools). + +### Installation (Debian/Ubuntu) + +```bash +sudo apt-get update +sudo apt-get install git wget unrar hfsutils build-essential +``` + +## Step-by-Step Setup + +### 1. Clone the Repository + +```bash +git clone system7-source +cd system7-source +``` + +### 2. Install `empw` + +The build system relies on `empw` (Emulated MPW) to run the original Macintosh Programmer's Workshop tools. + +1. Download or build `empw` from [ksherlock/mpw](https://github.com/ksherlock/mpw). +2. Ensure the `empw` binary is in your system `$PATH`. + +```bash +empw --version +# Should output version information +``` + +### 3. Setup MPW Tools + +You need to populate the `MPW/` directory in the root of this repository with the MPW Shell and Tools. These are proprietary files and are not included in this repository. + +* Create a directory named `MPW` in the repo root. +* Copy your MPW environment (Shell, Tools, Libraries) into it. + +### 4. Run the Setup Script + +The `cross_compile.sh` script automates the remaining setup: + +* Checks for MPW tools. +* Downloads and extracts reference binaries (System, Finder). +* Creates the build wrapper `build_system7.sh`. +* Patches the Makefiles to include necessary stubs. + +```bash +./cross_compile.sh +``` + +**Note:** If you are missing the `MPW/` directory, the script will warn you. + +### 5. Build the System + +Once setup is complete, use the generated wrapper script to start the build: + +```bash +./build_system7.sh +``` + +This will: +1. Launch `empw`. +2. Execute the build instructions in `Make/Universal.make` (or `Make/MainCode.Make`). +3. Output artifacts to the `Build/` directory. + +## "Hello World" Example + +To verify your environment, you can look at the `Internal/C/MiniFinder.c`. This is a minimal application that replaces the Finder. + +If the build succeeds, you should see an object file or binary corresponding to this stub in the build output. + +```bash +ls -l Build/ +``` diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..d709b04 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,35 @@ +# Macintosh System 7.1 Source Code + +Welcome to the documentation for the Macintosh System 7.1 source code repository. This project aims to preserve, analyze, and build the classic Mac OS for research and educational purposes. + +## Project Overview + +This repository contains a leaked and reconstructed version of the Macintosh System 7.1 source code. It includes the core operating system, device drivers, and build tools necessary to compile a bootable system image for m68k Macintosh computers. + +**Primary Goal:** Enable cross-compilation of System 7.1 on modern Linux systems. + +## Key Features + +- **Cross-Compilation:** Build classic Mac software on Linux using `empw`. +- **Core OS:** Source code for Memory Manager, Process Manager, HFS, and more. +- **Hardware Support:** Drivers for Macintosh SE/30, IIci, and other m68k machines. +- **Reconstruction:** Includes stubs and patches (e.g., `MiniFinder`) to replace missing proprietary components. + +## Documentation Sections + +- [**Getting Started**](getting-started.md): Setup your environment and build the system. +- [**Architecture**](architecture.md): High-level overview of the system design. +- [**Modules**](modules/index.md): Detailed documentation of subsystems (OS, Drivers, etc.). +- [**Configuration**](configuration.md): Understanding the build system and `.make` files. +- [**Development Guide**](development-guide.md): How to contribute and debug. +- [**Data Models**](data-models.md): Key data structures and schemas. +- [**Troubleshooting**](troubleshooting.md): Common issues and solutions. +- [**Deployment**](deployment.md): How to deploy the built system. + +## Quick Links + +- [Repository Root](../) +- [GitHub Issues](https://github.com/your-repo/issues) + +--- +*Disclaimer: This documentation is generated based on the analysis of the source code. Some sections may reflect the incomplete nature of the repository.* diff --git a/docs/modules/drivers.md b/docs/modules/drivers.md new file mode 100644 index 0000000..5d17dbb --- /dev/null +++ b/docs/modules/drivers.md @@ -0,0 +1,37 @@ +# Drivers Module + +The `Drivers/` directory contains the low-level software that controls the Macintosh hardware. These drivers provide a standard interface for the OS and Toolbox to interact with devices. + +## Driver Structure +Macintosh drivers typically follow a standard structure: +* **Open:** Initialize the driver/device. +* **Close:** Shut down the driver. +* **Control:** Send commands to the device. +* **Status:** Get information from the device. +* **Prime:** Perform I/O operations (Read/Write). + +## Key Drivers + +### 1. Sony (`Drivers/Sony/`) +The driver for the 3.5" Floppy Disk Drive. +* **Role:** Handles raw track reading/writing, GCR encoding/decoding. +* **Importance:** Often the primary boot device. + +### 2. Video (`Drivers/Video/`) +Manages the frame buffer and display hardware. +* **Role:** Sets video modes, handles vertical blanking interrupts (VBL). + +### 3. IOP (`Drivers/IOP/`) +Support for I/O Processors found in machines like the Mac IIfx and Quadra 900/950. +* **Role:** Offloads I/O tasks from the main CPU. + +### 4. EDisk (`Drivers/EDisk/`) +Likely an emulator or RAM disk driver used for testing or specific boot scenarios. + +## Interfaces +Drivers interact with the system via: +* **Device Manager:** The OS component that loads and manages drivers. +* **Interrupts:** Drivers install Interrupt Service Routines (ISRs) to handle hardware events asynchronously. + +## Configuration +Driver configuration is often hardcoded or determined at runtime by the `SlotMgr` (for NuBus cards) or `StartMgr` (for built-in devices). diff --git a/docs/modules/index.md b/docs/modules/index.md new file mode 100644 index 0000000..77268eb --- /dev/null +++ b/docs/modules/index.md @@ -0,0 +1,8 @@ +# Modules + +Detailed documentation for the various subsystems of Macintosh System 7.1. + +* [**Operating System (OS)**](os.md): Core kernel services (Memory, Process, File System). +* [**Drivers**](drivers.md): Hardware abstraction and device drivers. +* [**Interfaces**](interfaces.md): Public API headers (Toolbox). +* [**Internal**](internal.md): Private stubs and implementation details. diff --git a/docs/modules/interfaces.md b/docs/modules/interfaces.md new file mode 100644 index 0000000..acb23ed --- /dev/null +++ b/docs/modules/interfaces.md @@ -0,0 +1,26 @@ +# Interfaces Module + +The `Interfaces/` directory contains the public API definitions for the system. These files define the structures, constants, and function prototypes used by applications and system components. + +## Languages Supported +The interfaces are provided for multiple languages, reflecting the development environment of the era: +* **C (`CIncludes/`):** Headers for C programming. +* **Pascal (`PInterfaces/`):** Interfaces for Pascal (the primary language of the original Mac OS). +* **Assembly (`AIncludes/`):** Equate files (`.a`) for assembly language development. + +## Organization + +### `CIncludes/` & `PInterfaces/` +Contains high-level definitions for Toolbox managers. +* `Windows.h` / `Windows.p`: Window Manager. +* `Menus.h` / `Menus.p`: Menu Manager. +* `Files.h` / `Files.p`: File Manager. +* `Memory.h` / `Memory.p`: Memory Manager. + +### `AIncludes/` +Contains low-level offsets and bit definitions. +* `SysEqu.a`: System global variables. +* `Traps.a`: Trap numbers. + +## Usage +These files are essential for compiling any code that interacts with the System 7.1 API. The build system includes these directories in the search path (e.g., `-i {AIncludes}`). diff --git a/docs/modules/internal.md b/docs/modules/internal.md new file mode 100644 index 0000000..023381c --- /dev/null +++ b/docs/modules/internal.md @@ -0,0 +1,30 @@ +# Internal Module + +The `Internal/` directory contains private implementation details, glue code, and stubs that are not part of the public API. + +## Subdirectories + +### `C/` and `Pascal/` +Private headers and source files. These contain: +* **Private APIs:** Functions shared between system components but not exposed to developers. +* **Internal Data Structures:** Structs and records used internally by managers. +* **Stubs:** `MiniFinder.c` and `VirtualMemoryStub.c` are located here. + +### `Asm/` +Private assembly definitions and macros. +* `SysPrivateEqu.a`: Private system globals. +* `Emulator68kStub.a`: Stub for the 68k emulator (used on PPC or for specific build configs). + +## Key Files + +### `MiniFinder.c` +A reconstructed stub application that serves as a placeholder for the Finder. +* **Purpose:** Allows the system to boot into a known state without requiring the proprietary Finder source code. +* **Functionality:** Initializes the Toolbox, draws a desktop pattern, and runs a basic event loop. + +### `VirtualMemoryStub.c` +A placeholder for Virtual Memory functionality. +* **Purpose:** Satisfies link-time dependencies for VM calls if the full VM implementation is missing or excluded. + +## Role in Build +The `cross_compile.sh` script specifically checks for and compiles files in this directory to ensure a complete link. `patch_makefile.sh` ensures these objects are included in the final link list. diff --git a/docs/modules/os.md b/docs/modules/os.md new file mode 100644 index 0000000..fa05a03 --- /dev/null +++ b/docs/modules/os.md @@ -0,0 +1,47 @@ +# Operating System (OS) Module + +The `OS/` directory contains the core low-level components of Macintosh System 7.1. These components run in the kernel address space and provide essential services to the rest of the system. + +## Key Components + +### 1. Memory Manager (`MemoryMgr/`) +Responsible for managing the system heap and application heaps. +* **Concepts:** Pointers, Handles (relocatable blocks), Heap Zones. +* **Responsibilities:** Allocation, Deallocation, Compaction, Purging. + +### 2. Process Manager (`ProcessMgr/`) +Implements the cooperative multitasking model introduced in System 7. +* **Responsibilities:** + * Creating and destroying processes. + * Scheduling (context switching on `WaitNextEvent`). + * Apple Events (Inter-Process Communication). + +### 3. File System (`HFS/`) +Implements the Hierarchical File System (HFS). +* **Features:** Forks (Data Fork, Resource Fork), Catalog Tree, Extents Overflow. +* **Interaction:** Accessed via the File Manager API. + +### 4. Trap Dispatcher (`TrapDispatcher/`) +The mechanism that intercepts m68k "A-Line" instructions (0xAxxx) and routes them to the appropriate system routine. +* **Role:** Provides binary compatibility and allows patching of system functions. + +### 5. Other Managers +* **TimeMgr:** Manages time-based tasks and delayed execution. +* **PowerMgr:** Manages power states (crucial for Portables/PowerBooks). +* **SlotMgr:** Manages NuBus expansion slots. +* **StartMgr:** Handles the boot process. + +## Directory Structure + +| Directory | Description | +|-----------|-------------| +| `MemoryMgr/` | Memory management implementation. | +| `ProcessMgr/` | Process scheduling and IPC. | +| `HFS/` | HFS file system driver. | +| `Traps/` | Trap dispatch tables and logic. | +| `StartMgr/` | Boot logic. | +| `MMU/` | Memory Management Unit control (Virtual Memory support). | + +## Dependencies +* **Hardware:** Relies heavily on m68k specific instructions and hardware mapping. +* **Drivers:** Uses drivers in `Drivers/` to access physical storage and devices. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 0000000..51807c3 --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,42 @@ +# Troubleshooting + +Common issues and solutions when building or running the system. + +## Build Failures + +### `empw: command not found` +**Cause:** The `empw` binary is not in your `$PATH`. +**Fix:** Install `empw` and add its location to your PATH. +```bash +export PATH=$PATH:/path/to/empw +``` + +### `File not found` errors during build +**Cause:** MPW is case-insensitive, but Linux is case-sensitive. `empw` handles some of this, but file naming mismatches can occur. +**Fix:** Ensure files in the repo match the casing expected by the `.make` files. + +### `MainCode.Make` parsing errors +**Cause:** The makefile has special character encoding (Mac Roman) that might be corrupted by text editors. +**Fix:** Avoid editing `Make/MainCode.Make` with editors that auto-convert line endings or encodings. Use hex editors or script-based appending (like `patch_makefile.sh`). + +### Missing `MiniFinder.c.o` +**Cause:** The stubs were not compiled or the makefile patch didn't apply. +**Fix:** Run `patch_makefile.sh` again and check `Make/MainCode.Make` for the appended lines. + +## Runtime Issues + +### Emulator hangs at boot +**Cause:** Incomplete OS initialization, missing drivers, or memory corruption. +**Fix:** +1. Check if `MiniFinder` is being reached (add an infinite loop with a visual indicator if possible). +2. Ensure you are using a compatible ROM file in your emulator (e.g., Mac IIci or SE/30 ROM). + +### "Sad Mac" Icon +**Cause:** Hardware test failure or severe kernel panic. +**Fix:** Decode the hex code under the Sad Mac (consult "Sad Mac Error Codes" documentation online). + +## Logs +The build process logs to stdout. Redirect to a file to analyze: +```bash +./build_system7.sh > build.log 2>&1 +```