arch/.unmaintained/amiga/boot/arosboot.doc

   1 $VER: arosboot.doc 41.7 (29.3.97)
   2
   3 *****************************************************************************
   4                           AROS Native Boot Program
   5
   6                                  Part of the
   7                            AROS Research OS (AROS)
   8
   9                                  Written by
  10                     Lennard voor den Dag <ldp@xs4all.nl>
  11
  12                         Last revised: March 29, 1997
  13 *****************************************************************************
  14
  15
  16 =============================================================================
  17 0. Contents
  18 -----------------------------------------------------------------------------
  19
  20 0. Contents
  21 1. Introduction
  22 2. Requirements
  23 3. Installation
  24 4. Usage
  25 5. Config File Usage
  26 6. Technical Information
  27 7. WhoWhatWhere
  28 8. Legalese
  29 9. History
  30
  31
  32 =============================================================================
  33 1. Introduction
  34 -----------------------------------------------------------------------------
  35
  36 This document describes arosboot, the program used to load and install
  37 AROS modules on the Native Amiga.
  38
  39
  40 =============================================================================
  41 2. Requirements
  42 -----------------------------------------------------------------------------
  43
  44 Arosboot requires a 68020 or better processor and Kickstart V37 (Release 2.04)
  45 or better.
  46
  47
  48 =============================================================================
  49 3. Installation
  50 -----------------------------------------------------------------------------
  51
  52 If you have unpacked the archive, you will have a directory "AROS" where
  53 everything you need can be found.
  54
  55   AROS/
  56   AROS/arosboot
  57   AROS/arosboot.config
  58   AROS/os/               <== main AROS modules live here
  59   AROS/tools/            <== various utilities
  60
  61 CD into this directory and you're ready to run "arosboot".
  62
  63
  64 =============================================================================
  65 4. Usage
  66 -----------------------------------------------------------------------------
  67
  68 arosboot CONFIGFILE,CHIP/S,FAST/S,KICK/S,LOCAL/S,CLEAR/S,CO=CLEARONLY/S,
  69          RESET/S,DEBUG/S,SIM=SIMULATE/S,FORCE/S,QUIET/S
  70
  71   Configfile
  72
  73     Config file to use, default is "arosboot.config".
  74
  75   Chip/Fast/Kick/Local
  76
  77     Force the modules to a particular type of memory. If your original
  78     Kickstart is V37 (Release 2), the default is chip memory. If you have
  79     fast memory on your motherboard, you can specify the option "fast" to
  80     force the modules to that fastmem. On Kickstart V39/V40 (Release 3/3.1)
  81     the default is "kick" memory. If you specify more than one memory
  82     type, the order of precedence is kick->local->fast->chip.
  83
  84   Clear
  85
  86     Clear the reset vectors before installing new modules. Use this if you
  87     have already loaded AROS and want to load new modules, or else there will
  88     be 2 copies of AROS modules in memory.
  89
  90   Clearonly  : only clear reset vectors and exit
  91
  92     Only clear the reset vectors and exit. Use this so AROS will not come up
  93     during the next reset. Use it together with the reset option to reset the
  94     machine right now.
  95
  96   Reset
  97
  98     After arosboot has installed modules, the computer has to be reset to
  99     activate these modules. You can do that by hand or use this option to let
 100     arosboot reset the machine by itself. There will be a 2 second delay to
 101     give diskaccess a chance to finish.
 102
 103   Debug
 104
 105     Output debugging information. Include this debug output in a bug report,
 106     if you suspect there are problems with arosboot. This setting will
 107     override the quiet setting.
 108
 109   Simulate
 110
 111     Simulate loading, do not actually install modules. This will read the
 112     config file and load the modules into memory, but will immediately
 113     unload them. You can use this to test your installation.
 114
 115   Force
 116
 117     Normally, arosboot will not install modules if it finds that AROS modules
 118     have already been installed in the system. Use force to override this so
 119     new modules will be loaded. Don't forget to specify "clear" to delete the
 120     old modules from memory.
 121
 122   Quiet
 123
 124     Be quiet.
 125
 126
 127 All file operations (reading the config file and loading the modules) will be
 128 done relative to the directory where arosboot itself is located. This means
 129 you don't have to CD into arosboot's directory but can just run arosboot from
 130 anywhere and it will behave as if you CD'd into it's directory yourself.
 131
 132
 133 =============================================================================
 134 5. Config File Usage
 135 -----------------------------------------------------------------------------
 136
 137 Example config file:
 138
 139 ----8<----8<----
 140   ;
 141   ; arosboot config file
 142   ;
 143   ;
 144   MODULE os/exec.strap
 145   MODULE os/alert.hook
 146   MODULE os/utility.library
 147   ;
 148   FUNCTION -72  os/exec.strap   ON      ; InitCode
 149   FUNCTION -84  os/exec.strap   ON      ; MakeLibrary
 150   FUNCTION -90  os/exec.strap   OFF     ; MakeFunctions
 151 ----8<----8<----
 152
 153 MODULE lines
 154
 155   Template: MODULE/K/A
 156
 157   These lines contain the names (including (relative) paths) of the modules
 158   to install.
 159
 160   The MODULE keyword is compulsory.
 161
 162 FUNCTION lines
 163
 164   Template: FUNCTION/N/K/A,MODULE/A,ON/S,OFF/S
 165
 166   With these lines you can specify which functions in a module should be
 167   turned on or off. Currently this is only possible for the "exec.strap"
 168   module. If you turn a function off, the original AmigaOS function will
 169   be used instead. You can use this to selectively disable certain functions,
 170   to aid in debugging and more specific bug reports.
 171
 172   The FUNCTION keyword is compulsory. The MODULE keyword can be omitted.
 173   Both arguments must be specified.
 174
 175   If you don't specify ON or OFF, the function will be turned on. If you
 176   specify both ON and OFF, the function will be turned on.
 177
 178   Be very careful if you disable functions. Many functions are part of a
 179   constructor/deconstructor pair. E.g. if you disable AllocVec, you also
 180   _must_ disable FreeVec. Experience with the AmigaOS API is recommended
 181   before you start turning functions on/off. If you are unsure about
 182   something, you can always ask for our help.
 183
 184 COMMENTS
 185
 186   Start comment lines with a ; character.
 187
 188
 189 =============================================================================
 190 6. Technical Information
 191 -----------------------------------------------------------------------------
 192
 193 68020+ version
 194 --------------
 195 There is no 68000 version at the moment, because AROS itself is only compiled
 196 for 68020 or better processors. This way you can never inadvertently install
 197 AROS modules on systems with a 68000/68010. 68000 support will be added in the
 198 future.
 199
 200 arosboot and memory
 201 -------------------
 202 AROS modules are loaded into RAM. The memory they are loaded in has to be
 203 available very early during the reboot. This limits the types of memory that
 204 can be used. On Kickstart V39 and above, exec recognizes all memory available
 205 for this process by marking it with a special flag, the "kickmemory" flag. On
 206 this Kickstart, arosboot will load memory into this kickmemory by default.
 207
 208 On Kickstart V37, the exec doesn't have this flag, so arosboot has to guess
 209 which memory it can use for the modules. Chip memory is one region of memory
 210 that is guaranteed to always be available early in the reset procedure.
 211 Arosboot uses chipmemory by default on this Kickstart version. Fast memory
 212 on expansion cards is not guaranteed to be available early in the reset
 213 procedure, but fast memory on the motherboard generally is. If you have fast
 214 memory on your motherboard you can force AROS modules to be loaded into
 215 this fast memory by specifying the "fast" option. If you have fast memory on
 216 both the motherboard and expansion cards, you can try the "local" flag. This
 217 will load the modules in "local" memory, which is generally the fast memory
 218 on the motherboard, and the chip memory, with a preference for fast memory.
 219
 220 arosboot and system patches
 221 ---------------------------
 222 If you use system patches like FastExec, MCP, SystemPrefs, or similar, you
 223 may find that there are problems with installation of AROS modules. Such
 224 utilities can move certain system structures to fast memory, but they will
 225 only do that after the system is up and running. AROS modules will be started
 226 very early in the reset procedure, before these utilities have had a chance to
 227 perform their memory swizzling. If such a utility relocates some system
 228 structure to fast memory, and the OS can't find that structure during the
 229 reset, it will construct a new structure. If this happens, all resetproof
 230 programs, such as AROS modules, will be purged from memory. More specifically,
 231 a new execbase structure will be built, which has empty reset vectors, so
 232 resetproof modules will be forgotten.
 233
 234 If you experience problems (such as AROS disappearing during a reset), try
 235 turning off options that relocate certain things to fast memory. Examples of
 236 this are: SSP to fastmem, Exec to fastmem, Expansion to fastmem, Interrupts
 237 to fastmem, etc. Try turning all of these off, and if AROS works, turn them
 238 on one at a time to see which option is incompatible with AROS.
 239
 240 arosboot utilities
 241 ------------------
 242 Two utilities are included with arosboot:
 243
 244 Showvecs shows a report of everything that lives at the system reset vectors
 245 used by arosboot. If the checksum of these vectors is correct, an extended
 246 report is printed, else only the vectors themselves are printed. If arosboot
 247 is successful, you can see the new contents of the vectors even before a
 248 reset.
 249
 250 Printresmodules shows all Resident Modules that are currently in the System
 251 Resident Module List. Newly loaded AROS modules will only show up in this list
 252 after a system reset. To find AROS modules, look for modules that are in RAM
 253 (they have an address outside of the $f80000-$ffffff range), and the
 254 "arosboot.cookie" module at priority -120.
 255
 256
 257 =============================================================================
 258 7. WhoWhatWhere
 259 -----------------------------------------------------------------------------
 260
 261 More information on these pages on the WorldWideWait:
 262
 263     http://www.aros.org/
 264     http://www.xs4all.nl/~ldp/aros/ (AROS for Amiga)
 265
 266 If you have FTP, you can also get the most recent version from:
 267
 268     ftp://ftp.aros.org/pub/aros/
 269
 270 You can use these EMail addresses to send bug reports:
 271
 272     aros-bugs@aros.org
 273     aros-linux-bugs@aros.org
 274     aros-amiga-bugs@aros.org
 275
 276
 277 =============================================================================
 278 8. Legalese
 279 -----------------------------------------------------------------------------
 280
 281 This software is subject to the "Standard Amiga FD-Software Copyright Note".
 282 It is MAILWARE as defined in paragraph 4b.
 283
 284 If you like it and use it regularly please send a message to the
 285 following address:
 286
 287     Aaron "Optimizer" Digulla
 288     Haldenweg 5
 289     78464 Konstanz
 290     Germany
 291
 292     EMail: digulla@aros.org
 293
 294 For more information please read "AFD-COPYRIGHT" (Version 1 or higher).
 295
 296
 297 =============================================================================
 298 9. History
 299 -----------------------------------------------------------------------------
 300
 301 41.8
 302 - Fixed bug that could cause reset vector corruption (mementry for the
 303   KickTagPtr was 4 bytes short).
 304
 305 41.7
 306 - Do all file operations relative to PROGDIR:. This applies to the config
 307   file itself as well as to modules. This removes the need to CD into the
 308   directory where arosboot lives before running arosboot.
 309
 310 41.6
 311 - Major overhaul.
 312 - New command line options.
 313 - Extended config file format.
 314 - Renamed to "arosboot".
 315 - Docs.
 316
 317 41.5
 318 - Back out 41.4 change of falling back to MEMF_LOCAL. It turned out to worsen
 319   the situation when using FastExec with the "local" option. Still have the
 320   "-l" option in boot to force AROS to MEMF_LOCAL.
 321
 322 41.4
 323 - No longer fall back to MEMF_CHIP on kick V37, but to MEMF_LOCAL. This
 324   may also benefit FastExec users.
 325
 326 41.3
 327 - First public release.
 328 - Fail if option not recognized (e.g. "boot 0x" instead of "boot -x").
 329
 330
 331 =============================================================================
 332                                      END
 333 =============================================================================