Files

52 lines
6.5 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Assembly Development
> Technical evidence extract for the VCC Plus white paper. Only reviewed contracts, mechanisms, methods, results and limitations are retained. Original validation dates and configuration limits remain historical; this export is not a new test run.
Open **Develop → Assembly Development…** at a CoCo 3 BASIC prompt. The first document is Hello World — Earth or Mars. You can run it before saving a file or creating a disk.
## Working with several files
Use **File → Open Source…** for a single file with local includes, or **Open Project Folder…** for a folder of sources. Assembly instructions in LWASM normally start after whitespace. Put labels in the left column. Relative filenames and labels keep their original spelling and case. Save your work as ordinary UTF-8 source. Recoverable drafts retain edits separately from saved files.
The default project entry is `main.asm`. In a project folder, **File → Project Settings…** opens the editable `vccplus-assembly.json` configuration. For an object-linked program, set the entry module, additional modules and your LWLINK script:
```json
{
"main": "main.asm",
"modules": ["draw.asm"],
"linkScript": "layout.link"
}
```
VCC Plus assembles each module, links the objects and verifies source addresses against the final loaded bytes. Use the listing or native disassembly when a source location is ambiguous. A custom Make recipe can instead declare `makefile`, `target` and `binary`. Review the recipe before allowing it to run with your Mac account’s permissions. Custom recipes produce a runnable/exportable binary and can use the machine debugger. Verified source stops require the native assembly or link workflow.
## Share an assembly project with a local assistant
In Assembly Development, choose **File → Local Assistant Access… → Save Assembly Connection…**. The saved connection gives one client access to the current assembly document, including unsaved edits. Configure the client with the bundled helper and the saved connection file. See the local MCP client instructions.
Build 28 can read the listed files, assemble them with the bundled LWASM, return diagnostics and propose a single-line replacement. Review the current and proposed lines in the access panel. **Apply Edit** updates that buffer and supports the editor’s usual Undo. Assemble the revised source, set a stop on an executable instruction, then choose **Run Shared Build…**. At a verified pause the client can read the mapped source line, instruction bytes, PC, available A and E registers and the text byte at `$0400`. **Revoke Connection** ends access. Selecting another document also ends its grant.
Build 29 adds **multi-file review**. The assistant can call `propose_project_edits` with one to eight existing shared assembly or include files and up to 16 KiB of UTF-8 replacement source altogether. Open each filename to compare the entire proposed source with its current draft. **Apply All Changes** updates all the drafts together. **Cancel Changes** preserves them. Save writes the updated files. **Undo All Changes** in the access panel restores the previous drafts as one operation while that applied revision is current. If the workspace changes during review, ask the client to reread and propose against the new revision. Native two-file review
In build 30, start the shared build from the BASIC prompt to play an assembly text game over MCP. After the native launch the assistant can read the screen and send one letter, digit or space at a time. When the program returns to BASIC, the live game controls close. Play an interactive program
The development client can also call `get_machine_status` for the actual CPU, memory and media state, build and run blockers, and the latest build ID and status. Use `get_run` after a native run to obtain its run ID. At a verified source stop, `get_debug_snapshot` returns registers, the source stop and the readable address ranges. Pass the same run and snapshot IDs to `read_debug_memory` to read up to 256 permitted bytes. Stale snapshots and addresses outside the disclosed ranges are refused.
Share a direct-assembly project containing up to 32 UTF-8 assembly and include files, up to 64 KiB each and 512 KiB overall. Project includes must resolve inside the shared snapshot. Linked projects and custom Make recipes use the native workbench. Earlier CPU and target qualification
The assembly regression client exercises a dedicated app launched with `--interface-validation --mcp-assembly-regression --mcp-assembly-fixture EMPTY_DIR --mcp-rom-dir ROM_DIR`. Use a fresh, private directory each time and pass `--helper HELPER --fixture EMPTY_DIR --cpu 6809 --target 6809` to the client. For HD6309, add `--basic-6309 --mcp-assembly-hd6309` to the app and use `--cpu 6309 --target 6309` for the client. The test covers stale proposals, cancellation, whole-project apply and undo, an assembled run after changing both files, snapshot-scoped memory reads, and refusal of an out-of-project include. The optional mismatched combination checks that a 6809 guest refuses HD6309-only code.
## Verification on November 5, 2026
The screen-cell lesson assembled and ran in Disk BASIC, Hard Drive BASIC and CoCo SDC on both emulated processors. The disk export also ran from a Disk BASIC prompt with `LOADM"FIRST":EXEC`. The two-module test checked the linked address of a subroutine and its relocated operand. Follow the reference lesson table to reproduce the seven smaller CPU experiments.
The 78 focused Xcode tests passed on arm64 and again under x86_64 Rosetta. They cover assembly, BASIC bibliography and profile integration, the shared C build and source-map services, and disk safeguards. All 66 portable core checks also passed on arm64.
On macOS 27.2 with Xcode 27.2, the isolated native window test stopped before the first instruction, stepped twice, returned keyboard focus to the running CoCo, opened an example in a separate document and resized the editor. The relocated, locally signed development app produced identical binaries with the arm64 and Rosetta x86_64 slices of its embedded assembler. Physical Intel hardware, a macOS 14 installation and a notarized installer were outside this pass.
- Assembly editor paused after the screen write
- Quick Reference with LDA selected
While the editor is open it monitors the active project's files. Before source stepping or continuing it rechecks the project inputs. While a different document is open or the window is closed, a running guest can still reach stops armed for the previously loaded binary.