DICE Proprietary Functions and Extensions
This document lists DICE's proprietary functions and compiler extensions that are not part of the C/C++ standards but are available in DICE.
Startup Code Options
DICE provides several startup code options and files:
Startup Files
| File | Description | Usage |
|---|---|---|
| `DLIB:c.o` | DICE startup code | Default startup for most applications |
| `DLIB:x.o` | DICE section terminator code | Required for autoinit/autoexit sections |
| `DLIB:crt0.o` | Alternative C runtime startup | Used with some linker configurations |
Startup Options
| Option | Description | Effect |
|---|---|---|
| `-r` | Generate residentable executables | Places code in shared memory |
| `-nostartup` | Don't link startup code | Manual startup code required |
| `-nostdlib` | Don't link standard library | Minimal linking |
| `-static` | Static linking | Include all libraries statically |
| `-shared` | Shared library mode | Create shared library |
Application-Specific Startup Configurations
1. Minimal Amiga Command (Override _main for Maximum Performance)
Use Case: AmigaDOS commands that need maximum performance and minimal overhead, handling their own arguments with ReadArgs, workbench startup, and ctrl-c signals.
Startup Code: DLIB:c.o (default)
Entry Point: _main(int len, char *arg) (override _main for minimal overhead)
Compiler Options:
- -nostdlib (for minimal linking)
- -ms (for string constants in code section)
- -r (for residentable executables if needed)
Static Libraries:
- DLIB:cs.lib (small data model C library)
- DLIB:amigas13.lib or DLIB:amigas20.lib (Amiga library)
- DLIB:auto.lib (auto library opening)
Why Use This: Overriding _main instead of using main eliminates the overhead of stdio initialization, argument parsing, and C library setup. This can reduce executable size by 50% or more. You cannot use stdio functions (printf, fopen, etc.) or C memory allocation (malloc, etc.) when using _main.
Example:
`c
include <proto/exec.h>
include <proto/dos.h>
struct DosLibrary *DOSBase;
void _main(int len, char *arg)
{
if (DOSBase = (struct DosLibrary *)OpenLibrary("dos.library", 0)) {
Write(Output(), "Hello, world!\n", 14);
CloseLibrary((struct Library *)DOSBase);
}
_exit(0);
}
`
`bash
dcc -nostdlib -ms -r mycommand.c -o mycommand
`
2. Standard C Application with main(argc, argv)
Use Case: Standard C applications using main() with command line arguments and full stdio support.
Startup Code: DLIB:c.o (default)
Entry Point: main(int argc, char argv)
Compiler Options:
- -ms (for string constants in code section)
- -r (for residentable executables)
Static Libraries:
- DLIB:cs.lib (small data model C library)
- DLIB:ms.lib (math library if needed)
- DLIB:amigas13.lib or DLIB:amigas20.lib (Amiga library)
- DLIB:auto.lib (auto library opening)
Why Use This: Standard configuration with full stdio support, argument parsing, and C library functionality. The startup code automatically opens required Amiga libraries and sets up the C runtime environment.
Example:
`bash
dcc -ms -r myapp.c -o myapp
`
3. Heavyweight Unix/POSIX/Linux Command Port
Use Case: Ports of Unix/POSIX/Linux commands requiring extensive standard library support.
Startup Code: DLIB:c.o (default)
Entry Point: main(int argc, char argv)
Compiler Options:
- -ms (for string constants in code section)
- -r (for residentable executables)
- -mD (large data model if needed for >64KB data)
Static Libraries:
- DLIB:cs.lib (small data model C library)
- DLIB:ms.lib (math library)
- DLIB:amigas13.lib or DLIB:amigas20.lib (Amiga library)
- DLIB:auto.lib (auto library opening)
- Additional POSIX libraries as needed
Why Use This: Full-featured configuration for complex applications that need all standard library features, proper argument parsing, and extensive POSIX compatibility.
Example:
`bash
dcc -ms -r -mD myunixport.c -o myunixport
`
4. Workbench Application
Use Case: Amiga Workbench applications that need to handle workbench startup messages.
Startup Code: DLIB:c.o (default)
Entry Point: wbmain(struct WBStartup *wbs) (workbench entry point)
Compiler Options:
- -ms (for string constants in code section)
- -r (for residentable executables)
Why Use This: For Workbench applications that need to process workbench startup messages. The wbmain function is called by the startup code when the program is launched from Workbench.
Example:
`c
include <startup.h>
int wbmain(struct WBStartup *wbs)
{
// Process workbench startup message
// Your application code here
return 0;
}
`
Startup Code Features
- Auto library opening: DICE startup code automatically opens Amiga libraries when base variables are referenced but not declared. This includes:
- dos.library - When DOSBase is referenced
- intuition.library - When IntuitionBase is referenced
- graphics.library - When GfxBase is referenced
- layers.library - When LayersBase is referenced
- math.library - When MathBase is referenced
- mathieeedoubbas.library - When MathIeeeDoubBasBase is referenced
- mathieeedoubtrans.library - When MathIeeeDoubTransBase is referenced
- mathieeesingbas.library - When MathIeeeSingBasBase is referenced
- mathieeesingtrans.library - When MathIeeeSingTransBase is referenced
- mathtrans.library - When MathTransBase is referenced
- utility.library - When UtilityBase is referenced
- timer.device - When TimerBase is referenced
- translator.library - When TranslatorBase is referenced
- rexxsyslib.library - When RexxSysBase is referenced
- asl.library - When AslBase is referenced
- diskfont.library - When DiskfontBase is referenced
- gadtools.library - When GadToolsBase is referenced
- icon.library - When IconBase is referenced
- fifo.library - When FifoBase is referenced
- Stack setup: Initializes stack and stack pointer
- BSS clearing: Zeroes uninitialized data segments
- Autoinit sections: Calls __autoinit functions after libraries are opened, before _main
- Autoexit sections: Calls __autoexit functions before libraries are closed, after _exit
- Environment setup: Sets up environment variables and arguments
- Signal handling: Initializes signal handlers and clears Control-C signal
- Floating point: Sets up floating point environment
- Residentable executables: Support for shared memory programs with -r option
- Entry point flexibility: DICE provides multiple entry points for different use cases:
- main(int argc, char argv): Standard C entry point with full stdio support
- _main(int len, char *arg): Low-level entry point for minimal overhead (no stdio)
- wbmain(struct WBStartup *wbs): Workbench entry point for GUI applications
Autoinit/Autoexit Sections
DICE provides special sections for automatic initialization and cleanup:
- __autoinit functions: Called after libraries are opened, before _main
- __autoexit functions: Called before libraries are closed, after _exit
- Cannot make C library calls: These functions cannot call malloc, fopen, etc.
- Variable placement: __autoinit variables are placed in alternate sections
Compiler Extensions
Storage Qualifiers
| Extension | Description | Availability |
|---|---|---|
| `volatile` | Force auto variables to NOT be placed in registers | All |
| `const` | Place data items in code section (with -ms/-mS options) | All |
| `__autoinit` | Cause subroutine to run automatically before _main | All |
| `__autoexit` | Cause subroutine to run automatically before _exit | All |
| `__interrupt` | Interrupt handler (NOT AMIGA COMPATIBLE) | All |
| `__chip` | Place storage in CHIP memory | Registered users |
| `__far` | Use absolute-long addressing mode | All |
| `__near` | Use A4-relative addressing mode | All |
| `__aligned` | Align storage on longword boundary | All |
| `__unaligned` | Allow byte-aligned structures | All |
| `__geta4` | Setup A4 data base pointer | Registered users |
| `__shared` | Place storage in code section (shared between instances) | All |
| `__regargs` | Specify function takes registered arguments | All |
| `__stkargs` | Specify function takes stack-based arguments | All |
| `__dynamic` | Dynamic linking at runtime | Registered users |
| `__noprof` | Disable profiling for a procedure | All |
| `__D0-__D7` | Explicit register specification for arguments | Registered users |
| `__A0-__A7` | Explicit register specification for arguments | Registered users |
Auto Library Opening
DICE automatically opens Amiga libraries when their base variables are referenced but not declared. This includes:
- dos.library - When DOSBase is referenced
- intuition.library - When IntuitionBase is referenced
- graphics.library - When GfxBase is referenced
- layers.library - When LayersBase is referenced
- math.library - When MathBase is referenced
- mathieeedoubbas.library - When MathIeeeDoubBasBase is referenced
- mathieeedoubtrans.library - When MathIeeeDoubTransBase is referenced
- mathieeesingbas.library - When MathIeeeSingBasBase is referenced
- mathieeesingtrans.library - When MathIeeeSingTransBase is referenced
- mathtrans.library - When MathTransBase is referenced
- utility.library - When UtilityBase is referenced
- timer.device - When TimerBase is referenced
- translator.library - When TranslatorBase is referenced
- rexxsyslib.library - When RexxSysBase is referenced
- asl.library - When AslBase is referenced
- diskfont.library - When DiskfontBase is referenced
- gadtools.library - When GadToolsBase is referenced
- icon.library - When IconBase is referenced
- fifo.library - When FifoBase is referenced
Data Models
DICE supports multiple data models:
- Small Data Model (-md) - Default, uses A4-relative addressing
- Large Data Model (-mD) - Uses absolute-long addressing
- Register Arguments (-mr/-mR/-mRR) - Pass arguments in registers
Compiler Options
| Option | Description |
|---|---|
| `-1.3` | Use Amiga 1.3 includes and libraries |
| `-2.0` | Use Amiga 2.0 includes and libraries |
| `-r` | Generate residentable executables |
| `-ms` | Make string constants const |
| `-mS` | Use pc-relative addressing for const items |
| `-md` | Small data model (default) |
| `-mD` | Large data model |
| `-mr` | Register arguments |
| `-mR` | Register arguments (extended) |
| `-mRR` | Register arguments (full) |
| `-prof` | Enable profiling |
| `-a` | Generate assembly output |
Library Organization
Include Directories
- DINCLUDE: - Top-level includes (stdio.h, etc.)
- DINCLUDE:Amiga13/ - Amiga 1.3 includes
- DINCLUDE:Amiga20/ - Amiga 2.0 includes
Library Files
- DLIB:cs.lib - Main C library (small data model)
- DLIB:ms.lib - Math library
- DLIB:auto.lib - Auto library opening
- DLIB:amigas13.lib - Amiga 1.3 library (small data model)
- DLIB:amigas20.lib - Amiga 2.0 library (small data model)
- DLIB:c.o - Startup module
- DLIB:x.o - Terminator module
Special Features
Residentable Executables
DICE can generate residentable executables using the -r option, which:
- Places code in shared memory
- Reduces memory usage for multiple instances
- Requires small data model and const qualifiers
Autoinit/Autoexit Sections
Functions marked with __autoinit or __autoexit are called automatically:
- __autoinit functions run after libraries are opened, before _main
- __autoexit functions run before libraries are closed, after _exit
- Cannot make C library calls (malloc, fopen, etc.)
Dynamic Linking
Registered users can use __dynamic for runtime linking of routines and variables.
Profiling Support
DICE includes profiling support with the -prof option and __noprof qualifier.
Summary
DICE provides extensive Amiga-specific functionality beyond standard C:
- Auto library management - Automatic opening/closing of Amiga libraries
- Memory model flexibility - Support for different data models and memory placement
- Amiga integration - Deep integration with Amiga hardware and software
- Compiler extensions - Rich set of storage qualifiers and compiler options
- Residentable executables - Support for shared memory programs
- 680x0 optimization - Register usage and addressing mode control
- Flexible startup options - Multiple startup configurations with autoinit/autoexit support
These features make DICE a powerful development environment for Amiga systems, providing both standard C compliance and extensive platform-specific capabilities.