LIV2/CIDER-Software
1
0
Fork 0
mirror of https://github.com/LIV2/CIDER-Software.git synced 2025-12-06 00:23:50 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update documentation

Browse Source
This commit is contained in:
Matt Harlum 2025-09-21 14:45:12 +12:00
parent 3183606d23
commit e23e0adfe9
5 changed files with 688 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
.gitmodules vendored
View File

@ -1,3 +0,0 @@
[submodule "iderom/ide_device"]
path = ideupdate/lide.device
url = git@github.com:LIV2/lide.device.git

32
README.md
View File

@ -1,14 +1,34 @@
# CIDER Software
This repository contains software utilities for the [CIDER](https://github.com/LIV2/CIDER) CDTV Expansion
This repository contains software utilities for the [CIDER](https://github.com/LIV2/CIDER) expansion board for Amiga computers.
## Contents
- [addram](https://github.com/LIV2/CIDER-Software/tree/main/addram) Adds the A0/Bonus RAM to the system
- [bootrom](https://github.com/LIV2/CIDER-Software/tree/main/bootrom) A Kickstart module to add the Bonus RAM to the system at boot
- [cflash](https://github.com/LIV2/CIDER-Software/tree/main/cflash) A tool to manage the Kick Flash and update the IDE ROM
## What is CIDER?
CIDER is an expansion board for the Commodore CDTV that significantly enhances its capabilities:
- **11.37 MB Fast RAM**: Including 1.5 MB Ranger RAM, 8 MB standard Fast RAM, and 1.87 MB Bonus RAM at $A00000
- **IDE Interface**: Built-in IDE controller with autoboot driver for hard drives and other storage
- **Dual Kickstart Flash ROM**: Programmable flash memory for multiple Kickstart and Extended ROMs
- **In-system programming**: All flash components can be updated without removing the board
- **CDTV integration**: Plugs into the CDTV's diagnostic port for seamless integration
## Tools Overview
- **[cflash](https://github.com/LIV2/CIDER-Software/tree/main/cflash#cflash)** - Flash ROM programming tool for Kickstart and Extended ROMs
- **[addram](https://github.com/LIV2/CIDER-Software/tree/main/addram#addram)** - Manual tool to add BonusRAM to your system with configurable options
- **[bootrom](https://github.com/LIV2/CIDER-Software/tree/main/bootrom#cider-bootrom)** - Automatic resident module that adds BonusRAM at boot time
## Quick Start
**New to CIDER?** Choose the right tool for your needs:
- **Want automatic memory activation?** → Use **bootrom** (integrate into Extended ROM for set-and-forget operation)
- **Need control over memory settings?** → Use **addram** (command-line tool with options for testing and configuration)
- **Want to update ROMs?** → Use **cflash** (program new Kickstart/Extended ROMs to flash memory)
Each tool has comprehensive documentation with step-by-step instructions for both beginners and advanced users.
## Downloads
Binaries are provided under [Releases](https://github.com/LIV2/CIDER-Software/releases)
* CIDER-Software.adf and CIDER-Software.lha contain binaries for the tools in this repositiory
* CIDER-Software.adf and CIDER-Software.lha contain binaries for the tools in this repository
* IDE firmware can be programmed using the lastest [lide-update adf](https://github.com/LIV2/LIDE.device/releases/latest)
## Third-Party notice

246
addram/README.md
View File

@ -1,15 +1,247 @@
# Addram
# ADDRAM
A tool to add the BonusRAM ($A0000) to the system
A tool to add the BonusRAM to your CIDER-equipped system's memory pool.
## What is ADDRAM?
ADDRAM is a tool that activates and adds the BonusRAM provided by your CIDER expansion board to your Amiga's memory system. BonusRAM uses the address space from $A00000 to $BEFFFF.
When you run ADDRAM, it:
1. Tests and detects available BonusRAM
2. Enables the BonusRAM hardware
3. Adds the memory to your system's Fast RAM pool
4. Optionally merges it with existing Fast RAM for better efficiency
## Before You Start
### Getting Started
- ADDRAM only adds memory that's physically present on your CIDER board
- The tool safely tests memory before adding it to avoid system conflicts
- **Safe operation**: If BonusRAM is already active, ADDRAM will detect this and exit safely
### What You'll Need
- Your CIDER-equipped Amiga
- The addram program (available in [CIDER-Software.adf](https://github.com/LIV2/CIDER-Software/releases/latest))
- A CLI/terminal or Workbench to run commands
### Prerequisites
- CIDER expansion board must be properly installed
- System should be stable with adequate power
- No conflicting memory expansions in the BonusRAM address space
## Basic Usage
### Simple Memory Addition
To add BonusRAM to your system with default settings:
## Usage
```
-d - Perform a dry-run
-v - Verbose
-m - Attempt to merge Bonus RAM with Fast RAM Memory block
-p <priority> - Set Fast / BonusRAM Priority
addram
```
This will:
- Test and detect available BonusRAM
- Add it to your system as Fast RAM
- Use default priority settings
### Check What Would Happen (Dry Run)
To see what ADDRAM would do without actually changing anything:
```
addram -d
```
This is useful for:
- Checking how much BonusRAM is available
- Verifying the tool detects your CIDER board
- Testing before making actual changes
### Verbose Output
To see detailed information about what's happening:
```
addram -v
```
This shows:
- Memory testing progress
- Detected memory size
- Board information
- Priority changes
### Combined Options
```
addram -d -v
```
Shows detailed information while doing a dry run.
## Advanced Options
### Setting Memory Priority
You can control the priority of Fast RAM and BonusRAM:
```
addram -p 10
```
This sets the Fast/BonusRAM priority to 10. Higher numbers mean higher priority for memory allocation.
**Priority explained:**
- Higher priority memory gets used first by the system
- Useful for controlling which memory gets allocated for different purposes
- Default system behavior works well for most users
### Merging with Fast RAM
For optimal memory layout, you can merge BonusRAM with existing Fast RAM:
```
addram -m
```
**Benefits of merging:**
- Creates one large contiguous Fast RAM block
- More efficient memory management
- Better for applications that need large memory allocations
**Note:** This is an advanced feature that modifies memory structures more extensively.
### Combined Advanced Usage
```
addram -v -m -p 15
```
This will:
- Show verbose output
- Merge BonusRAM with Fast RAM
- Set priority to 15
## Understanding BonusRAM
### Memory Layout
- **Address Range**: $A00000 to $BEFFFF (up to ~2MB)
- **Type**: Fast RAM (32-bit, no wait states)
- **Compatibility**: Works with all Amiga software that supports Fast RAM
### How It Works
1. CIDER provides RAM in the $A00000-$BEFFFF address space
2. For RAM-equipped addresses, it provides fast memory access
3. This provides additional memory in previously unused address space
## Troubleshooting
### "Memory block already added"
- BonusRAM is already active in your system
- This is normal if you've already run ADDRAM
- **Solution**: BonusRAM is working - no action needed
### "Board not found"
- CIDER expansion board isn't detected
- **Check**: Board is properly seated and connected
- **Check**: Board firmware is up to date
### "No memory found"
- CIDER board detected but no BonusRAM available
- **Possible causes**:
- Hardware fault with RAM
### "Detected more ram than should be in Bonus region"
- Unusual memory configuration detected
- **Solution**: Check your memory configuration and board installation
## Example Workflows
### First Time Setup
```
# 1. Check what's available (safe)
addram -d -v
# 2. Add the memory
addram -v
# 3. Verify in system (check with avail command)
avail
```
### Optimal Configuration
```
# Add BonusRAM merged with Fast RAM for best performance
addram -v -m
```
### Custom Priority Setup
```
# Set specific priority for memory management
addram -v -p 20
```
### Startup-Sequence Integration
To automatically add BonusRAM every time you boot, add this to your startup-sequence:
```
; Add BonusRAM if available
C:addram >NIL:
```
Or for verbose output during boot:
```
; Add BonusRAM with status messages
C:addram -v
```
For optimal performance with automatic merging:
```
; Add BonusRAM merged with Fast RAM
C:addram -m >NIL:
```
**Startup-sequence tips:**
- Place the addram command early in your startup-sequence
- Use `>NIL:` to suppress output during normal boot
- Remove `>NIL:` if you want to see status messages during boot
## Getting Help
If addram won't run or you get errors, try running it with help option:
```
addram -h
```
This shows all available options and their syntax.
## Technical Details
### Memory Integration
- BonusRAM is added as MEMF_FAST type memory
- Can be merged with existing Fast RAM blocks for efficiency
- Priority system ensures proper memory allocation order
## Command-line Options
```
Usage: addram [-d] [-v] [-p <Priority>] [-m] [-h]
-d - Dry run (test without making changes)
-v - Verbose output
-p - Set Fast/BonusRAM priority
-m - Merge BonusRAM with Fast RAM blocks
-h - Show help
```
## Final Tips
1. **Start with dry run**: Use `-d -v` first to see what will happen
2. **Merge for performance**: Use `-m` for optimal memory layout
3. **Default works well**: Basic `addram` is fine for most users
4. **Check with avail**: Use the `avail` command to verify memory was added
5. **Run once**: You typically only need to run ADDRAM once per boot
## License
[![License: GPL v2](https://img.shields.io/badge/License-GPL_v2-blue.svg)](https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html)

208
bootrom/README.md
View File

@ -1,13 +1,209 @@
# BootROM
# CIDER BootROM
A resident module that adds the BonusRAM ($A0000) to the system
A resident module that automatically adds BonusRAM to your CIDER-equipped system at boot time.
This will automatically add the $A0000 RAM to your system's memory pool if Fast RAM is enabled
## What is BootROM?
If the Left mouse-button is held at boot it will not run
BootROM is a resident module (library) that automatically detects and adds your CIDER board's BonusRAM to the system memory pool during the boot process. Unlike the standalone `addram` tool, BootROM runs automatically every time you boot your system without requiring any user intervention.
## Usage
Add to your extended rom using Remus/Romtool or use with loadmodule
### Key Features
- **Automatic operation**: Runs during system startup without user intervention
- **Smart detection**: Only activates if CIDER board and BonusRAM are present
- **Memory merging**: Attempts to merge BonusRAM with existing Fast RAM for optimal layout
- **Safe fallback**: Creates separate memory block if merging isn't possible
- **Boot bypass**: Hold left mouse button during boot to skip activation
- **Legacy support**: Fixes memory priorities on Kickstart 1.x systems
## How It Works
BootROM integrates into the Amiga's boot process as a resident module:
1. **Detection**: Scans for CIDER board during system startup
2. **Testing**: Safely tests available BonusRAM using non-destructive methods
3. **Integration**: Adds memory to system pool, preferring to merge with existing Fast RAM
4. **Optimization**: On older Kickstart versions, adjusts memory priorities for better performance
### Memory Layout
- **Address Range**: $A00000 to $BEFFFF (up to ~2MB)
- **Type**: Fast RAM (32-bit, no wait states)
- **Integration**: Merged with existing Fast RAM when possible
- **Compatibility**: Works with all Amiga software that supports Fast RAM
## Installation Methods
### Method 1: Extended ROM Integration (Recommended)
For permanent installation, integrate BootROM into your Extended ROM using tools like Remus or Romtool. The custom Extended ROM can then be easily programmed into your CIDER's flash memory using the cflash tool.
**Benefits:**
- Automatic activation on every boot
- No startup-sequence modification needed
- Works even with minimal system configurations
- Fastest activation (runs early in boot process)
- Easy installation to flash memory with cflash
### Method 2: LoadModule Command
For temporary or testing purposes, you can load BootROM manually:
```
loadmodule bootrom
```
**Use cases:**
- Testing before permanent installation
- Temporary setups
- Systems where you don't want to modify Extended ROM
### Method 3: Startup-Sequence Integration
Add to your startup-sequence for automatic loading:
```
; Load CIDER BootROM support
C:loadmodule DEVS:bootrom
```
## User Control
### Bypassing BootROM
To prevent BootROM from activating (useful for troubleshooting):
1. **During boot**: Hold the **left mouse button** while the system starts
2. **Keep holding** until the boot process completes
3. **Result**: BootROM will detect the button press and skip activation
This is useful when:
- Troubleshooting memory issues
- Testing system without BonusRAM
- Comparing performance with/without additional memory
### Verifying Operation
Check if BootROM successfully added memory:
```
avail
```
Look for:
- Increased Fast RAM amount
- Memory blocks labeled "GottaGoFast!"
- Total available memory increase
## Technical Details
### Resident Module Integration
- **Priority**: Runs during cold start initialization
- **Type**: NT_LIBRARY resident module
- **Activation**: Automatic during system boot
- **Dependencies**: Requires expansion.library
### Memory Testing Method
BootROM uses safe, non-destructive memory testing:
- Tests at offset +$B00 from each 64KB boundary
- Avoids potential conflicts with system hardware
- Uses address-based test patterns
- Restores original values after testing
### Memory Integration Strategy
1. **Preferred**: Merge with existing Fast RAM block for contiguous memory
2. **Fallback**: Create separate BonusRAM memory block
3. **Optimization**: Adjusts memory priorities on Kickstart 1.x systems
### Kickstart 1.x Enhancements
On older Kickstart versions, BootROM provides additional optimizations:
- Sets Ranger RAM priority to -5 for better allocation order
- Ensures proper memory type flags are set
- Improves overall memory management behavior
## Troubleshooting
### BootROM Not Running
- **Check installation**: Verify BootROM is properly integrated into Extended ROM
- **Check board**: Ensure CIDER board is properly installed and detected
- **Mouse button**: Make sure you're not accidentally holding left mouse button during boot
### Memory Not Added
- **No BonusRAM**: Board may not have RAM installed or RAM may be faulty
- **Already active**: Memory may already be added by other means (addram tool, etc.)
- **Board detection**: CIDER board may not be detected properly
### Verification
Use these commands to check system status:
```
; Check available memory
avail
; Check for CIDER board (if you have appropriate tools)
showconfig
; Check memory layout
showmem
```
## Comparison with ADDRAM Tool
| Feature | BootROM | ADDRAM Tool |
|---------|---------|-------------|
| **Activation** | Automatic | Manual |
| **Boot timing** | Early (resident) | Later (startup-sequence) |
| **User control** | Mouse button bypass | Command line options |
| **Installation** | Extended ROM | Startup-sequence |
| **Flexibility** | Fixed behavior | Configurable options |
| **Best for** | Set-and-forget | Testing and customization |
### When to Use Each
**Use BootROM when:**
- You want automatic, hands-off operation
- You have a stable system configuration
- You want the earliest possible memory activation
- You prefer ROM-based solutions
**Use ADDRAM tool when:**
- You want control over memory configuration
- You need verbose output for troubleshooting
- You want to test different settings
- You prefer startup-sequence based solutions
## Integration Examples
### Extended ROM Integration Workflow
```
# 1. Obtain bootrom module from CIDER-Software.lha
# Download from: https://github.com/LIV2/CIDER-Software/releases/latest
# 2. Backup your current Extended ROM
cp extended.rom extended.rom.backup
# 3. Add bootrom to Extended ROM using Remus/Romtool
<use your preferred ROM tool to add bootrom to extended.rom>
# 4. Flash updated Extended ROM to your CIDER
cflash -x extended.rom
```
### Testing Before Permanent Installation
```
# 1. Test with loadmodule first
loadmodule bootrom
# 2. Verify memory was added
avail
# 3. If satisfied, integrate into Extended ROM using your preferred ROM tool
```
## Final Tips
1. **Backup first**: Always backup your Extended ROM before modification
2. **Test thoroughly**: Use loadmodule to test before permanent integration
3. **Mouse bypass**: Remember the left mouse button bypass for troubleshooting
4. **Check compatibility**: Verify with your specific system configuration
5. **Monitor memory**: Use `avail` to confirm proper operation
## License
[![License: GPL v2](https://img.shields.io/badge/License-GPL_v2-blue.svg)](https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html)

232
cflash/README.md
View File

@ -1,28 +1,232 @@
# CFLASH
A tool to program the Kickstart and IDE Flash of the CIDER board.
This tool allows you to program the Kick and IDE flash in-system even while it is currently in use
A tool to program the Kickstart and Extended ROM flash of the CIDER board for the Commodore CDTV.
This tool allows you to program the flash in-system even while it is currently in use.
## Usage examples
## What is CFLASH?
### Copying current kickstart and extended rom to flash
```cflash -C -c```
CFLASH is a tool that lets you update the firmware (ROM files) on your CIDER expansion board for the Commodore CDTV. It can update two types of firmware:
### Flashing IDE ROM
```cflash -I cider-ide.rom```
- **Kickstart ROM**: The main system firmware that boots your Amiga
- **Extended ROM**: Additional firmware for CDTV functionality
### Flashing a kickstart file to the second slot
```cflash -s 1 -k kick13.rom```
## Before You Start
### Getting Started
- CFLASH only programs the flash memory - it never touches your original system ROMs
- Make sure your CDTV has stable power during flashing
- **If you want to go back**: Simply switch off the kickflash DIP switch and reboot
### What You'll Need
- Your CIDER-equipped CDTV
- ROM files you want to flash (`.rom` files)
- The cflash program (available in [CIDER-Software.adf](https://github.com/LIV2/CIDER-Software/releases/latest))
- A CLI/terminal or Workbench to run commands
### Prerequisites
- CIDER expansion board must be properly installed
- ROM overlay should be switched off
- Bonus RAM must be disabled during flashing
## Common Tasks
### 1. Copy Your Current ROMs to Flash
To preserve what you currently have running:
```
cflash -c -C
```
This copies your current Kickstart and Extended ROMs from the system to flash.
### 2. Flash a New Kickstart ROM
To install a new Kickstart ROM file:
```
cflash -k kick31.rom
```
Replace `kick31.rom` with the actual filename of your Kickstart ROM.
**For dual Kickstart setups:**
- Flash to slot 0 (default): `cflash -s 0 -k kick31.rom`
- Flash to slot 1: `cflash -s 1 -k kick13.rom`
### 3. Flash an Extended ROM
To install a new Extended ROM file:
```
cflash -x cdtv-ext.rom
```
Replace `cdtv-ext.rom` with your Extended ROM filename.
### 4. Copy Current System ROMs to Flash
If you want to preserve your currently running ROMs to flash:
**Copy current Kickstart:**
```
cflash -c
```
**Copy current Extended ROM:**
```
cflash -C
```
**Copy both:**
```
cflash -c -C
```
### 5. Verify Flash Contents
To check if your flash matches a ROM file:
```
cflash -v -k kick31.rom
```
To verify against currently running ROMs:
```
cflash -v -c -C
```
### 6. Check Flash Device Information
To see what flash chip you have:
```
cflash -i
```
This displays the manufacturer and device ID of your flash chip.
## Advanced Operations
### Erasing Flash
**Erase Kickstart bank:**
```
cflash -e k
```
**Erase Extended ROM bank:**
```
cflash -e x
```
**Erase entire chip:**
```
cflash -E
```
### Skip Verification
```
cflash -V -k kick31.rom
```
The `-V` flag skips verification after programming (not recommended).
## Understanding Slots
The CIDER has dual Kickstart slots, allowing you to have two different Kickstart ROMs:
- **Slot 0**: Default slot
- **Slot 1**: Alternative slot
You can switch between them using CIDER's controls. Use `-s 0` or `-s 1` to specify which slot to program.
## ROM File Sizes
CFLASH supports these ROM sizes:
- **Kickstart**: 256KB, 512KB, or 1MB
- **Extended ROM**: 256KB or 512KB
## Troubleshooting
### "Flash is enabled" Message
If you see this message, cflash will automatically:
1. Copy ROMs to RAM
2. Switch to RAM mode
3. Proceed with flashing
This is normal - just wait for it to complete.
### "Bonus RAM must be disabled"
- Restart your system
- Make sure Bonus RAM is not activated before running cflash
### "Unknown Flash device"
- Check that your CIDER board is properly installed
- Verify you're using compatible flash chips
### Verification Failed
- Try flashing again
- Check that your ROM file isn't corrupted
- Ensure stable power during flashing
### Want to Use Original ROMs Again
- Switch off the kickflash DIP switch on your CIDER board
- Reboot your system (it will use the original ROMs)
- Your original ROMs are always safe and untouched
## Example Workflows
### Upgrading to Kickstart 3.1
```
# 1. Copy current setup to flash (optional)
cflash -c -C
# 2. Flash new Kickstart
cflash -k kick31.rom
# 3. Verify it worked
cflash -v -k kick31.rom
```
### Setting up Dual Kickstart
```
# Flash Kickstart 3.1 to slot 0
cflash -s 0 -k kick31.rom
# Flash Kickstart 1.3 to slot 1
cflash -s 1 -k kick13.rom
# Now you can switch between them using CIDER controls
```
### Complete ROM Update
```
# Update both ROM components
cflash -k kick31.rom
cflash -x cdtv-ext.rom
```
## Getting Help
If cflash won't run or you get errors, try running it without parameters to see the usage information:
```
cflash
```
This will show you all available options and their syntax.
## Command-line options
```
Usage: cflash [-iEvV] [-e k|x] [-c|-k <kickstart rom>] [-C|-x <extended rom>] [-I <ide rom>] -s [0|1]
Usage: cflash [-iEvV] [-e k|x] [-c|-k <kickstart rom>] [-C|-x <extended rom>] -s [0|1]
-c - Copy ROM to Flash.
-C - Copy Extended ROM to Flash.
-k <kickstart file> - Kickstart to Flash or verify.
-x <ext rom file> - Extended ROM to Flash or verify.
-i - Print Flash device id.
-I <ide rom> - Flash IDE ROM.
-e [k|x] - Erase [k]ickstart or e[x]t rom bank.
-E - Erase chip.
-v - Verify bank against file or ROM
@ -30,6 +234,12 @@ Usage: cflash [-iEvV] [-e k|x] [-c|-k <kickstart rom>] [-C|-x <extended rom>] [-
-s [0|1] - Select kickstart slot to work on.
```
## Final Tips
1. **Start simple**: Begin with copying your current ROMs to flash
2. **Keep ROM files**: Save copies of useful ROM files for future use
3. **Easy recovery**: If something doesn't work, just switch off the kickflash DIP switch and reboot
## License
[![License: GPL v2](https://img.shields.io/badge/License-GPL_v2-blue.svg)](https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html)