AmigaOS Documentation Wiki - User contributions [en]

Workbench/Prefs/Workbench

2023-11-08T19:27:51Z

Brian Deneen: Corrected "and /" after mouse pointer.

Workbench is the unique Graphical User Interface (GUI) of AmigaOS. It provides one of the means of interaction with AmigaOS and is typically the first screen that is displayed when AmigaOS is finished booting. It is composed of a menu system that is accessed by clicking the right mouse button or pointing the mouse pointer at the top of the screen and clicking the right mouse button; icons that are initially visible on the screen and can be displayed by double-clicking the individual image with the left mouse button; and an optional docking system that can be used to organize and control the look and feel of the icon display.

Workbench Preferences allows the user to configure and control this GUI and the programs to which it refers. Currently (2023), the Preferences are found by pointing the mouse into the main area of the Workbench and clicking and holding the right mouse button. A menu panel then appears which shows 11 choices, one of which is Workbench Preferences. Hold down the right mouse button and hover over the Preferences menu item to access the 32 programs that determine, in large part, how the Workbench is presented and functions.

Workbench/Prefs/Workbench

2023-11-07T09:30:20Z

Brian Deneen: Added this item describing the Workbench Preferences menu for new users.

Workbench is the unique Graphical User Interface (GUI) of AmigaOS. It provides one of the means of interaction with AmigaOS and is typically the first screen that is displayed when AmigaOS is finished booting. It is composed of a menu system that is accessed by clicking the right mouse button and / or pointing the mouse pointer at the top of the screen and clicking the right mouse button; icons that are initially visible on the screen and can be displayed by double-clicking the individual image with the left mouse button; and an optional docking system that can be used to organize and control the look and feel of the icon display.

Workbench Preferences allows the user to configure and control this GUI and the programs to which it refers. Currently (2023), the Preferences are found by pointing the mouse into the main area of the Workbench and clicking and holding the right mouse button. A menu panel then appears which shows 11 choices, one of which is Workbench Preferences. Hold down the right mouse button and hover over the Preferences menu item to access the 32 programs that determine, in large part, how the Workbench is presented and functions.

Glossary

2023-11-07T09:11:54Z

Brian Deneen: Added "Workbench" as a glossary item for new users.

Amiga 25 Years

2023-11-07T09:09:50Z

Brian Deneen: Added period after "2010", capitalized the following "The."

'Amiga 25 Years' is a Video produced by one of the lead developers at Hyperion Entertainment showcasing 25 years of Amiga development.

The video shows the development of AmigaOS from its birth up to 2010. The animation in this video was realised using the open source software solution Gource.

'''Watch the Video on YouTube:'''

http://www.youtube.com/watch?v=5NJ1TlQwLTs

UserDoc:How AmigaOS Works

2023-10-03T15:51:28Z

Brian Deneen: /* Removing the JIT Emulator */ Removed excess "the" occurrences and changed punctuation for smoother reading. Please see "Show Changes" page.

As already mentioned, AmigaOS was a pioneer in the early days of personal computing in delivering sophistication that contemporary systems could only have dreamt of and pretended to offer. Today, AmigaOS continues to offer a straightforward elegance that seems to be overlooked in the development of other platforms. Thanks to the concepts behind AmigaOS, the system is easy to understand and to use by everyone.

In this page we will explore all these concepts of AmigaOS. Also you will learn here the naming of all parts of the system.

= Introduction =

AmigaOS is made of different components which are either mandatory (i.e., AmigaOS will not work without them) or components the user can choose to use or not. All these components can have one or mutiple interfaces a user or a developer can use to operate with the components and through them to control the operating system.

= The most important components =

== Exec, the AmigaOS kernel ==

Exec is the kernel of AmigaOS. It is the component that pilots all other components. It is responsible for running programs, dealing with computer memory and managing low-level resources that programs may need. In other words, it organises everything to make the operating system run.

It is made of different parts that cannot be moved outside the kernel: the scheduler, the memory pager and the 68k interpretive emulator.

== AmigaDOS: the underlying system ==

The word "DOS" was originally an acronym for "Disk Operating System". Some say it should be "Disk Based Operating System" as it does a lot more than operate a disk and that it was really an operating system based (stored) on disks. Some say it should be "Device Operating System".

The whole AmigaDOS system includes things such as:

* A set of commands that can be used in the Shell window and elsewhere.
* A system for saving data to disk and retrieving it from disk.
* A system for filing data on disks.
* An interface for peripherals such as keyboards, monitors, printers, etc.
* A method of running programs
* A multitasking system for running more than one program at a time.
* etc. etc. etc.

Read the [[AmigaDOS manual]] to understand and learn everything about AmigaDOS.

== The Graphics library ==

The Graphics library handles every low level graphic operation like designing pixels on the monitor, creating graphic elements (bobs, sprites) and also writing text output.

== Intuition ==

The Intuition library is responsible for every graphical object: windows, screens, gadgets, mouse pointers... It lies between any graphic program and the graphics library.

== The Workbench ==

The Workbench is the graphical place where you will manage your computer and all your files. The name was chosen because the user will use tools to create and work with the computer.

[[File:Wb.png|320px]]

== The Shell ==

While some people prefer to control the operating system using their mouse, others prefer using the keyboard. The shell is a text based window when you can type commands to execute actions in the operating system. In the shell the commands will display the results of their execution.

== ARexx - inter-program communication by scripting ==

The ARexx scripting language can be used to operate the Workbench and other Amiga applications from a script containing ARexx commands. This is extremely useful in performing repetitive tasks or doing what the controlled application was not even designed to do.
After a learning curve, everybody can use ARexx as it is built into the system. The scripts can be executed immediately like any other tool.

= How is my data stored? =
== Files ==
=== Executable files ===
Programs you can start are stored in executable files. They contain binary code directly understandable by the computer. They are files with an executable bit, a flag that shows AmigaOS that such file will do something when started.
An example is a music player. When you start this executable, the player opens and you can start playing music files.

AmigaOS can run two different kinds of executable files: the AmigaOS native programs made for the PowerPC processor and programs created for the Motorola 68k processors. The latter are executed inside an emulation that translates them into PowerPC code.

==== Scripts ====

Scripts are text files containing a list of commands. They are not strictly executables like ''binary code'' files but they can be executed by AmigaOS as if they were.
This is the case with AmigaDOS and ARexx scripts. These files need to have the executable and script bits set.

=== Data files ===
Files that are not executable are data files. These contain data that will be manipulated by programs. Some examples are a music file, a video file or a text document.

== Directories/Drawers ==
In order to organise things, files are grouped together. We create "directories" which are like drawers of a cabinet to store different files of the same kind, for example.
Often the name ''directory'' is used when talking about a directory which is stored on a disk. The graphical interface of AmigaOS is called "Workbench," and directories are often called ''drawers''.

Note: directories are often called ''folders'' on other systems. The terms "directory," "drawer" and "folder" are synonymous.

== Disks, partitions and volumes ==
=== Disks ===
Disks are storage media you can purchase at a computer store. We use them to store our files. They can be internal hard disks, external hard drives, USB interface devices (i.e., SD cards, CF cards, "flash" drives, etc.), and floppy disk drives.

=== Partitions ===
A disk is often very big and many users prefer to make it more organised. This is done by virtually splitting the disk into several smaller parts. This operation is known as creating partitions on a disk.

[[File:Partitions.png|Small part of Media Toolbox showing different partitions on the harddisk]]

On this screenshot you can see one harddisk with many partitions. Each color corresponds to a different filesystem which defines how data is stored. Also, you can see a greyed area which is a blank area on the disk (i.e., no partition is defined at this position). Several different file systems can be used on the same Amiga drive. It's your choice.

=== Volumes ===
A partition is a physical area on a disk. To access it with AmigaOS we must read the physical data off the partition. To make it easier AmigaOS uses the concept of volumes. These are virtual representations of a partition. The volumes have a name so AmigaOS and therefore the user can access all files/directories stored on it in a very practical way: just by using its name.

Volume names can refer to either a physical or virtual named space. See the autodoc section for the ASSIGN command in the C: directory as well as the MOUNT command which provides more information on naming and the concept of volumes.

= How to identify files/directories =

== On the Workbench ==

The Workbench being graphical, a lot of things are understandable just by looking at them. That's why icons are often enough to understand what kind of object it represents: a file, a directory, a disk...

In case you have a doubt, just look at the information on an icon. The Workbench will tell you the type of the object. It is displayed next to its name.

== In a shell ==

In a shell the '''list''' command can be used to see if an object is a file or a directory.

[[File:Files-dirs-in-shell.png|The '''list''' command shows a file of 925678 bytes and two directories]]

A file will be displayed with its size, whereas a directory will be displayed with the text '''Dir''' next to it.

Also, as you can see on the screenshot, the list command displays other characteristics on these 3 items: the protection bits and the date they were updated the last time. The command also sums up what it just listed.

= All AmigaOS components =

AmigaOS is made of components that are needed as soon as the system starts or later when the user or the system needs them.

== Kickstart modules ==

These components are the heart of AmigaOS. Their duty is to draw graphics, to handle discs or to handle all reads/writes to files. Also one of them is the AmigaOS kernel which is a kind of director handling the work of all other components.
These Kickstart modules are loaded at the beginning of the operating system boot process (read [[UserDoc:How_AmigaOS_Works#AmigaOS_boot_procedure|here]]). You can find them all in the '''Kickstart''' directory on the system volume. Here is a list:

=== Mandatory modules ===

The following modules are required in any AmigaOS system. Without one of these, the system will not start.

* kernel - The kernel works like the conductor of an orchestra. Its job is to make everything work together. It creates processes, handles memory usage, defines the way other components will access peripherals...etc. Note that the AmigaOS kernel is not based on any other kernel. It is a unique kernel that has existed since 1983.
* loader - this component handles the loading of all other kickstart modules
* battclock.resource.kmod - this module handles reading/writing the battery backed up clock which is used on all computers to keep the date and time
* bootimage - this is the boot picture. It is displayed during the start sequence of AmigaOS
* bootmenu.kmod - this component handles the Early Startup Menu the user can employ to define some settings before starting AmigaOS
* con-handler.kmod - it directs read and write requests to the console window, to a serial AUX: device or any other supported interface
* console.device.kmod - it opens a window and reads/writes text to and from that window
* diskboot.kmod - handles the booting of AmigaOS from a supported disk
* diskboot.config - this is a text file experienced users can modify to change the boot behaviour of AmigaOS
* dos.library.kmod - this module is a collection of functions that any program can use to perform actions on disks, files and directories
* elf.library.kmod - handles the loading of executable programs
* env-handler.kmod - handles the reads/writes of environment variables
* FileSystem.resource.kmod - handles access to the different filesystems
* gadtools.library.kmod - a collection of functions used to create all graphic objects like gadgets, sliders, menus...
* gameport.device.kmod - handles the reads/writes of game pads and joysticks
* graphics.library.kmod - a collection of functions used to draw graphic elements on the monitor
* hunk.library.kmod - a set of functions to read a data stream into memory
* input.device.kmod - handles input events like keyboard events or mouse clicks
* intuition.library.kmod - a collection of functions to create and handle all graphic elements (screens, windows, the mouse pointer...)
* layers.library.kmod - set of functions to be used to handle different layers in graphic operations
* keyboard.device.kmod - driver for the keyboard
* keymap.library.kmod - functions to handle different keymaps
* newlib.library.kmod - collection of functions to perform memory operations (allocating memory, copying memory areas... )
* nonvolatile.library.kmod - provides a simple means for an application developer to manage nonvolatile storage
* nvram.resource.kmod - handles the reads/writes to the NVRAM chip present on many AmigaOS computers
* PCIGraphics.card - driver that supports the use of different graphic cards
* ram-handler.kmod - functions that handle the '''Ram disk:'''.
* ramdrive.device.kmod - device that allows the usage of the ramdrive device '''RAD:''' disk
* ramlib.kmod - loads disk based libraries and devices for exec.library
* rtg.library - library of functions to perform low level graphic operations on graphics cards
* shell.kmod - the AmigaOS command line interface
* strap.kmod - module that handles booting on different disk devices
* timer.device.kmod - driver to give access to timing functions

=== Filesystem support ===

These kickstart modules can be loaded optionally. If you want to use a particular filesystem on your disk partitions, you need to load the corresponding filesystem module.

* CDFileSystem - handles the CD-ROM disks with data stored in different formats: ISO9660, HFS...
* SmartFilesystem - allows the usage of partitions in SFS0 and SFS2 layouts
* JXFileSystem - allows the usage of partitions in JXFS layout (now obsolescent)
* FastFileSystem - allows the usage of partitions in FFS and FFS2 layouts
* NGFileSystem - an experimental file system designed to gradually replace the FastFileSystem
* diskcache.library.kmod - component required by the SmartFileSystem and JXFileSystem modules

=== Hardware drivers ===

==== Graphic cards drivers ====

* 3dfxVoodoo.chip
* 3DLabsPermedia2.chip
* ATIRadeon.chip
* RadeonHD.chip
* siliconmotion502.chip

==== Disk drivers ====

Each of these drivers allows the use of disks connected to a disk controller. These files are named after the controller they support. As an example, the '''sii3114ide.device.kmod''' allows the use of disks connected to a '''Silicon Image SiI3114''' controller chip.

* it8212ide.device.kmod
* lsi53c8xx.device.kmod
* sam460sata.device.kmod
* sii3112ide.device.kmod
* sii3512ide.device.kmod
* sii3114ide.device.kmod
* sii0680ide.device.kmod
* sii3132ide.device.kmod

==== USB drivers ====

* hub.usbfd
* usbsys.device
* usbresource.library
* ehci.usbhcd
* ohci.usbhcd
* uhci.usbhcd
* massstorage.usbfd

==== Other drivers ====

* bootkeyboard.usbfd - allows a USB keyboard to be used even before the USB stack is loaded
* bootmouse.usbfd - allows a USB mouse to be used even before the USB stack is loaded
* fpga.resource.kmod - allows to use the FPGA components which are present on some Amiga computers
* i2c.resource.kmod - allows to use the i2c interface present on some Amiga computers
* xena.resource.kmod - provides access to the Xena chip on the AmigaOne X1000

==== Misc modules ====

* petunia.library.kmod - this module contains the Just-In-Time emulator that allows AmigaOS to run programs made for the Motorola 68k processor

== Control of the Kickstart ==

The Kickstart/ drawer contains an ASCII file called "Kicklayout". This file lists all the modules that must be loaded from the system volume during the boot process. It is read by the boot loaders "SLB" or "amigaboot".

The Kicklayout file consists of a number of configurations, each of which describes a set of Kickstart modules. Each configuration has a label and the various configurations are listed by label on the boot screen. The user may elect to load the default configuration or to select any one of the other configurations. Often a developer will have several configurations in his/her Kicklayout file, some of which may be experimental, while the default is a "known good" configuration to which (s)he can fall back.

You can edit the Kicklayout file using Notepad or any other ASCII editor. You are strongly advised to leave the original configuration unchanged (as a fall-back) and to add new configurations at the end of the file, each with its own label. That way you can still recover if you make a mistake while editing.

<nowiki>; Configuration name
LABEL MainSystem
; Exec name
EXEC Kickstart/loader.of
;
; PPC native modules
;
MODULE Kickstart/kernel
;
MODULE Kickstart/FastFileSystem
MODULE Kickstart/CDFileSystem
MODULE Kickstart/NGFileSystem
;
(etc)</nowiki>

Note that lines that start with a semicolon (";") are treated as comments and are ignored. Each configuration must start with a "LABEL" keyword and should be separated from the previous configuration by a blank line. The blank line signifies "Stop loading here".

Each module to be loaded is defined by the "MODULE" keyword, followed by the path and file name. You can use any path ''on the system volume'', so you could have two or more drawers containing Kickstart modules and address them independently if you so wished. You can not refer to modules on other volumes, since they have not been mounted by DOS (which does not exist yet) and only the system volume is available at this early stage.

=== Selecting the Default Configuration ===

You can specify in the NVRAM the label of the default configuration in the Kicklayout. For instance, if your default configuration is called "MainSystem", the LABEL line will look like this:

LABEL MainSystem

You can define an NVRAM variable called "boot_config" using U-Boot, CFE or the "nvsetvar" tool. Simply type:

nvsetvar boot_config "MainSystem"

[Note that nvsetvar may be inhibited from writing to the NVRAM on some systems, in which case you will have to use U-Boot or CFE to set the variable]

If you do not specify a default configuration with the "boot_config" variable, the boot loader will default to the first configuration in the Kicklayout.

== System components ==

[[File:Workbench_directory_listing.png|frame|right|List of directories and files present at the root of any AmigaOS system]]

Beside the kickstart modules, AmigaOS uses many different components that can be loaded only when needed. These files are stored in different directories in the system volume.
A default AmigaOS installation looks like this:

* C
This directory contains AmigaDOS '''C'''ommands
* Classes
contains different object elements easy to be used in any program: gadgets, requesters, graphic table, windows...
* Devs
contains definitions for '''Dev'''ices
* Emulation
contains files used for the 68k emulation (though E-UAE)
* Fonts
contains various systems fonts
* Internet
contains Internet-related files and configurations
* Kickstart
contains the kickstart modules
* L
contains hand'''l'''ers and filesystems
* Libs
contains dynamic '''Lib'''rairies of functions
* Locale
contains all files used to customise the system for your locality (catalogs, keymaps...)
* MUI
contains the files needed for programs that use the MUI third party graphic interface
* [[Prefs]]
contains the preference programs used to customise AmigaOS
* S
contains the system's '''S'''cripts
* SObjs
contains .so shared object library files
* Storage
contains other optional files, not currently used
* System
contains some programs used by the system itself (i.e. you don't need to run them yourself) or low-level programs like disk tools
* [[Utilities]]
contains several programs you can use to achieve some tasks on AmigaOS

= Motorola 680x0 Emulators =

For a long time Amigas have had the famous Motorola 680x0 processors as the central unit for execution. Unfortunately the time of the 680x0 series is passing in favor of other architectures. The new era of processors reached the Amiga some time ago, when expansion boards became available for extending the Classic systems with the raw power of a PowerPC processor.

In the old operating system (AmigaOS 3.x) it was not possible to gain the full advantage of the new processors. The system itself and most of the applications required the original Motorola 680x0 processor. There was no 680x0 emulation available for the PowerPCs, so the 680x0 could not be "switched off".

Thus the new processors remained as a powerful, but mostly unused adjunct to the main 680x0 processor. "Native" PowerPC programs were rare, and every time a PowerPC program called the system, a so called "context switch" occurred between the 680x0 and PowerPC code, often causing a large performance penalty.

The new Amiga platform is based on the PowerPC processor family, therefore the new version of the AmigaOS has to smooth the transition from the 680x0 series, which is achieved by emulating the old processor architecture. The operating system itself is written almost 100 percent for the PowerPC processors, but the 680x0 legacy applications require an emulated 680x0 processor.

== Two 680x0 Emulators ==

In version 4.0 of AmigaOS, two different emulators were implemented. One is the successor of BlackBox emulation. It is an interpretive emulator with mediocre emulation speed. On the other hand, it has a very low "reaction time" and is ideal for time critical parts, such as interrupts.

The other is Petunia, the "JIT emulator", a fast but less compatible way of emulation of the legacy Motorola processors. It is intended mainly for emulating applications. When execution of the application leaves the bounds of the application's code segment, emulation falls back to the interpretive method, where it does its job and returns to the JIT emulation again.

Dynamic recompilation (also called just-in-time compilation or simply JIT compilation) is a technique of translating foreign processor machine code to native machine code "on the fly".

This technique is common nowadays in JAVA virtual machines. It is also used with success in several emulators. In dynamic recompilation, there is the possibility of runtime optimization of the emulated code by collecting statistics of the execution process. Therefore (theoretically) the final executed code can be even faster than the original code on its original processor.

== Features ==

Emulated opcodes:
* all user and supervisor level opcodes of the Motorola 68040
* all FPU opcodes of the Motorola 68881/68882

AmigaOS claims only 68020/68881 compatibility to applications because this is the safest compatibility level, but both emulators are compatible with the machine code up to the level of 68040/060 processors.

At compile time, a low level flag and branch control analysis allows on-the-fly optimizations of compiled code.

== Removing the JIT Emulator ==

Using dynamic translation requires a lot more memory than interpretive emulation. The translated code needs to be stored somewhere, not to mention the data collection tables.

If speed is not as important as the memory consumption of the system, the JIT emulator can be removed, leaving the job to the interpretive emulator.

Thanks to the modular design of AmigaOS kickstart, all you need to do is edit the "Sys:Kickstart/Kicklayout" file. Simply put a semicolon (;) at the beginning of the module line "Petunia.library.kmod". After executing a "cold" system reboot, the JIT emulator will not be reloaded. Make sure that you alter the appropriate configuration in the Kicklayout file. There may be several alternative configurations with different names, such as "DefaultJIT" or "DefaultNoJIT".

== Configuring the Emulators ==

Petunia cooperates with a so called "black list". By default, Petunia emulates every 680x0 program or library that is loaded by DOS.library/LoadSeg function, but if an executable or library shows incompatibilities with Petunia, then it can be explicitly inhibited from the dynamic recompilation by specifying it in a list.

If an executable needs to be added to the list, then it can be done by extending the file "DEVS:applications.dos" with the '''Compatibility''' preferences program from the Prefs drawer of the system. Adding a program name to the list and checking it will prevent Petunia from emulating that program, and it will be interpreted instead by the built-in interpreter.

Removing a program from the list or unchecking (thus allowing Petunia to emulate it again) can be done with the same preferences program.

Please note: some programs consist of multiple executables (shared libraries, plugins). If you want to fully disable the translation of such programs, then every part must be added to the list.

For example to disable UnArc fully, you would have to add to the list all files from libs:xad and also xadmaster.library.

= AmigaOS boot procedure =

Classic Amigas with PowerPC accelerators, the original AmigaOne SE/XE and the Sam series of Amigas all use the Second Level Booter (SLB) to read their Kickstart modules from the system volume. The newer A-Eon machines (X1000, X5000, A1222) all use a loader called AmigaBoot. In the X1000, AmigaBoot must be read from an FFS partition, while in the later machines, it is stored in the on-board CF card. The process of loading the kickstart modules is the same in all cases.

Basically a computer with AmigaOS does the following when the power button is pushed:

* [[File:Uboot.jpg|200px]]
The BIOS ([[UserDoc:BIOS|Uboot]] or [[UserDoc:BIOS|CFE]]) of the computer initialises the hardware: graphic card, USB ports... At this point, the monitor wakes up and the first information is displayed. This shows if hardware is correctly recognised. As an example you can see if a hard drive is correctly connected into the machine and your BIOS is correctly set up to make this drive useable.
* Depending on the machine type, the BIOS will look on the harddisk to find the Second Level Booter (SLB) or AmigaBoot, or will execute the AmigaBoot program from the on-board NVRAM. Whereas the BIOS does not know about AmigaOS disk structure, the SLB/AmigaBoot can ''understand'' the AmigaOS partitions and file systems. In other words, it is the link between the BIOS and the rest of the boot procedure. Its goal is also to give you the ability to start several configurations present on the same drive.
* [[File:SLB.png|200px]]
SLB/AmigaBoot analyses all Amiga partitions on the system disk. It reads each system configuration it finds on the partition and displays them all for the user to select one to load. AmigaBoot (not SLB) also displays configurations from Kickstart/Kicklayout files on every "bootable" partition.
The user can [[UserDoc:How_AmigaOS_Works#Control_of_the_Kickstart|define]] many different kickstart configurations to choose from. Also both AmigaOS and Linux can be selected for boot.
* [[File:Kmods loading.png|200px]]
SLB/AmigaBoot loads the kickstart files of the selected configuration and executes the '''Loader''' module
* '''Loader''' executes the kickstart modules (Exec, devices, libraries...)
* AmigaOS becomes alive displaying the AmigaOS boot picture on the monitor
* The AmigaDOS library executes the [[UserDoc:System_Scripts#startup-sequence|startup-sequence]] script found on the system volume
* The Startup-sequence will be executed and all commands it contains are executed. It means that starting from here the boot procedure is easy to follow and understand.
* The Workbench is started

At this point the user can use his/her computer.

= How to make a Bootable USB Memory Stick for AmigaOS 4.1 =

By Julian Margetson ("Spectre660")

Prerequisites:
* USB memory stick of 2 GB or less in size.
* It is best to only have one USB mass storage device connected while you are creating your bootable USB memory stick.
* Plug the USB memory stick into a USB port on your machine.
* Note that the device will be formatted so make sure that you use an empty memory stick or one that does not contain any data that you need or backup the contents before you begin.

Procedure:
# You use Media Toolbox in the System: drawer to prepare the USB stick. On starting Media Toolbox select ''usbdisk.device'' as the device to use.
# Make certain that you have selected usbdisk.device and not any other device.
# Click on "Start"
# You will see the usb mass storage unit connected in a list.
# Make sure that the Unit type displayed for the USB memory stick is "Removable hard disk"
# Select that Unit by clicking on it.
# The first thing that you need to do is to install the RDB onto the USB Memory Stick.
# Click on the "Install" button.
# A window Labeled "RDB/disk geometry editing" comes up.
## Towards the bottom of the window is the "AmigaOne boot code (SLB)" section.
## Select the "Install" button .
## A file requester "Select AmigaOne Boot Code" now comes up with the Drawer choice defaulting to "l:"
## Select file "slb_v2".
## Select Ok.
## You are now returned to the "RDB/disk geometry editing window".
## Select "Ok-accept changes".
# You are now returned to the display showing the attached USB unit.
# Select "Edit partitions and Filesystems". You will now see the Window 'Editing partitions for disk"
# Select "Add partition"
# This defaults to using the whole device as a single partition.
# It is possible to use create more partitions but for this tutorial we will only use one.
# You now need to give the partition a unique name (e.g. USB0 or something that is different from any of the existing partitions on your hard drive). This is done by changing the default DH0 in the "Name" box.
# Now make sure that the Boxes "Automount" and "Bootable" are selected and show the "Tick mark".
# You need to set "Boot priority" to higher than the boot priority of your hard drive boot partition(s). This is done by increasing Boot priority by clicking on the "+" to the right of the "boot priority" box. Normally you can set the boot priority to 2 .
# Next it is time to select the file system to use.
# Select "Select filesystem/edit details".
# The Window "Editing details for partition 'USB0'" ,or whatever partition name you used, comes up.
## Select the file system that you are going to use by selecting the pull down menu under "Filesystem chooser".
## Only filesystems SFS/00 or SFS/02 will work for a bootable device.
## The option that gives the most flexibility at the moment is SFS/00 as a USB stick in this format can be read from and written to using another compatible system in the event that you need to make modifications after it is created without a booting AmigaOS 4.1 machine.
## Next select Blocksize from the "Blocksize" pull down menu. 512 is the correct size to use.
## Now Select "Ok-accept changes".
## Your are now returned to the "Edit partitions for disk" window.
## Again select "Ok-accept changes"
# You are now returned to the window showing the USB mass storage unit list.
# Select "Save to disk"
# A requester pops up with the options "Yes, Save." or "No!"
# Select the "Yes, save." option.
# You now close Media Toolbox by clicking on the close icon (X) on the left of the Media Toolbox window.
# This will give you a requester advising that you need to reboot the machine for the changes to take effect. At this point you need to remove the USB memory stick for the machine. If you do not then the Machine will attempt boot from it before it is formatted and the required Kickstart and AmigaOS 4.1 files are copied to it.
# Select "Yes, reboot NOW!".
# Once you have rebooted connect your USB Memory Stick to a USB port.
# A disk icon "USB0:Uninitialized" (or whatever partition name you used) appears on Workbench.
# You now need to format the device.
# To format Select this Icon and go to the Workbench "Icons" menu .
# Select "Format Disk"
# You can give the USB Memory Stick a unique name and select whether you want a Trashcan or not.
# You can use either a full Format or a Quick Format. Full Format may take a few minutes.
# Once formatted the USB Memory Stick is ready for you to copy the required files from you hard drive or AmigaOS Install CD to it in order to boot AmigaOS 4.1 from it.

UserDoc:How AmigaOS Works

2023-10-03T15:41:43Z

Brian Deneen: /* Two 680x0 Emulators */ Various reconstruction of sentences for clarity. Please see the "Show changes" page

As already mentioned, AmigaOS was a pioneer in the early days of personal computing in delivering sophistication that contemporary systems could only have dreamt of and pretended to offer. Today, AmigaOS continues to offer a straightforward elegance that seems to be overlooked in the development of other platforms. Thanks to the concepts behind AmigaOS, the system is easy to understand and to use by everyone.

In this page we will explore all these concepts of AmigaOS. Also you will learn here the naming of all parts of the system.

= Introduction =

AmigaOS is made of different components which are either mandatory (i.e., AmigaOS will not work without them) or components the user can choose to use or not. All these components can have one or mutiple interfaces a user or a developer can use to operate with the components and through them to control the operating system.

= The most important components =

== Exec, the AmigaOS kernel ==

Exec is the kernel of AmigaOS. It is the component that pilots all other components. It is responsible for running programs, dealing with computer memory and managing low-level resources that programs may need. In other words, it organises everything to make the operating system run.

It is made of different parts that cannot be moved outside the kernel: the scheduler, the memory pager and the 68k interpretive emulator.

== AmigaDOS: the underlying system ==

The word "DOS" was originally an acronym for "Disk Operating System". Some say it should be "Disk Based Operating System" as it does a lot more than operate a disk and that it was really an operating system based (stored) on disks. Some say it should be "Device Operating System".

The whole AmigaDOS system includes things such as:

* A set of commands that can be used in the Shell window and elsewhere.
* A system for saving data to disk and retrieving it from disk.
* A system for filing data on disks.
* An interface for peripherals such as keyboards, monitors, printers, etc.
* A method of running programs
* A multitasking system for running more than one program at a time.
* etc. etc. etc.

Read the [[AmigaDOS manual]] to understand and learn everything about AmigaDOS.

== The Graphics library ==

The Graphics library handles every low level graphic operation like designing pixels on the monitor, creating graphic elements (bobs, sprites) and also writing text output.

== Intuition ==

The Intuition library is responsible for every graphical object: windows, screens, gadgets, mouse pointers... It lies between any graphic program and the graphics library.

== The Workbench ==

The Workbench is the graphical place where you will manage your computer and all your files. The name was chosen because the user will use tools to create and work with the computer.

[[File:Wb.png|320px]]

== The Shell ==

While some people prefer to control the operating system using their mouse, others prefer using the keyboard. The shell is a text based window when you can type commands to execute actions in the operating system. In the shell the commands will display the results of their execution.

== ARexx - inter-program communication by scripting ==

The ARexx scripting language can be used to operate the Workbench and other Amiga applications from a script containing ARexx commands. This is extremely useful in performing repetitive tasks or doing what the controlled application was not even designed to do.
After a learning curve, everybody can use ARexx as it is built into the system. The scripts can be executed immediately like any other tool.

= How is my data stored? =
== Files ==
=== Executable files ===
Programs you can start are stored in executable files. They contain binary code directly understandable by the computer. They are files with an executable bit, a flag that shows AmigaOS that such file will do something when started.
An example is a music player. When you start this executable, the player opens and you can start playing music files.

AmigaOS can run two different kinds of executable files: the AmigaOS native programs made for the PowerPC processor and programs created for the Motorola 68k processors. The latter are executed inside an emulation that translates them into PowerPC code.

==== Scripts ====

Scripts are text files containing a list of commands. They are not strictly executables like ''binary code'' files but they can be executed by AmigaOS as if they were.
This is the case with AmigaDOS and ARexx scripts. These files need to have the executable and script bits set.

=== Data files ===
Files that are not executable are data files. These contain data that will be manipulated by programs. Some examples are a music file, a video file or a text document.

== Directories/Drawers ==
In order to organise things, files are grouped together. We create "directories" which are like drawers of a cabinet to store different files of the same kind, for example.
Often the name ''directory'' is used when talking about a directory which is stored on a disk. The graphical interface of AmigaOS is called "Workbench," and directories are often called ''drawers''.

Note: directories are often called ''folders'' on other systems. The terms "directory," "drawer" and "folder" are synonymous.

== Disks, partitions and volumes ==
=== Disks ===
Disks are storage media you can purchase at a computer store. We use them to store our files. They can be internal hard disks, external hard drives, USB interface devices (i.e., SD cards, CF cards, "flash" drives, etc.), and floppy disk drives.

=== Partitions ===
A disk is often very big and many users prefer to make it more organised. This is done by virtually splitting the disk into several smaller parts. This operation is known as creating partitions on a disk.

[[File:Partitions.png|Small part of Media Toolbox showing different partitions on the harddisk]]

On this screenshot you can see one harddisk with many partitions. Each color corresponds to a different filesystem which defines how data is stored. Also, you can see a greyed area which is a blank area on the disk (i.e., no partition is defined at this position). Several different file systems can be used on the same Amiga drive. It's your choice.

=== Volumes ===
A partition is a physical area on a disk. To access it with AmigaOS we must read the physical data off the partition. To make it easier AmigaOS uses the concept of volumes. These are virtual representations of a partition. The volumes have a name so AmigaOS and therefore the user can access all files/directories stored on it in a very practical way: just by using its name.

Volume names can refer to either a physical or virtual named space. See the autodoc section for the ASSIGN command in the C: directory as well as the MOUNT command which provides more information on naming and the concept of volumes.

= How to identify files/directories =

== On the Workbench ==

The Workbench being graphical, a lot of things are understandable just by looking at them. That's why icons are often enough to understand what kind of object it represents: a file, a directory, a disk...

In case you have a doubt, just look at the information on an icon. The Workbench will tell you the type of the object. It is displayed next to its name.

== In a shell ==

In a shell the '''list''' command can be used to see if an object is a file or a directory.

[[File:Files-dirs-in-shell.png|The '''list''' command shows a file of 925678 bytes and two directories]]

A file will be displayed with its size, whereas a directory will be displayed with the text '''Dir''' next to it.

Also, as you can see on the screenshot, the list command displays other characteristics on these 3 items: the protection bits and the date they were updated the last time. The command also sums up what it just listed.

= All AmigaOS components =

AmigaOS is made of components that are needed as soon as the system starts or later when the user or the system needs them.

== Kickstart modules ==

These components are the heart of AmigaOS. Their duty is to draw graphics, to handle discs or to handle all reads/writes to files. Also one of them is the AmigaOS kernel which is a kind of director handling the work of all other components.
These Kickstart modules are loaded at the beginning of the operating system boot process (read [[UserDoc:How_AmigaOS_Works#AmigaOS_boot_procedure|here]]). You can find them all in the '''Kickstart''' directory on the system volume. Here is a list:

=== Mandatory modules ===

The following modules are required in any AmigaOS system. Without one of these, the system will not start.

* kernel - The kernel works like the conductor of an orchestra. Its job is to make everything work together. It creates processes, handles memory usage, defines the way other components will access peripherals...etc. Note that the AmigaOS kernel is not based on any other kernel. It is a unique kernel that has existed since 1983.
* loader - this component handles the loading of all other kickstart modules
* battclock.resource.kmod - this module handles reading/writing the battery backed up clock which is used on all computers to keep the date and time
* bootimage - this is the boot picture. It is displayed during the start sequence of AmigaOS
* bootmenu.kmod - this component handles the Early Startup Menu the user can employ to define some settings before starting AmigaOS
* con-handler.kmod - it directs read and write requests to the console window, to a serial AUX: device or any other supported interface
* console.device.kmod - it opens a window and reads/writes text to and from that window
* diskboot.kmod - handles the booting of AmigaOS from a supported disk
* diskboot.config - this is a text file experienced users can modify to change the boot behaviour of AmigaOS
* dos.library.kmod - this module is a collection of functions that any program can use to perform actions on disks, files and directories
* elf.library.kmod - handles the loading of executable programs
* env-handler.kmod - handles the reads/writes of environment variables
* FileSystem.resource.kmod - handles access to the different filesystems
* gadtools.library.kmod - a collection of functions used to create all graphic objects like gadgets, sliders, menus...
* gameport.device.kmod - handles the reads/writes of game pads and joysticks
* graphics.library.kmod - a collection of functions used to draw graphic elements on the monitor
* hunk.library.kmod - a set of functions to read a data stream into memory
* input.device.kmod - handles input events like keyboard events or mouse clicks
* intuition.library.kmod - a collection of functions to create and handle all graphic elements (screens, windows, the mouse pointer...)
* layers.library.kmod - set of functions to be used to handle different layers in graphic operations
* keyboard.device.kmod - driver for the keyboard
* keymap.library.kmod - functions to handle different keymaps
* newlib.library.kmod - collection of functions to perform memory operations (allocating memory, copying memory areas... )
* nonvolatile.library.kmod - provides a simple means for an application developer to manage nonvolatile storage
* nvram.resource.kmod - handles the reads/writes to the NVRAM chip present on many AmigaOS computers
* PCIGraphics.card - driver that supports the use of different graphic cards
* ram-handler.kmod - functions that handle the '''Ram disk:'''.
* ramdrive.device.kmod - device that allows the usage of the ramdrive device '''RAD:''' disk
* ramlib.kmod - loads disk based libraries and devices for exec.library
* rtg.library - library of functions to perform low level graphic operations on graphics cards
* shell.kmod - the AmigaOS command line interface
* strap.kmod - module that handles booting on different disk devices
* timer.device.kmod - driver to give access to timing functions

=== Filesystem support ===

These kickstart modules can be loaded optionally. If you want to use a particular filesystem on your disk partitions, you need to load the corresponding filesystem module.

* CDFileSystem - handles the CD-ROM disks with data stored in different formats: ISO9660, HFS...
* SmartFilesystem - allows the usage of partitions in SFS0 and SFS2 layouts
* JXFileSystem - allows the usage of partitions in JXFS layout (now obsolescent)
* FastFileSystem - allows the usage of partitions in FFS and FFS2 layouts
* NGFileSystem - an experimental file system designed to gradually replace the FastFileSystem
* diskcache.library.kmod - component required by the SmartFileSystem and JXFileSystem modules

=== Hardware drivers ===

==== Graphic cards drivers ====

* 3dfxVoodoo.chip
* 3DLabsPermedia2.chip
* ATIRadeon.chip
* RadeonHD.chip
* siliconmotion502.chip

==== Disk drivers ====

Each of these drivers allows the use of disks connected to a disk controller. These files are named after the controller they support. As an example, the '''sii3114ide.device.kmod''' allows the use of disks connected to a '''Silicon Image SiI3114''' controller chip.

* it8212ide.device.kmod
* lsi53c8xx.device.kmod
* sam460sata.device.kmod
* sii3112ide.device.kmod
* sii3512ide.device.kmod
* sii3114ide.device.kmod
* sii0680ide.device.kmod
* sii3132ide.device.kmod

==== USB drivers ====

* hub.usbfd
* usbsys.device
* usbresource.library
* ehci.usbhcd
* ohci.usbhcd
* uhci.usbhcd
* massstorage.usbfd

==== Other drivers ====

* bootkeyboard.usbfd - allows a USB keyboard to be used even before the USB stack is loaded
* bootmouse.usbfd - allows a USB mouse to be used even before the USB stack is loaded
* fpga.resource.kmod - allows to use the FPGA components which are present on some Amiga computers
* i2c.resource.kmod - allows to use the i2c interface present on some Amiga computers
* xena.resource.kmod - provides access to the Xena chip on the AmigaOne X1000

==== Misc modules ====

* petunia.library.kmod - this module contains the Just-In-Time emulator that allows AmigaOS to run programs made for the Motorola 68k processor

== Control of the Kickstart ==

The Kickstart/ drawer contains an ASCII file called "Kicklayout". This file lists all the modules that must be loaded from the system volume during the boot process. It is read by the boot loaders "SLB" or "amigaboot".

The Kicklayout file consists of a number of configurations, each of which describes a set of Kickstart modules. Each configuration has a label and the various configurations are listed by label on the boot screen. The user may elect to load the default configuration or to select any one of the other configurations. Often a developer will have several configurations in his/her Kicklayout file, some of which may be experimental, while the default is a "known good" configuration to which (s)he can fall back.

You can edit the Kicklayout file using Notepad or any other ASCII editor. You are strongly advised to leave the original configuration unchanged (as a fall-back) and to add new configurations at the end of the file, each with its own label. That way you can still recover if you make a mistake while editing.

<nowiki>; Configuration name
LABEL MainSystem
; Exec name
EXEC Kickstart/loader.of
;
; PPC native modules
;
MODULE Kickstart/kernel
;
MODULE Kickstart/FastFileSystem
MODULE Kickstart/CDFileSystem
MODULE Kickstart/NGFileSystem
;
(etc)</nowiki>

Note that lines that start with a semicolon (";") are treated as comments and are ignored. Each configuration must start with a "LABEL" keyword and should be separated from the previous configuration by a blank line. The blank line signifies "Stop loading here".

Each module to be loaded is defined by the "MODULE" keyword, followed by the path and file name. You can use any path ''on the system volume'', so you could have two or more drawers containing Kickstart modules and address them independently if you so wished. You can not refer to modules on other volumes, since they have not been mounted by DOS (which does not exist yet) and only the system volume is available at this early stage.

=== Selecting the Default Configuration ===

You can specify in the NVRAM the label of the default configuration in the Kicklayout. For instance, if your default configuration is called "MainSystem", the LABEL line will look like this:

LABEL MainSystem

You can define an NVRAM variable called "boot_config" using U-Boot, CFE or the "nvsetvar" tool. Simply type:

nvsetvar boot_config "MainSystem"

[Note that nvsetvar may be inhibited from writing to the NVRAM on some systems, in which case you will have to use U-Boot or CFE to set the variable]

If you do not specify a default configuration with the "boot_config" variable, the boot loader will default to the first configuration in the Kicklayout.

== System components ==

[[File:Workbench_directory_listing.png|frame|right|List of directories and files present at the root of any AmigaOS system]]

Beside the kickstart modules, AmigaOS uses many different components that can be loaded only when needed. These files are stored in different directories in the system volume.
A default AmigaOS installation looks like this:

* C
This directory contains AmigaDOS '''C'''ommands
* Classes
contains different object elements easy to be used in any program: gadgets, requesters, graphic table, windows...
* Devs
contains definitions for '''Dev'''ices
* Emulation
contains files used for the 68k emulation (though E-UAE)
* Fonts
contains various systems fonts
* Internet
contains Internet-related files and configurations
* Kickstart
contains the kickstart modules
* L
contains hand'''l'''ers and filesystems
* Libs
contains dynamic '''Lib'''rairies of functions
* Locale
contains all files used to customise the system for your locality (catalogs, keymaps...)
* MUI
contains the files needed for programs that use the MUI third party graphic interface
* [[Prefs]]
contains the preference programs used to customise AmigaOS
* S
contains the system's '''S'''cripts
* SObjs
contains .so shared object library files
* Storage
contains other optional files, not currently used
* System
contains some programs used by the system itself (i.e. you don't need to run them yourself) or low-level programs like disk tools
* [[Utilities]]
contains several programs you can use to achieve some tasks on AmigaOS

= Motorola 680x0 Emulators =

For a long time Amigas have had the famous Motorola 680x0 processors as the central unit for execution. Unfortunately the time of the 680x0 series is passing in favor of other architectures. The new era of processors reached the Amiga some time ago, when expansion boards became available for extending the Classic systems with the raw power of a PowerPC processor.

In the old operating system (AmigaOS 3.x) it was not possible to gain the full advantage of the new processors. The system itself and most of the applications required the original Motorola 680x0 processor. There was no 680x0 emulation available for the PowerPCs, so the 680x0 could not be "switched off".

Thus the new processors remained as a powerful, but mostly unused adjunct to the main 680x0 processor. "Native" PowerPC programs were rare, and every time a PowerPC program called the system, a so called "context switch" occurred between the 680x0 and PowerPC code, often causing a large performance penalty.

The new Amiga platform is based on the PowerPC processor family, therefore the new version of the AmigaOS has to smooth the transition from the 680x0 series, which is achieved by emulating the old processor architecture. The operating system itself is written almost 100 percent for the PowerPC processors, but the 680x0 legacy applications require an emulated 680x0 processor.

== Two 680x0 Emulators ==

In version 4.0 of AmigaOS, two different emulators were implemented. One is the successor of BlackBox emulation. It is an interpretive emulator with mediocre emulation speed. On the other hand, it has a very low "reaction time" and is ideal for time critical parts, such as interrupts.

The other is Petunia, the "JIT emulator", a fast but less compatible way of emulation of the legacy Motorola processors. It is intended mainly for emulating applications. When execution of the application leaves the bounds of the application's code segment, emulation falls back to the interpretive method, where it does its job and returns to the JIT emulation again.

Dynamic recompilation (also called just-in-time compilation or simply JIT compilation) is a technique of translating foreign processor machine code to native machine code "on the fly".

This technique is common nowadays in JAVA virtual machines. It is also used with success in several emulators. In dynamic recompilation, there is the possibility of runtime optimization of the emulated code by collecting statistics of the execution process. Therefore (theoretically) the final executed code can be even faster than the original code on its original processor.

== Features ==

Emulated opcodes:
* all user and supervisor level opcodes of the Motorola 68040
* all FPU opcodes of the Motorola 68881/68882

AmigaOS claims only 68020/68881 compatibility to applications because this is the safest compatibility level, but both emulators are compatible with the machine code up to the level of 68040/060 processors.

At compile time, a low level flag and branch control analysis allows on-the-fly optimizations of compiled code.

== Removing the JIT Emulator ==

Using the dynamic translation requires a lot more memory than the interpretive emulation. The translated code needs to be stored somewhere, not to mention the data collection tables.

If speed is not as important as the memory consumption of the system, then the JIT emulator can be removed, leaving the job to the interpretive emulator.

Thanks to the modular design of AmigaOS kickstart, all you need to do is edit the "Sys:Kickstart/Kicklayout" file, simply put a semicolon (;) at the beginning of the module line of Petunia.library.kmod. After rebooting the system from cold, the JIT emulator will not be reloaded. Make sure that you alter the appropriate configuration in the Kicklayout file, there may be several alternative configurations, with different names like "DefaultJIT", or "DefaultNoJIT".

== Configuring the Emulators ==

Petunia cooperates with a so called "black list". By default, Petunia emulates every 680x0 program or library that is loaded by DOS.library/LoadSeg function, but if an executable or library shows incompatibilities with Petunia, then it can be explicitly inhibited from the dynamic recompilation by specifying it in a list.

If an executable needs to be added to the list, then it can be done by extending the file "DEVS:applications.dos" with the '''Compatibility''' preferences program from the Prefs drawer of the system. Adding a program name to the list and checking it will prevent Petunia from emulating that program, and it will be interpreted instead by the built-in interpreter.

Removing a program from the list or unchecking (thus allowing Petunia to emulate it again) can be done with the same preferences program.

Please note: some programs consist of multiple executables (shared libraries, plugins). If you want to fully disable the translation of such programs, then every part must be added to the list.

For example to disable UnArc fully, you would have to add to the list all files from libs:xad and also xadmaster.library.

= AmigaOS boot procedure =

Classic Amigas with PowerPC accelerators, the original AmigaOne SE/XE and the Sam series of Amigas all use the Second Level Booter (SLB) to read their Kickstart modules from the system volume. The newer A-Eon machines (X1000, X5000, A1222) all use a loader called AmigaBoot. In the X1000, AmigaBoot must be read from an FFS partition, while in the later machines, it is stored in the on-board CF card. The process of loading the kickstart modules is the same in all cases.

Basically a computer with AmigaOS does the following when the power button is pushed:

* [[File:Uboot.jpg|200px]]
The BIOS ([[UserDoc:BIOS|Uboot]] or [[UserDoc:BIOS|CFE]]) of the computer initialises the hardware: graphic card, USB ports... At this point, the monitor wakes up and the first information is displayed. This shows if hardware is correctly recognised. As an example you can see if a hard drive is correctly connected into the machine and your BIOS is correctly set up to make this drive useable.
* Depending on the machine type, the BIOS will look on the harddisk to find the Second Level Booter (SLB) or AmigaBoot, or will execute the AmigaBoot program from the on-board NVRAM. Whereas the BIOS does not know about AmigaOS disk structure, the SLB/AmigaBoot can ''understand'' the AmigaOS partitions and file systems. In other words, it is the link between the BIOS and the rest of the boot procedure. Its goal is also to give you the ability to start several configurations present on the same drive.
* [[File:SLB.png|200px]]
SLB/AmigaBoot analyses all Amiga partitions on the system disk. It reads each system configuration it finds on the partition and displays them all for the user to select one to load. AmigaBoot (not SLB) also displays configurations from Kickstart/Kicklayout files on every "bootable" partition.
The user can [[UserDoc:How_AmigaOS_Works#Control_of_the_Kickstart|define]] many different kickstart configurations to choose from. Also both AmigaOS and Linux can be selected for boot.
* [[File:Kmods loading.png|200px]]
SLB/AmigaBoot loads the kickstart files of the selected configuration and executes the '''Loader''' module
* '''Loader''' executes the kickstart modules (Exec, devices, libraries...)
* AmigaOS becomes alive displaying the AmigaOS boot picture on the monitor
* The AmigaDOS library executes the [[UserDoc:System_Scripts#startup-sequence|startup-sequence]] script found on the system volume
* The Startup-sequence will be executed and all commands it contains are executed. It means that starting from here the boot procedure is easy to follow and understand.
* The Workbench is started

At this point the user can use his/her computer.

= How to make a Bootable USB Memory Stick for AmigaOS 4.1 =

By Julian Margetson ("Spectre660")

Prerequisites:
* USB memory stick of 2 GB or less in size.
* It is best to only have one USB mass storage device connected while you are creating your bootable USB memory stick.
* Plug the USB memory stick into a USB port on your machine.
* Note that the device will be formatted so make sure that you use an empty memory stick or one that does not contain any data that you need or backup the contents before you begin.

Procedure:
# You use Media Toolbox in the System: drawer to prepare the USB stick. On starting Media Toolbox select ''usbdisk.device'' as the device to use.
# Make certain that you have selected usbdisk.device and not any other device.
# Click on "Start"
# You will see the usb mass storage unit connected in a list.
# Make sure that the Unit type displayed for the USB memory stick is "Removable hard disk"
# Select that Unit by clicking on it.
# The first thing that you need to do is to install the RDB onto the USB Memory Stick.
# Click on the "Install" button.
# A window Labeled "RDB/disk geometry editing" comes up.
## Towards the bottom of the window is the "AmigaOne boot code (SLB)" section.
## Select the "Install" button .
## A file requester "Select AmigaOne Boot Code" now comes up with the Drawer choice defaulting to "l:"
## Select file "slb_v2".
## Select Ok.
## You are now returned to the "RDB/disk geometry editing window".
## Select "Ok-accept changes".
# You are now returned to the display showing the attached USB unit.
# Select "Edit partitions and Filesystems". You will now see the Window 'Editing partitions for disk"
# Select "Add partition"
# This defaults to using the whole device as a single partition.
# It is possible to use create more partitions but for this tutorial we will only use one.
# You now need to give the partition a unique name (e.g. USB0 or something that is different from any of the existing partitions on your hard drive). This is done by changing the default DH0 in the "Name" box.
# Now make sure that the Boxes "Automount" and "Bootable" are selected and show the "Tick mark".
# You need to set "Boot priority" to higher than the boot priority of your hard drive boot partition(s). This is done by increasing Boot priority by clicking on the "+" to the right of the "boot priority" box. Normally you can set the boot priority to 2 .
# Next it is time to select the file system to use.
# Select "Select filesystem/edit details".
# The Window "Editing details for partition 'USB0'" ,or whatever partition name you used, comes up.
## Select the file system that you are going to use by selecting the pull down menu under "Filesystem chooser".
## Only filesystems SFS/00 or SFS/02 will work for a bootable device.
## The option that gives the most flexibility at the moment is SFS/00 as a USB stick in this format can be read from and written to using another compatible system in the event that you need to make modifications after it is created without a booting AmigaOS 4.1 machine.
## Next select Blocksize from the "Blocksize" pull down menu. 512 is the correct size to use.
## Now Select "Ok-accept changes".
## Your are now returned to the "Edit partitions for disk" window.
## Again select "Ok-accept changes"
# You are now returned to the window showing the USB mass storage unit list.
# Select "Save to disk"
# A requester pops up with the options "Yes, Save." or "No!"
# Select the "Yes, save." option.
# You now close Media Toolbox by clicking on the close icon (X) on the left of the Media Toolbox window.
# This will give you a requester advising that you need to reboot the machine for the changes to take effect. At this point you need to remove the USB memory stick for the machine. If you do not then the Machine will attempt boot from it before it is formatted and the required Kickstart and AmigaOS 4.1 files are copied to it.
# Select "Yes, reboot NOW!".
# Once you have rebooted connect your USB Memory Stick to a USB port.
# A disk icon "USB0:Uninitialized" (or whatever partition name you used) appears on Workbench.
# You now need to format the device.
# To format Select this Icon and go to the Workbench "Icons" menu .
# Select "Format Disk"
# You can give the USB Memory Stick a unique name and select whether you want a Trashcan or not.
# You can use either a full Format or a Quick Format. Full Format may take a few minutes.
# Once formatted the USB Memory Stick is ready for you to copy the required files from you hard drive or AmigaOS Install CD to it in order to boot AmigaOS 4.1 from it.

UserDoc:How AmigaOS Works

2023-10-03T15:26:31Z

Brian Deneen: /* How to make a Bootable USB Memory Stick for AmigaOS 4.1 */ 20.3. Added "from" after "read" to maintain parallel construction.

As already mentioned, AmigaOS was a pioneer in the early days of personal computing in delivering sophistication that contemporary systems could only have dreamt of and pretended to offer. Today, AmigaOS continues to offer a straightforward elegance that seems to be overlooked in the development of other platforms. Thanks to the concepts behind AmigaOS, the system is easy to understand and to use by everyone.

In this page we will explore all these concepts of AmigaOS. Also you will learn here the naming of all parts of the system.

= Introduction =

AmigaOS is made of different components which are either mandatory (i.e., AmigaOS will not work without them) or components the user can choose to use or not. All these components can have one or mutiple interfaces a user or a developer can use to operate with the components and through them to control the operating system.

= The most important components =

== Exec, the AmigaOS kernel ==

Exec is the kernel of AmigaOS. It is the component that pilots all other components. It is responsible for running programs, dealing with computer memory and managing low-level resources that programs may need. In other words, it organises everything to make the operating system run.

It is made of different parts that cannot be moved outside the kernel: the scheduler, the memory pager and the 68k interpretive emulator.

== AmigaDOS: the underlying system ==

The word "DOS" was originally an acronym for "Disk Operating System". Some say it should be "Disk Based Operating System" as it does a lot more than operate a disk and that it was really an operating system based (stored) on disks. Some say it should be "Device Operating System".

The whole AmigaDOS system includes things such as:

* A set of commands that can be used in the Shell window and elsewhere.
* A system for saving data to disk and retrieving it from disk.
* A system for filing data on disks.
* An interface for peripherals such as keyboards, monitors, printers, etc.
* A method of running programs
* A multitasking system for running more than one program at a time.
* etc. etc. etc.

Read the [[AmigaDOS manual]] to understand and learn everything about AmigaDOS.

== The Graphics library ==

The Graphics library handles every low level graphic operation like designing pixels on the monitor, creating graphic elements (bobs, sprites) and also writing text output.

== Intuition ==

The Intuition library is responsible for every graphical object: windows, screens, gadgets, mouse pointers... It lies between any graphic program and the graphics library.

== The Workbench ==

The Workbench is the graphical place where you will manage your computer and all your files. The name was chosen because the user will use tools to create and work with the computer.

[[File:Wb.png|320px]]

== The Shell ==

While some people prefer to control the operating system using their mouse, others prefer using the keyboard. The shell is a text based window when you can type commands to execute actions in the operating system. In the shell the commands will display the results of their execution.

== ARexx - inter-program communication by scripting ==

The ARexx scripting language can be used to operate the Workbench and other Amiga applications from a script containing ARexx commands. This is extremely useful in performing repetitive tasks or doing what the controlled application was not even designed to do.
After a learning curve, everybody can use ARexx as it is built into the system. The scripts can be executed immediately like any other tool.

= How is my data stored? =
== Files ==
=== Executable files ===
Programs you can start are stored in executable files. They contain binary code directly understandable by the computer. They are files with an executable bit, a flag that shows AmigaOS that such file will do something when started.
An example is a music player. When you start this executable, the player opens and you can start playing music files.

AmigaOS can run two different kinds of executable files: the AmigaOS native programs made for the PowerPC processor and programs created for the Motorola 68k processors. The latter are executed inside an emulation that translates them into PowerPC code.

==== Scripts ====

Scripts are text files containing a list of commands. They are not strictly executables like ''binary code'' files but they can be executed by AmigaOS as if they were.
This is the case with AmigaDOS and ARexx scripts. These files need to have the executable and script bits set.

=== Data files ===
Files that are not executable are data files. These contain data that will be manipulated by programs. Some examples are a music file, a video file or a text document.

== Directories/Drawers ==
In order to organise things, files are grouped together. We create "directories" which are like drawers of a cabinet to store different files of the same kind, for example.
Often the name ''directory'' is used when talking about a directory which is stored on a disk. The graphical interface of AmigaOS is called "Workbench," and directories are often called ''drawers''.

Note: directories are often called ''folders'' on other systems. The terms "directory," "drawer" and "folder" are synonymous.

== Disks, partitions and volumes ==
=== Disks ===
Disks are storage media you can purchase at a computer store. We use them to store our files. They can be internal hard disks, external hard drives, USB interface devices (i.e., SD cards, CF cards, "flash" drives, etc.), and floppy disk drives.

=== Partitions ===
A disk is often very big and many users prefer to make it more organised. This is done by virtually splitting the disk into several smaller parts. This operation is known as creating partitions on a disk.

[[File:Partitions.png|Small part of Media Toolbox showing different partitions on the harddisk]]

On this screenshot you can see one harddisk with many partitions. Each color corresponds to a different filesystem which defines how data is stored. Also, you can see a greyed area which is a blank area on the disk (i.e., no partition is defined at this position). Several different file systems can be used on the same Amiga drive. It's your choice.

=== Volumes ===
A partition is a physical area on a disk. To access it with AmigaOS we must read the physical data off the partition. To make it easier AmigaOS uses the concept of volumes. These are virtual representations of a partition. The volumes have a name so AmigaOS and therefore the user can access all files/directories stored on it in a very practical way: just by using its name.

Volume names can refer to either a physical or virtual named space. See the autodoc section for the ASSIGN command in the C: directory as well as the MOUNT command which provides more information on naming and the concept of volumes.

= How to identify files/directories =

== On the Workbench ==

The Workbench being graphical, a lot of things are understandable just by looking at them. That's why icons are often enough to understand what kind of object it represents: a file, a directory, a disk...

In case you have a doubt, just look at the information on an icon. The Workbench will tell you the type of the object. It is displayed next to its name.

== In a shell ==

In a shell the '''list''' command can be used to see if an object is a file or a directory.

[[File:Files-dirs-in-shell.png|The '''list''' command shows a file of 925678 bytes and two directories]]

A file will be displayed with its size, whereas a directory will be displayed with the text '''Dir''' next to it.

Also, as you can see on the screenshot, the list command displays other characteristics on these 3 items: the protection bits and the date they were updated the last time. The command also sums up what it just listed.

= All AmigaOS components =

AmigaOS is made of components that are needed as soon as the system starts or later when the user or the system needs them.

== Kickstart modules ==

These components are the heart of AmigaOS. Their duty is to draw graphics, to handle discs or to handle all reads/writes to files. Also one of them is the AmigaOS kernel which is a kind of director handling the work of all other components.
These Kickstart modules are loaded at the beginning of the operating system boot process (read [[UserDoc:How_AmigaOS_Works#AmigaOS_boot_procedure|here]]). You can find them all in the '''Kickstart''' directory on the system volume. Here is a list:

=== Mandatory modules ===

The following modules are required in any AmigaOS system. Without one of these, the system will not start.

* kernel - The kernel works like the conductor of an orchestra. Its job is to make everything work together. It creates processes, handles memory usage, defines the way other components will access peripherals...etc. Note that the AmigaOS kernel is not based on any other kernel. It is a unique kernel that has existed since 1983.
* loader - this component handles the loading of all other kickstart modules
* battclock.resource.kmod - this module handles reading/writing the battery backed up clock which is used on all computers to keep the date and time
* bootimage - this is the boot picture. It is displayed during the start sequence of AmigaOS
* bootmenu.kmod - this component handles the Early Startup Menu the user can employ to define some settings before starting AmigaOS
* con-handler.kmod - it directs read and write requests to the console window, to a serial AUX: device or any other supported interface
* console.device.kmod - it opens a window and reads/writes text to and from that window
* diskboot.kmod - handles the booting of AmigaOS from a supported disk
* diskboot.config - this is a text file experienced users can modify to change the boot behaviour of AmigaOS
* dos.library.kmod - this module is a collection of functions that any program can use to perform actions on disks, files and directories
* elf.library.kmod - handles the loading of executable programs
* env-handler.kmod - handles the reads/writes of environment variables
* FileSystem.resource.kmod - handles access to the different filesystems
* gadtools.library.kmod - a collection of functions used to create all graphic objects like gadgets, sliders, menus...
* gameport.device.kmod - handles the reads/writes of game pads and joysticks
* graphics.library.kmod - a collection of functions used to draw graphic elements on the monitor
* hunk.library.kmod - a set of functions to read a data stream into memory
* input.device.kmod - handles input events like keyboard events or mouse clicks
* intuition.library.kmod - a collection of functions to create and handle all graphic elements (screens, windows, the mouse pointer...)
* layers.library.kmod - set of functions to be used to handle different layers in graphic operations
* keyboard.device.kmod - driver for the keyboard
* keymap.library.kmod - functions to handle different keymaps
* newlib.library.kmod - collection of functions to perform memory operations (allocating memory, copying memory areas... )
* nonvolatile.library.kmod - provides a simple means for an application developer to manage nonvolatile storage
* nvram.resource.kmod - handles the reads/writes to the NVRAM chip present on many AmigaOS computers
* PCIGraphics.card - driver that supports the use of different graphic cards
* ram-handler.kmod - functions that handle the '''Ram disk:'''.
* ramdrive.device.kmod - device that allows the usage of the ramdrive device '''RAD:''' disk
* ramlib.kmod - loads disk based libraries and devices for exec.library
* rtg.library - library of functions to perform low level graphic operations on graphics cards
* shell.kmod - the AmigaOS command line interface
* strap.kmod - module that handles booting on different disk devices
* timer.device.kmod - driver to give access to timing functions

=== Filesystem support ===

These kickstart modules can be loaded optionally. If you want to use a particular filesystem on your disk partitions, you need to load the corresponding filesystem module.

* CDFileSystem - handles the CD-ROM disks with data stored in different formats: ISO9660, HFS...
* SmartFilesystem - allows the usage of partitions in SFS0 and SFS2 layouts
* JXFileSystem - allows the usage of partitions in JXFS layout (now obsolescent)
* FastFileSystem - allows the usage of partitions in FFS and FFS2 layouts
* NGFileSystem - an experimental file system designed to gradually replace the FastFileSystem
* diskcache.library.kmod - component required by the SmartFileSystem and JXFileSystem modules

=== Hardware drivers ===

==== Graphic cards drivers ====

* 3dfxVoodoo.chip
* 3DLabsPermedia2.chip
* ATIRadeon.chip
* RadeonHD.chip
* siliconmotion502.chip

==== Disk drivers ====

Each of these drivers allows the use of disks connected to a disk controller. These files are named after the controller they support. As an example, the '''sii3114ide.device.kmod''' allows the use of disks connected to a '''Silicon Image SiI3114''' controller chip.

* it8212ide.device.kmod
* lsi53c8xx.device.kmod
* sam460sata.device.kmod
* sii3112ide.device.kmod
* sii3512ide.device.kmod
* sii3114ide.device.kmod
* sii0680ide.device.kmod
* sii3132ide.device.kmod

==== USB drivers ====

* hub.usbfd
* usbsys.device
* usbresource.library
* ehci.usbhcd
* ohci.usbhcd
* uhci.usbhcd
* massstorage.usbfd

==== Other drivers ====

* bootkeyboard.usbfd - allows a USB keyboard to be used even before the USB stack is loaded
* bootmouse.usbfd - allows a USB mouse to be used even before the USB stack is loaded
* fpga.resource.kmod - allows to use the FPGA components which are present on some Amiga computers
* i2c.resource.kmod - allows to use the i2c interface present on some Amiga computers
* xena.resource.kmod - provides access to the Xena chip on the AmigaOne X1000

==== Misc modules ====

* petunia.library.kmod - this module contains the Just-In-Time emulator that allows AmigaOS to run programs made for the Motorola 68k processor

== Control of the Kickstart ==

The Kickstart/ drawer contains an ASCII file called "Kicklayout". This file lists all the modules that must be loaded from the system volume during the boot process. It is read by the boot loaders "SLB" or "amigaboot".

The Kicklayout file consists of a number of configurations, each of which describes a set of Kickstart modules. Each configuration has a label and the various configurations are listed by label on the boot screen. The user may elect to load the default configuration or to select any one of the other configurations. Often a developer will have several configurations in his/her Kicklayout file, some of which may be experimental, while the default is a "known good" configuration to which (s)he can fall back.

You can edit the Kicklayout file using Notepad or any other ASCII editor. You are strongly advised to leave the original configuration unchanged (as a fall-back) and to add new configurations at the end of the file, each with its own label. That way you can still recover if you make a mistake while editing.

<nowiki>; Configuration name
LABEL MainSystem
; Exec name
EXEC Kickstart/loader.of
;
; PPC native modules
;
MODULE Kickstart/kernel
;
MODULE Kickstart/FastFileSystem
MODULE Kickstart/CDFileSystem
MODULE Kickstart/NGFileSystem
;
(etc)</nowiki>

Note that lines that start with a semicolon (";") are treated as comments and are ignored. Each configuration must start with a "LABEL" keyword and should be separated from the previous configuration by a blank line. The blank line signifies "Stop loading here".

Each module to be loaded is defined by the "MODULE" keyword, followed by the path and file name. You can use any path ''on the system volume'', so you could have two or more drawers containing Kickstart modules and address them independently if you so wished. You can not refer to modules on other volumes, since they have not been mounted by DOS (which does not exist yet) and only the system volume is available at this early stage.

=== Selecting the Default Configuration ===

You can specify in the NVRAM the label of the default configuration in the Kicklayout. For instance, if your default configuration is called "MainSystem", the LABEL line will look like this:

LABEL MainSystem

You can define an NVRAM variable called "boot_config" using U-Boot, CFE or the "nvsetvar" tool. Simply type:

nvsetvar boot_config "MainSystem"

[Note that nvsetvar may be inhibited from writing to the NVRAM on some systems, in which case you will have to use U-Boot or CFE to set the variable]

If you do not specify a default configuration with the "boot_config" variable, the boot loader will default to the first configuration in the Kicklayout.

== System components ==

[[File:Workbench_directory_listing.png|frame|right|List of directories and files present at the root of any AmigaOS system]]

Beside the kickstart modules, AmigaOS uses many different components that can be loaded only when needed. These files are stored in different directories in the system volume.
A default AmigaOS installation looks like this:

* C
This directory contains AmigaDOS '''C'''ommands
* Classes
contains different object elements easy to be used in any program: gadgets, requesters, graphic table, windows...
* Devs
contains definitions for '''Dev'''ices
* Emulation
contains files used for the 68k emulation (though E-UAE)
* Fonts
contains various systems fonts
* Internet
contains Internet-related files and configurations
* Kickstart
contains the kickstart modules
* L
contains hand'''l'''ers and filesystems
* Libs
contains dynamic '''Lib'''rairies of functions
* Locale
contains all files used to customise the system for your locality (catalogs, keymaps...)
* MUI
contains the files needed for programs that use the MUI third party graphic interface
* [[Prefs]]
contains the preference programs used to customise AmigaOS
* S
contains the system's '''S'''cripts
* SObjs
contains .so shared object library files
* Storage
contains other optional files, not currently used
* System
contains some programs used by the system itself (i.e. you don't need to run them yourself) or low-level programs like disk tools
* [[Utilities]]
contains several programs you can use to achieve some tasks on AmigaOS

= Motorola 680x0 Emulators =

For a long time Amigas have had the famous Motorola 680x0 processors as the central unit for execution. Unfortunately the time of the 680x0 series is passing in favor of other architectures. The new era of processors reached the Amiga some time ago, when expansion boards became available for extending the Classic systems with the raw power of a PowerPC processor.

In the old operating system (AmigaOS 3.x) it was not possible to gain the full advantage of the new processors. The system itself and most of the applications required the original Motorola 680x0 processor. There was no 680x0 emulation available for the PowerPCs, so the 680x0 could not be "switched off".

Thus the new processors remained as a powerful, but mostly unused adjunct to the main 680x0 processor. "Native" PowerPC programs were rare, and every time a PowerPC program called the system, a so called "context switch" occurred between the 680x0 and PowerPC code, often causing a large performance penalty.

The new Amiga platform is based on the PowerPC processor family, therefore the new version of the AmigaOS has to smooth the transition from the 680x0 series, which is achieved by emulating the old processor architecture. The operating system itself is written almost 100 percent for the PowerPC processors, but the 680x0 legacy applications require an emulated 680x0 processor.

== Two 680x0 Emulators ==

In version 4.0 of AmigaOS, two different emulators were implemented; one is the successor of BlackBox emulation, it is an interpretive emulator, thus the emulation speed is mediocre. On the other hand it has a very low "reaction time", and is ideal for time critical parts, such as interrupts.

The other is Petunia, the "JIT emulator". A fast, but less compatible way of emulation of the legacy Motorola processors. It is intended mainly for emulating applications, and therefore, when execution of the application leaves the bounds of the application's code segment, emulation falls back to the interpretive method, where it does its job and returns to the JIT emulation again.

Dynamic recompilation (also called just-in-time compilation or simply JIT compilation) is a technique of translating foreign processor machine code to native machine code, "on the fly".

This technique is common nowadays, commonly applied in JAVA virtual machines, and it is also used with success in several emulators. In dynamic recompilation there is the possibility of runtime optimization of the emulated code by collecting statistics of the execution process. Therefore (theoretically) the final executed code can be even faster than the original code on its original processor.

== Features ==

Emulated opcodes:
* all user and supervisor level opcodes of the Motorola 68040
* all FPU opcodes of the Motorola 68881/68882

AmigaOS claims only 68020/68881 compatibility to applications because this is the safest compatibility level, but both emulators are compatible with the machine code up to the level of 68040/060 processors.

At compile time, a low level flag and branch control analysis allows on-the-fly optimizations of compiled code.

== Removing the JIT Emulator ==

Using the dynamic translation requires a lot more memory than the interpretive emulation. The translated code needs to be stored somewhere, not to mention the data collection tables.

If speed is not as important as the memory consumption of the system, then the JIT emulator can be removed, leaving the job to the interpretive emulator.

Thanks to the modular design of AmigaOS kickstart, all you need to do is edit the "Sys:Kickstart/Kicklayout" file, simply put a semicolon (;) at the beginning of the module line of Petunia.library.kmod. After rebooting the system from cold, the JIT emulator will not be reloaded. Make sure that you alter the appropriate configuration in the Kicklayout file, there may be several alternative configurations, with different names like "DefaultJIT", or "DefaultNoJIT".

== Configuring the Emulators ==

Petunia cooperates with a so called "black list". By default, Petunia emulates every 680x0 program or library that is loaded by DOS.library/LoadSeg function, but if an executable or library shows incompatibilities with Petunia, then it can be explicitly inhibited from the dynamic recompilation by specifying it in a list.

If an executable needs to be added to the list, then it can be done by extending the file "DEVS:applications.dos" with the '''Compatibility''' preferences program from the Prefs drawer of the system. Adding a program name to the list and checking it will prevent Petunia from emulating that program, and it will be interpreted instead by the built-in interpreter.

Removing a program from the list or unchecking (thus allowing Petunia to emulate it again) can be done with the same preferences program.

Please note: some programs consist of multiple executables (shared libraries, plugins). If you want to fully disable the translation of such programs, then every part must be added to the list.

For example to disable UnArc fully, you would have to add to the list all files from libs:xad and also xadmaster.library.

= AmigaOS boot procedure =

Classic Amigas with PowerPC accelerators, the original AmigaOne SE/XE and the Sam series of Amigas all use the Second Level Booter (SLB) to read their Kickstart modules from the system volume. The newer A-Eon machines (X1000, X5000, A1222) all use a loader called AmigaBoot. In the X1000, AmigaBoot must be read from an FFS partition, while in the later machines, it is stored in the on-board CF card. The process of loading the kickstart modules is the same in all cases.

Basically a computer with AmigaOS does the following when the power button is pushed:

* [[File:Uboot.jpg|200px]]
The BIOS ([[UserDoc:BIOS|Uboot]] or [[UserDoc:BIOS|CFE]]) of the computer initialises the hardware: graphic card, USB ports... At this point, the monitor wakes up and the first information is displayed. This shows if hardware is correctly recognised. As an example you can see if a hard drive is correctly connected into the machine and your BIOS is correctly set up to make this drive useable.
* Depending on the machine type, the BIOS will look on the harddisk to find the Second Level Booter (SLB) or AmigaBoot, or will execute the AmigaBoot program from the on-board NVRAM. Whereas the BIOS does not know about AmigaOS disk structure, the SLB/AmigaBoot can ''understand'' the AmigaOS partitions and file systems. In other words, it is the link between the BIOS and the rest of the boot procedure. Its goal is also to give you the ability to start several configurations present on the same drive.
* [[File:SLB.png|200px]]
SLB/AmigaBoot analyses all Amiga partitions on the system disk. It reads each system configuration it finds on the partition and displays them all for the user to select one to load. AmigaBoot (not SLB) also displays configurations from Kickstart/Kicklayout files on every "bootable" partition.
The user can [[UserDoc:How_AmigaOS_Works#Control_of_the_Kickstart|define]] many different kickstart configurations to choose from. Also both AmigaOS and Linux can be selected for boot.
* [[File:Kmods loading.png|200px]]
SLB/AmigaBoot loads the kickstart files of the selected configuration and executes the '''Loader''' module
* '''Loader''' executes the kickstart modules (Exec, devices, libraries...)
* AmigaOS becomes alive displaying the AmigaOS boot picture on the monitor
* The AmigaDOS library executes the [[UserDoc:System_Scripts#startup-sequence|startup-sequence]] script found on the system volume
* The Startup-sequence will be executed and all commands it contains are executed. It means that starting from here the boot procedure is easy to follow and understand.
* The Workbench is started

At this point the user can use his/her computer.

= How to make a Bootable USB Memory Stick for AmigaOS 4.1 =

By Julian Margetson ("Spectre660")

Prerequisites:
* USB memory stick of 2 GB or less in size.
* It is best to only have one USB mass storage device connected while you are creating your bootable USB memory stick.
* Plug the USB memory stick into a USB port on your machine.
* Note that the device will be formatted so make sure that you use an empty memory stick or one that does not contain any data that you need or backup the contents before you begin.

Procedure:
# You use Media Toolbox in the System: drawer to prepare the USB stick. On starting Media Toolbox select ''usbdisk.device'' as the device to use.
# Make certain that you have selected usbdisk.device and not any other device.
# Click on "Start"
# You will see the usb mass storage unit connected in a list.
# Make sure that the Unit type displayed for the USB memory stick is "Removable hard disk"
# Select that Unit by clicking on it.
# The first thing that you need to do is to install the RDB onto the USB Memory Stick.
# Click on the "Install" button.
# A window Labeled "RDB/disk geometry editing" comes up.
## Towards the bottom of the window is the "AmigaOne boot code (SLB)" section.
## Select the "Install" button .
## A file requester "Select AmigaOne Boot Code" now comes up with the Drawer choice defaulting to "l:"
## Select file "slb_v2".
## Select Ok.
## You are now returned to the "RDB/disk geometry editing window".
## Select "Ok-accept changes".
# You are now returned to the display showing the attached USB unit.
# Select "Edit partitions and Filesystems". You will now see the Window 'Editing partitions for disk"
# Select "Add partition"
# This defaults to using the whole device as a single partition.
# It is possible to use create more partitions but for this tutorial we will only use one.
# You now need to give the partition a unique name (e.g. USB0 or something that is different from any of the existing partitions on your hard drive). This is done by changing the default DH0 in the "Name" box.
# Now make sure that the Boxes "Automount" and "Bootable" are selected and show the "Tick mark".
# You need to set "Boot priority" to higher than the boot priority of your hard drive boot partition(s). This is done by increasing Boot priority by clicking on the "+" to the right of the "boot priority" box. Normally you can set the boot priority to 2 .
# Next it is time to select the file system to use.
# Select "Select filesystem/edit details".
# The Window "Editing details for partition 'USB0'" ,or whatever partition name you used, comes up.
## Select the file system that you are going to use by selecting the pull down menu under "Filesystem chooser".
## Only filesystems SFS/00 or SFS/02 will work for a bootable device.
## The option that gives the most flexibility at the moment is SFS/00 as a USB stick in this format can be read from and written to using another compatible system in the event that you need to make modifications after it is created without a booting AmigaOS 4.1 machine.
## Next select Blocksize from the "Blocksize" pull down menu. 512 is the correct size to use.
## Now Select "Ok-accept changes".
## Your are now returned to the "Edit partitions for disk" window.
## Again select "Ok-accept changes"
# You are now returned to the window showing the USB mass storage unit list.
# Select "Save to disk"
# A requester pops up with the options "Yes, Save." or "No!"
# Select the "Yes, save." option.
# You now close Media Toolbox by clicking on the close icon (X) on the left of the Media Toolbox window.
# This will give you a requester advising that you need to reboot the machine for the changes to take effect. At this point you need to remove the USB memory stick for the machine. If you do not then the Machine will attempt boot from it before it is formatted and the required Kickstart and AmigaOS 4.1 files are copied to it.
# Select "Yes, reboot NOW!".
# Once you have rebooted connect your USB Memory Stick to a USB port.
# A disk icon "USB0:Uninitialized" (or whatever partition name you used) appears on Workbench.
# You now need to format the device.
# To format Select this Icon and go to the Workbench "Icons" menu .
# Select "Format Disk"
# You can give the USB Memory Stick a unique name and select whether you want a Trashcan or not.
# You can use either a full Format or a Quick Format. Full Format may take a few minutes.
# Once formatted the USB Memory Stick is ready for you to copy the required files from you hard drive or AmigaOS Install CD to it in order to boot AmigaOS 4.1 from it.

Main Page

2023-10-03T15:15:49Z

Brian Deneen: /* For Users */ removed "the" before "AmigaDOS" as redundant

= Welcome to the AmigaOS Documentation Wiki =

This is the AmigaOS Documentation Wiki. Here we collect all information for users and developers of AmigaOS version 4.0 and beyond.

== For Users ==
The [[UserDoc:Main|User Documentation Section]] is meant as a starting point for users. It begins by explaining the concepts of AmigaOS, AmigaDOS commands and the Workbench environment. It shows how to use Menus, the Keyboard Shortcuts available, and later how to configure the Workbench and AmigaOS from the look and feel of the desktop (e.g. changing the background image) to more comprehensive tasks such as setting up a network, configuring Sound Cards and similar information.

== For Developers ==
Documentation is organized into multiple sections. The [[DeveloperDoc:Main|Developer Section]] contains documentation that is useful for developing applications, device drivers, games and other programming projects on AmigaOS. The [[Tutorials:Main|Tutorial Section]] contains a couple of hands-on tutorials that are intended to allow beginning developers to get into programming with step-by-step examples. Finally, the [[Autodocs:Main|Autodocs section]] contains the well-known ''autodocs'', function-by-function documentation of libraries and devices in the AmigaOS system.

== For Wiki Editors ==

The [[EditorDoc:Main|Editor Documentation Section]] is meant for editors to communicate with each other on the do's and don'ts of editing this wiki.

== Credits ==

Thank you to our [[Wiki Author Credits|contributors]] that helped with the material found on this wiki.

AmigaDOS Introduction

2016-09-17T01:34:55Z

Brian Deneen: /* About AmigaDOS */ replaced "memorize" with "data storage"

[[Category:DOS]]{{WIP}}
= About AmigaDOS =

AmigaDOS is the name given to a subsystem group of modules which give to the AmigaOS capability to handle I/O with data storage units like hard disks, SSD etc.

AmigaDOS extends AmigaOS capabilities with:

*[[DOS Library|dos.library]]: the AmigaDOS core library, it gives many utility functions to manage I/O of files, directories, processes, etc...;
*'''File System''': an AmigaDOS (dos.library) process which handles how system organizes data on phisical memory units like hard disks, SSD, etc...;
*'''CLI''': Command Line Interface for user with which he can interact with AmigaDOS processes without use of GUI paradigm;

AmigaDOS provides a process that you can use, called '''Command Line Interface''' or '''Shell'''. There may be several Shell processes running simultaneously, numbered from 1 onwards. The Shell processes read '''commands'''
and then execute them. To make additional Shell processes, you use the NEWSHELL or RUN commands. To remove a Shell process use the ENDSHELL command. (You can find a full description of these commands in Chapter 2).

= Console Handling =

You can direct information that you enter at the terminal to a Command
Line Interface (Shell) that tells AmigaDOS to load a program, or you can
direct the information to a program running under that Shell. In either
case, '''console''' (or '''terminal''') '''handler''' processes input and output. This
handler also performs local line editing and certain other functions. You
can type ahead as many as 512 characters - the maximum line length.

To correct mistakes, you press the BACKSPACE key. This erases the last
character you typed. To rub out an entire line, hold down the Ctrl key
while you press X. This '''control combination''' is referred to from this point
on in the manual as Ctrl-X. You may also use the left and right cursor
keys to move within the command line to insert or remove characters if you
make a mistake.

You can also search for the most recent occurrence of a specific command
by typing the command line, or the beginning of it, then pressing Shift-Up
(or Ctrl-R). For instance, if you type DIR and press Shift-Up, you will be
returned to the last command to perform a DIR of any directory. Pressing
Shift-Down moves you to the bottom of the history buffer, leaving the
cursor on a blank line.

In addition to command line editing, the Shell also provides command
history, which allows you to recall previously-entered command lines, edit
them, and re-enter them. This is useful when you want to repeat a command
or enter several very similar commands.

The shell uses a 2K command line buffer to retain command lines. The
exact number of lines varies depending on [the] lengths of the lines
actually stored. When the buffer fills up, the oldest lines are lost. You
access lines in the buffer through the up and down cursor keys:

{|
| up cursor || Moves backwards in the history buffer (earlier lines).
|-
| down cursor || Moves forwards in the history buffer (later lines).
|}

If you type anything, AmigaDOS waits until you have finished typing before
displaying any other output. Because AmigaDOS waits for you to finish, you
can type ahead without your input and output becoming intermixed. AmigaDOS
recognizes that you have finished a line when you press the RETURN key.
You can also tell AmigaDOS that you have finished with a line by
cancelling it. To cancel a line, you can either press Ctrl-X or press
BACKSPACE until all the characters on the line have been erased. Once
AmigaDOS is satisfied that you have finished, it starts to display the
output that it was holding back. If you wish to stop the output so that
you can read it, simply type any character (pressing the space bar is the
easiest), and the output stops. To restart output, press BACKSPACE,
Ctrl-X, or RETURN. Pressing RETURN causes AmigaDOS to try to execute the
command line typed after the current program exits.

AmigaDOS recognizes Ctrl-\\ as an end-of-file indicator. In certain
circumstances, you use this combination to terminate an input file. (For a
circumstance when you would use Ctrl-\\, see "Understanding Device Names",
below).

If you find that strange characters appear on the screen when you type
anything on the keyboard, you have probably pressed Ctrl-O by mistake.
AmigaDOS recognizes this control combination as an instruction to the
console device (CON:) to display the alternative character set. To undo
this condition, you press Ctrl-N. Any further characters should then
appear as normal. You could press Esc-C to reset the console. This clears
the screen and displays normal text.

The table below summarizes the editing capabilities of the Amiga's Shell
interface:

{| class="wikitable"
! Key
! Shell Editing Commands
|-
| left cursor || Moves cursor one character to the left.
|-
| right cursor || Moves cursor one character to the right.
|-
| Shift-left cursor || Moves cursor to the beginning of the line.
|-
| Shift-right cursor || Moves cursor to the end of the line.
|-
| Backspace || Deletes the character to the left of the cursor.
|-
| Del || Deletes the character highlighted by the cursor.
|-
| Ctrl-H || Deletes the last character (same as BACKSPACE).
|-
| Ctrl-M || Processes the command line (same as RETURN).
|-
| Ctrl-J || Adds a line feed.
|-
| Ctrl-W || Deletes the word to the left of the cursor
|-
| Ctrl-X || Deletes the current line.
|-
| Ctrl-K || Deletes everything from the cursor forwards to the end of the line.
|-
| Ctrl-Y || Replaces the characters deleted with Ctrl-K.
|-
| Ctrl-U || Deletes everything from the cursor backwards to the start of the line.
|-
| Space bar (or any printable character) || Suspends output (stops scrolling).
|-
| Backspace || Resumes output (continues scrolling).
|-
| Ctrl-C || Sends a BREAK command to the current process (halts the process).
|-
| Ctrl-D || Sends a BREAK command to the current script (halts the script).
|-
| Ctrl-S || Suspends output.
|-
| Ctrl-Q || Resumes output if it was suspended with Ctrl-S.
|-
| Ctrl-\ || Closes the Shell window.
|}

Finally, AmigaDOS recognizes all commands and argument typed in either
upper or lower case. AmigaDOS displays a filename with the characters in
the case used when it was created, but finds the file no matter what
combination of cases you use to specify the filename.

= Using the Filing System =

This section describes the AmigaDOS filing system. In particular, it
explains how to name, organize, and recall your files.

A file is the smallest named object used by AmigaDOS. The simplest
identification of a file is by its filename, discussed below in "Naming
Files". However, it may be necessary to identify a file more fully. Such
an identification may include the device or volume name, and/or directory
name(s) as well as the filename. These will be discussed in [the]
following sections.

== Naming Files ==

AmigaDOS holds information on disks in a number of files, named so that
you can identify and recall them. The filing system allows filenames to
have up to 30 characters, where the characters may be any printing
character except slash (/) and colon (:). This means that you can include
space ( ), equals (=), plus (+) and double quote ("), all special
characters recognized by the CLI, within a filename. However, if you use
these special characters, you must enclose the entire filename within
double quotes. To introduce a double quote character within a filename,
you must type an asterisk (*) immediately before that character. In
addition, to introduce an asterisk, you must type another asterisk. This
means that a file named:

<pre>
A*B = C"
</pre>

should be typed as follows:

<pre>
"A**B = C*""
</pre>

for the CLI to accept it.

{| class="wikitable"
| ''Note:'' This use of the asterisk is in contrast to many other operating systems where it is used as a universal ''wild card''. An asterisk by itself in AmigaDOS represents the keyboard and the current window. For example,

<pre>
COPY filename TO *
</pre>

copies the filename to the screen. On the Amiga, the universal wild card is #?.
|}

When spaces are used within a file, directory, or device name, quotes
are required when accessing the name. For example,

<pre>
COPY "df0:My file" TO ram:
</pre>

Avoid spaces before or after filenames because they may cause confusion.

== Using Directories ==

The filing system also allows the use of directories as a way to group files together into logical units. For example, you may use two different
directories to separate program source from program documentation, or to keep files belonging to one person distinct from those belonging to another.

Each file on a disk must belong to a directory. An empty disk contains one directory, called the root directory. If you create a file on an empty disk, then that file belongs to the root directory. However, directories may themselves contain other directories. Each directory may therefore contain files, or yet more directories, or a mixture of both. Any filename is unique only within the directory it belongs to, so that the file "fred" in the directory "bill" is a completely different file from the one called "fred" in the directory "mary".

This filing structure means that two people sharing a disk do not have to worry about accidentally overwriting files created by someone else, as
long as they always create files in their own directories.

{{Note|title=WARNING|text=When you create a file with a filename that already exists, AmigaDOS deletes the previous contents of that file. No message to that effect appears on the screen. You can also use this directory structure to organize information on the disk, keeping different sorts of files in different directories.}}

An example might help to clarify this. Consider a disk that contains two directories, called "bill" and "mary". The directory "bill" contains two files, called "text" and "letter". The directory "mary" contains a file called "data" and two directories called "letter" and "invoice". These subdirectories each contain a file called "jun18". [This figure] represents this structure as follows:

ROOT
|
+----------+----------+
| |
BILL MARY
| |
+----+----+ +--------+--------+
| | | | |
TEXT LETTER DATA LETTER INVOICE
| |
JUN18 JUN18

{{Note|text=The directory "bill" has a file called "letter", while the directory "mary" contains a directory called "letter". However, there is no confusion because both...are in different directories. There is no limit to the depth that you can "nest" directories.}}

To specify a file fully, you must include the directory that owns it, the directory owning that directory, and so on. To specify a file, you
give the names of all the directories on the path to the desired file. To separate each directory name from the next directory or filename, you type a following slash (/). Thus, the full specification of the data files on the disk shown...above is as follows:

<pre>
bill/text
bill/letter
mary/data
mary/letter/jun18
mary/invoice/jun18
</pre>

== Setting the Current Directory ==

A full file description can get extremely cumbersome to type, so the
filing system maintains the idea of a current directory. The filing
system searches for files in this current directory. To specify the
current directory, you use the CD ('''C'''urrent '''D'''irectory) command. If you have
set "mary" as your current directory, then the following names would be
sufficient to specify the files in that directory:

<pre>
data
letter/jun18
invoice/jun18
</pre>

You can set any directory as the current directory. To specify any files
within that directory, simply type the name of the file. To specify files
within subdirectories, you need to type the names of the directories on
the path from the current directory specified.

All the files on the disk are still available even though you've set up
a current directory. To instruct AmigaDOS to search through the
directories from the root (top level) directory of a volume (disk or
partition), you type a colon (:) at the beginning of the file description.
Thus, when your file description [sic] has the current directory set to
"mary", you can also obtain the file "data" by typing the description
":mary/data". Using the current directory method simply saves typing,
because all you have to do is specify the filename "data".

To obtain the other files on the disk, first type ":bill/text" and
":bill/letter", respectively. Another way might be to CD or type / before
the filename. Slash [(/)] does not mean "root" as in some systems, but
refers to the directory above the current directory. AmigaDOS allows
multiple slashes. Each slash refers to the level above. So a UNIX ../ is a
/ in AmigaDOS. Similarly, an MS-DOS ..\\ is a / in AmigaDOS. Thus, if the
current directory is ":mary/letter", you may specify the file
":mary/invoice/jun18" as "/invoice/jun18". To refer to the files in
":bill", you could type:

<pre>
CD :bill
</pre>

or

<pre>
CD //bill
</pre>

Then you could specify any file in "bill" with a single filename. Of
course, you could always use the // feature to refer directly to a
specific file. For example,

<pre>
TYPE //bill/letter
</pre>

displays the file without your first setting "bill" as the current
directory. To go straight to the root level, always type a colon (:)
followed by a directory name. If you use slashes, you must know the exact
numbewr of levels back desired.

== Setting the Current Device ==

Finally, you may have many disk drives. Each [floppy] disk device has a name in the form DFn (for example DF1), where the "n" refers to the number of the device. (Currently, AmigaDOS accepts the device names DF0 to DF3.) Each individual disk is also associated with a unique name, known as a volume name (see below for more details).

In addition, the logical device SYS: is assigned to the disk you started the system up from. You can use this name in place of a disk device name (like DF0:).

The current directory is also associated with a current drive, the drive where you may find the [current] directory. As you know, prefacing a file description with a colon serves to identify the root of the current drive. However, to give the root directory of a specific drive, you precede the colon with the drive name. Thus, you have yet another way of specifying the file "data" in directory "mary", that is "DF1:mary/data". This assumes that you have inserted the disk into drive DF1. So, to reference a file on the drive DF0 called "project-report" in directory "peter", you would type "DF0:peter/project-report", no matter which directory you had set as the current one.

{{Note|text=When you refer to a disk drive or any other device, on its own or with a directory name, you should always type the colon; for example, DF1:.}}

This table illustrates the structure of a file description

{| class="wikitable"
! Left of the :
! Right of the :
! Right of a /
|-
| Device name or Volume name
| Directory name or Filename
| Subdirectory name or Filename
|}

Here are some examples of valid file descriptions.

<pre>
SYS:commands
DF0:bill
DF1:mary/letter
DF2:mary/letter/jun18
DOC:report/section1/figure
FONTS:silly-font
C:cls
</pre>

To gain access to a file on a particular disk, you can type its unique name, which is known as the disk's volume name, instead of the device
name. For instance, if the file is on the disk "MCC", you can specify the same file by typing the name "MCC:peter/project-report". You can use the volume name to refer to a disk regardless of the drive it is in. You assign a volume name to a disk when you format it. You can also change the volume name using the RELABEL command.

A device name, unlike a volume name, is not really part of the name. For example, AmigaDOS can read a file you created on DF0: from another drive, such as DF1:, if you place the disk in that drive, assuming of course that the drives are interchangeable. That is, if you created a file called "bill" on a disk in drive DF0:, the file is known as "DF0:bill". If you then move the disk to drive DF1:, AmigaDOS can still read the file, which is then known as "DF1:bill".

== Attaching a Filenote ==

Although a filename can give some information about its contents, it is
often necessary to look in the file itself to find out more. AmigaDOS
provides a simple solution to this problem. You can use the command called
FILENOTE to attach an associated comment. You can make up a comment of up
to 80 characters (you must enclose comments containing spaces in double
quotes). Anything can be put in a file comment: the day of the file's
creation, whether or not a bug has been fixed, the version number of a
program, and anything else that may help to identify it.

You must associate a comment with a particular file - not all files have
them. To attach comments, you use the FILENOTE command. If you create a
new file, it will not have a comment. Even if the new file is a copy of a
file that has a comment, the comment is not copied to the new file.
However, any comment attached to a file which is overwritten is retained.
To write a program to copy a file and its comment, you'll have to do some
extra work to copy the comment.

When you rename a file, the comment associated with it doesn't change.
The RENAME command only change the name of the file. The file's contents
and comment remain the same regardless of the name change.

== Understanding Device Names ==

Devices have names so that you can refer to them by name. Disk names such as DF0: are examples of device names. Note that you may refer to device names, like filenames, using either upper or lower case. For disks, you follow the device name by a filename because AmigaDOS supports files on these devices. Furthermore, the filename can include directories because AmigaDOS also supports directories.

You can also create files in memory with the device called RAM:. RAM: implements a filing system in memory that supports any of the normal filing system comands.

Once the RAM: device exists, you can, for instance, create a directory to copy all the commands into memory. To do this, type the following
commands:

<pre>
MAKEDIR ram:c
COPY sys:c TO ram:c
ASSIGN C: ram:c
</pre>

You could then look at the output with DIR RAM:. It would include the direcotry "c" (DIR lists this as "c (dir)"). This would make loading commands very quick but would leave little room in memory for anything else. Any files in the RAM: device are lost when you reset the machine.

AmigaDOS also provides a number of other devices that you can use instead of a reference to a disk file. The following paragraphs describe
these devices including NIL:, SER:, PAR:, PRT:, CON:, and RAW:. In particular, the device NIL: is a dummy device. AmigaDOS simply throws away
output written to NIL:. While reading from NIL:, AmigaDOS gives an immediate "end-of-file" indication. For example, you would type the following:

<pre>
EDIT abc TO nil:
</pre>

to use the editor to browse through a file, while AmigaDOS throws away the edited output.

You use the device called SER: to refer to any device connected to the serial line (often a [modem or] printer). Thus, you would type the following command sequence:

<pre>
COPY xyz TO ser:
</pre>

to instruct AmigaDOS to send the contents of the file "xyz" down the serial line. Note that the serial device only copies in multiples of 400
bytes at a time. Copying with SER: can therefore appear granular.

The device PAR: refers to the parallel port in the same way.

AmigaDOS also provides the device PRT: (for PRinTer). PRT: is the printer you chose in the Preferences program. In this program, you can define your printer to be connected through either the serial or parallel port. Thus, the command sequence:

<pre>
COPY xyz TO prt:
</pre>

prints the file "xyz", no matter how the printer is connected.

All output sent to PRT: is translated through the printer driver selected in Preferences. The printer driver will translate standard ANSI
escape codes into the specific code required by the printer. PRT: translates every linefeed character in a file to carriage return plus linefeed. Some printers, however, require files without translation. To send a file with the linefeeds as just linefeeds, you use PRT:RAW instead of PRT:.

AmigaDOS supports multiple windows. To make a new window, you can specify the device CON:. The format for CON: is as follows:

<pre>
CON:x/y/width/height/[title]
</pre>

where "x" and "y" are coordinates, "width" and "height" are integers describing the width and height of the new window, and "title", which is
optional, is a string. The title appears on the window's title bar. You must include all the slashes, including the last one. Your title can
include up to 30 characters (including spaces). If the title has spaces, you must enclose the whole description in double quotes (") as shown in
the following example:

<pre>
"CON:20/10/300/100/my window"
</pre>

There is another window device called RAW:, but it is of little use to the general user. You can use RAW: to create a raw window device similar to CON:. However, unlike CON:, RAW: does no character translation and does not allow you to change the contents of a line. That is to say, RAW: accepts input and returns output in exactly the same form that it was originally typed. This means characters are sent to a program immediately without letting you erase anything with the BACKSPACE key. You usually use RAW: from a program where you might want to do input and output without character translation.

{{Note|title=WARNING|text=RAW: is intended for the advanced user. Do not use RAW: experimentally.}}

There is one special name, which is * (asterisk). You use this to refer to the current window, both for input or for output. You can use the COPY command to copy from one file to another. Using *, you can copy from the current window to another window, for example,

<pre>
COPY * TO CON:20/20/350/150/
</pre>

from the current window to the current window, for example,

<pre>
COPY * TO *
</pre>

or from a file to the current window, for example,

<pre>
COPY bill/letter TO *
</pre>

AmigaDOS finishes copying when it comes to the end of the file. To tell AmigaDOS to stop copying from *, you must give the Ctrl-\ combination.
Note that * is NOT the universal wild card.

== Using Directory Conventions and Logical Devices ==

In addition to the aforementioned physical devices, AmigaDOS supports a
variety of useful ''logical devices''. AmigaDOS uses these devices to find
the files that your programs require from time to time. (So that your
programs can refer to a standard device name regardless of where the file
actually is.) All of these "logical devices" may be reassigned by you to
reference any directory.

The logical devices described in this section are as follows:

{| class="wikitable"
! Logical Device Name
! Description
! Directory
|-
| SYS: || System disk root directory || SYS:
|-
| C: || Commands directory || SYS:C
|-
| L: || Library directory || SYS:L
|-
| S: || Script directory || SYS:S
|-
| LIBS: || Directory for OpenLibrary() calls || SYS:LIBS
|-
| DEVS: || Directory for OpenDevice() calls || SYS:DEVS
|-
| FONTS: || Loadable fonts for OpenFonts() calls || SYS:FONTS
|-
| T: || Temporary workspace || RAM:T
|}

=== SYS: ===

Typical directory name: Workbench:

"SYS" represents the '''SYS'''tem disk root directory. When you first start up
the Amiga system [from floppy], AmigaDOS assigns SYS: to the root
directory name of the disk in DF0:. If, for instance, the disk in drive
DF0: has the volume name Workbench, then AmigaDOS assigns SYS: to
Workbench:. After this assignment, any programs that refer to SYS: use
that disk's root directory.

=== C: ===

Typical directory name: Workbench:C

"C" represents the '''C'''ommands direcotry. When you type a command to the CLI
(DIR, for example), AmigaDOS first searches for that command in your
cuurent directory. If the system cannot find the command in the current
directory, it then look for "C:DIR". So that, if you have assigned "C:" to
another directory (for example, "Boot_disk.c"), AmigaDOS reads and
executes from "Boot_disk:c/DIR".

=== L: ===

Typical directory name: Workbench:L

"L" represents the '''L'''ibrary directory. This directory keeps the overlays
for large commands and nonresident parts of the operating system. For
instance, the disk-based run-time libraries (Aux-Handler, Port-Handler,
and so forth) are kept here. AmigaDOS requires this directory to operate.

=== S: ===

Typical directory name: Workbench:S

"S" represents the '''S'''cript directory. This directory contains command
scripts that the EXECUTE command searches for and uses. EXECUTE first
looks for the script (or batch) file in your current directory. If EXECUTE
cannot find it there, it looks in the directory that you have assigned S:
to.

=== LIBS: ===

Typical directory name: Workbench:Libs

IExec->OpenLibrary() looks here for the library if it is not already loaded in memory.

=== DEVS: ===

Typical directory name: Workbench:Devs

IExec->OpenDevice() looks here for the device if it is not already loaded in memory.

=== FONTS: ===

Typical directory name: Workbench:Fonts

OpenFonts() looks here for your loadable fonts if they are not already loaded in memory.

=== T: ===

Typical directory name: RAM:T

You use this directory to store temporary files. Programs such as editors place their temporary work files, or backup copies of the last file edited, in this directory. If you run out of space on a disk, this is one of the first places you should look for files that are no longer needed.

=== During booting ===

When the system is first booted, AmigaDOS initially assigns C: to the :C
directory. This means that if you boot with a disk that you had formatted
by issuing the command:

<pre>
FORMAT DRIVE DF0: NAME "My.Boot.Disk"
</pre>

SYS: is assigned to "My.Boot.Disk". The "logical device" C: is assigned to
the C: directory on the same disk (that is, My.Boot.Disk:c). Likewise, the
following assignments are made:

<pre>
C: My.Boot.Disk:c
L: My.Boot.Disk:l
S: My.Boot.Disk:s
LIBS: My.Boot.Disk:libs
DEVS: My.Boot.Disk:devs
FONTS: My.Boot.Disk:fonts
</pre>

If a directory is not present, the corresponding logical device is
assigned to the root directory.

If you have a non-bootable hard disk (here called DH0:) and you want to
use the system files on it, you must issue the following commands to the
system:

<pre>
ASSIGN SYS: DH0:
ASSIGN C: DH0:c
ASSIGN L: DH0:l
ASSIGN S: DH0:s
ASSIGN LIBS: DH0:libs
ASSIGN DEVS: DH0:devs
ASSIGN FONTS: DH0:fonts
</pre>

If your hard disk is bootable, you don't need to make these assigns since
the system handles it for you.

Please keep in mind that assignments are global to all Shell processes.
Changing an assignment within one window changes it for all windows.

If you want to use your own special font library, type:

<pre>
ASSIGN FONTS: "Special font disk:myfonts"
</pre>

If you want your commands to load faster (and you have memory "to burn"),
type:

<pre>
MAKEDIR ram:c
COPY sys:c ram:c ALL
ASSIGN c: ram:c
</pre>

This copies all of the normal AmigaDOS commands to the RAM disk and
reassigns the commands directoy so that the system finds them there.
Another way to speed up AmigaDOS commands is by making them resident.
See the description of the RESIDENT command.

= Using AmigaDOS Commands =

An AmigaDOS command consists of the command name and its arguments, if any. To execute an AmigaDOS command, you type the command name and its
arguments after the Shell prompt.

When you type a command name, the command runs as part of the Command Line Interface (Shell). You can type other command names ahead, but AmigaDOS does not execute them until the current command has finished. When a command has finished, the current Shell prompt appears. In this
case, the command is running interactively.

The Shell prompt is initially n> where n is the number of the Shell process. However, it can be changed to something else with the PROMPT
command.

{{Note|title=WARNING|text=If you run a command interactively and it fails, AmigaDOS continues to execute the next command you typed anyway. Therefore, it can be dangerous to type many commands ahead. For example, if you type<br/>
COPY a TO b<br/>
DELETE a<br/>
and the COPY command fails (perhaps because the disk is full), then DELETE executes and you lose your file.}}

== Running Commands in the Background ==

You can instruct AmigaDOS to run a command, or commands, in the
background. To do this, you use the RUN command. This creates a new Shell
as a separate process of the same priority. In this case, AmigaDOS
executes subsequent command lines at the same time as those that have been
RUN. For example, you can examine the contents of your directory at the
same time as sending a copy of your text file to the printer. To do this,
type

<pre>
RUN TYPE text_file TO prt:
LIST
</pre>

RUN creates a new Shell and carries out your printing while you list your
directory files on your original Shell window.

You can ask AmigaDOS to carry out several commands using RUN. RUN takes
each command and carries it out in the given order. The line containing
commands after RUN is called a command line. To terminate the command
line, press RETURN. To extend your command line over several lines, type a
plus sign (+) before pressing RETURN on every line except the last. For
example,

<pre>
RUN JOIN text_file1 text_file2 AS text_file +
SORT text_file TO sorted_text +
TYPE sorted_text TO prt:
</pre>

If you want to start a command using RUN and then close the Shell window
from which it was launched, you will have to redirect input and output. To
do this use:

<pre>
RUN <NIL: >NIL: command
</pre>

== Executing Command Files ==

You can also use the EXECUTE command to execute command lines in a file
instead of typing them in directly. The Shell reads the sequence of
commands from the file until it finds an error the end of the file. If it
finds an error, AmigaDOS does not execute subsequent commands on the RUN
line or in the file used by EXECUTE, unless you have used the FAILAT
command. The Shell only
gives prompts after executing commands that have run interactively.

== Directing Command Input and Output ==

AmigaDOS provides a way for you to redirect standard input and output. You
use the > and < symbols as commands. When you type a command, AmigaDOS
usually displays the output from that command on the screen. To tell
AmigaDOS to send the output to a file, you can use the > command. To tell
AmigaDOS to accept the input to a program from the specified file rather
than from the keyboard, you use the < command. The < and > commands act
like traffic cops who direct the flow of information. For example, to
direct the output from the DATE command and write it to the file named
"text_file", you would type the following command line:

<pre>
DATE > text_file
</pre>

If you want to redirect output to a file that already exists use >>. For
example, to direct the output of the TYPE command to a file that already
exists use:

<pre>
TYPE >>more_text original_text
</pre>

The text stored in the file original_text will be appended to any text
that is already stored in the file my_text. Under 2.0 and later versions
of AmigaDOS, if you redirect output to a file using >> and the file does
not exist, then the file will be created for you.

= Interrupting AmigaDOS =

AmigaDOS allows you to indicate four levels of attention interrupt with Ctrl-C, Ctrl-D, Ctrl-E, and Ctrl-F. To stop the current command from
whatever it was doing, press Ctrl-C. In some cases, such as EDIT, pressing Ctrl-C instructs the command to stop what it was doing and then to return to reading more EDIT commands. To tell the CLI to stop a command sequence initiated by the EXECUTE command as soon as the current command being executed finishes, press Ctrl-D. Ctrl-E and Ctrl-F are only used by certain commands in special cases.

{{Note|text=It is the programmer's responsibility to detect and respond to these interruption flags. AmigaDOS will not kill a program by itself.}}

= Restart Validation Process =

When you first insert a disk for updating, AmigaDOS creates a process at
low priority. This validates the entire structure on the disk. Until the
restart process has completed this job, you cannot create files on the
disk. It is possible, however, to read files.

Older versions of AmigaDOS (1.3 and earlier) do some additional
processing when a disk is inserted. When the restart process completes,
AmigaDOS checks to see if you have set the system date and time. To set
the date and time, you use the DATE command, the SETCLOCK command or the
TIME command. If you do not specify the system date,
AmigaDOS sets the system date to the date and time of the most recently
created file on the inserted disk. This ensures that newer versions of
files have more recent dates, even though the actual time and date will be
incorrect.

= Commonly Used Commands =

This manual describes the AmigaDOS and its commands. The Command Line
Interpreter (CLI) reads AmigaDOS commands typed into a CLI window and
translates them into actions performed by the computer. In this sense, the
CLI is similar to more "traditional" computer interfaces: you type in
commands and the interface displays text in return.

== Using the Shell ==

To use the Shell interface, select the Shell window and type the desired
Shell commands (described within this manual). The Shell window(s) may be
sized and moved just like many others. To close the Shell window, type
"ENDSHELL".

Not all programs or commands can be run under both the Workbench and the
Shell environment. Many of the AmigaDOS commands described in Chapter 2
can be run only from the Shell.

Throughout this book, the terms "CLI" and "Shell" are used to refer to
the special window where you can type in AmigaDOS. Although the terms are
used to mean the same thing, there is a slight difference. Just keep in
mind that the CLI and the Shell both refer to the place where you can type
in AmigaDOS commands.

= Some AmigaDOS Commands =

Alhough all the commands that are available through the Shell are
explained in deleted in Chapter 2 of this book, we have found that most
users will use very few of the advanced options. Therefore we have
provided a summary here showing various commands in their most common
form.

The commands summarized below (along with the actual AmigaDOS command
name) ask AmigaDOS to do such operations as:

* Copy a disk (DISKCOPY)
* Format a new disk (FORMAT)
* Make a formatted disk bootable (INSTALL)
* Create a CLI disk
* Relabel a disk (RELABEL)
* Look at the directories of a disk (DIR)
* Get information about files (LIST)
* Prevent a file from accidental deletion (PROTECT)
* Get information about a file system (INFO)
* Change a current directory (CD)
* Set the date and time (DATE)
* Redirect the output of a command (>)
* Type a text file to the screen (TYPE)
* Rename a file (RENAME)
* Delete a file (DELETE)
* Create a new directory (MAKEDIR)
* Copy files on a dual-drive system (COPY)
* Copy files on a single-drive system (COPY)
* Find files on a disk (DIR OPT A)
* Do something automatically at boot time (using Startup-Sequence)
* Tell AmigaDOS where to look for certain things (ASSIGN)
* Open a new Shell window (NEWSHELL)
* Close an existing Shell window (ENDSHELL)

== For a New User ==

For a new user, we suggest that you read and try each of these items in
sequence. Each command that is shown below leaves a test disk in a known
state so that the command that immediately follows will work exactly as
shown. Later, when you are more familiar with the system, the subsection
titles shown below will serve to refresh your memory.

== How to Begin ==

Before you begin this section, be sure you have two blank, double-sided
disks, and your Workbench disk. Before you begin, write protect your
master disk, and write enable the blank disks. Most of the commands given
below assume that you have a single-drive system; however, for [the]
convenience of those with dual-drive systems, the dual-drive version of
the command is occasionally given.

Commands that instruct AmigaDOS to execute are shown in the following
sections, indented from the left margin. After typing each command, press
the RETURN key to return control to AmigaDOS. Although the commands are
all shown in capital letters, this is simply to distinguish them from the
rest of the text. AmigaDOS will accept the commands in lower case as well
as upper case.

In the sections that follow, the notations "DF0:" and "drive 0" refer to
the disk drive that is built into the Amiga. The notation "DF1:" refers to
the first external 3½-inch disk drive. (Some systems use "DF2:" to refer
to the [second] external drive.)

You will occasionally see a semicolon [(;)] on a command line that you
are told to type. What follows the semicolon is treated as a comment by
AmigaDOS. Since AmigaDOS ignores the rest of the line, you don't need to
type the comment along with the command. It is for your information only.

For most commands, you can get a very limited form of help by typing the
command name, followed by a question mark (?) and pressing RETURN. It
shows you the "template" of a command, containing the sequence of
parameters it expects and the keywords it recognizes.

=== Copying a Disk ===

You can use this sequence to back up your system master disk or any other
disk.

For a one-disk system:

DISKCOPY FROM df0: TO df0:

For a two-disk system:

DISKCOPY FROM df0: TO df1:

Follow the instructions as they appear. For a single-drive system, you'll
be instructed to insert the master (FROM) disk. Then, as the copying
progresses, AmigaDOS asks you to insert the copy (TO) disk, swapping
master and copy in and out until all of the disk has been duplicated. For
a two-disk system, you'll be instructed to put the master disk into drive
DF0: (The built-in drive) and the copy disk onto which to copy into DF1:
(the first external drive).

Remove your master disk and put your master disk in a safe place. Leave
the copy write-enabled so that you can store information on it. Insert the
copy you have just made into the built-in drive [(DF0:)] and reboot your
system from the copy. (See "Making a Disk Bootable", below.)
After the reboot, reenter the CLI mode again.

=== Formatting a Disk ===

To try this command, your Workbench or CLI disk copy should be in drive 0,
and you should have a blank disk available.

Sometimes rather than simply copy a disk, you'll want to prepare a data
disk for your system. Then later you can copy selected files to this data
disk. Format your second blank disk by using the FORMAT command.

FORMAT DRIVE df0: NAME "AnyName"

Follow the instructions. You can format disks in either drive 0 (DF0:,
built into your Amiga) or an external drive.

After the format is completed, wait for the disk activity light to go
off and remove the freshly formatted disk. Reinsert your Workbench. The
formatted disk can now be used to hold data files. It is not bootable,
however.

=== Making a Disk Bootable ===

To try this command, your Workbench disk copy should be in drive 0, and
your should have your freshly formatted disk available.

A bootable disk is one that you can use to start up your Amiga following
the Kickstart process. You can change a formatted disk into a bootable
disk by typing the command:

INSTALL ?

AmigaDOS responds:

DRIVE/A,NOBOOT/S,CHECK/S

Remove your Workbench disk copy and insert the formatted disk. Then type:

df0:

and press RETURN. AmigaDOS writes boot sectors to the disk in DF0:. Now,
if you wait until the disk activity light goes out, you can then perform a
full reset (Ctrl-Amiga-Amiga). When the system reboots, you will go
directly into the CLI rather than into the Workbench.

Your formatted disk now contains a CLI and nothing else. This means that
although you see the interpreter, it can't perform any of the commands
shown in this section. A CLI needs several files before its commands can
be performed. All of the command files are located in the C directory of
your master disk.

=== Making a CLI Disk ===

There is another way to make a bootable disk that gives you a more useful
disk in that it leaves the CLI command directories intact. Here is a step-
by-step process to change a writable copy of a Workbench diskette into a
CLI disk:

1. Copy your Workbench disk.
2. Open the Shell as described above.
3. Select the Shell window and type the command:

RENAME FROM s/startup-sequence TO s/NO-startup-sequence

Now if you wait for the disk activity light to go off and perform a full
reset, your Workbench disk copy will have become a CLI disk. To restore
the Workbench, perform the rename again, but with the name sequence
reversed. You see, if AmigaDOS can't find a file with the exact name
"Startup-sequence" ins the "s" directory, it will enter command mode and
wait for you to type a command.

=== Relabeling a Disk ===

Before you try this command, your Workbench or CLI disk copy should be in
drive 0.

If, after either copying or formatting a disk, you are not satisfied
with the volume name you have given it, you can change the name of the
volume by using the RELABEL command:

RELABEL df0: DifferentName

This command changes the volume of the disk in drive DF0: to
"DifferentName".

=== Looking at the Directory ===

Before you try this command, your Workbench or CLI disk copy should be in
drive 0.

You look at the contents of a disk with [either of] the commands:

DIR or DIR df0:

This lists the contents of your current directory. You can list the
contents of a different directory by specifying the pathname for that
directory. For example, the command:

DIR df0:c or DIR c

lists the contents of the c (directory) on drive DF0:. Directories are
equivelent to the drawers you see when the Workbench screen is visible.

You can look at the directory of a different disk unit, if you have one,
by specifying its name. For example:

DIR df1:

lists the contents of a disk inserted in drive DF1:.

You can even look at the directory of a disk that isn't currently in the
drive by specifying its volume name. For example, the contents of that
freshly formatted disk whose name we changed can be displayed by the
command:

DIR DifferentName:

AmigaDOS will ask you to insert disk DifferentName into [any] drive so
that DIR can read it and report the contents of the directory. Don't do it
yet, however, because there are no files present for DIR to read. We'll
add some files later.

=== Using the LIST Command ===

To try this command, your Workbench or CLI disk copy should be in drive 0.

The DIR command tells you the names of files that are in your directory.
The LIST command provides additional information about those files. Type
the command:

LIST

AmigaDOS provides information about all files in the current directory,
including how large each file is, the protection flags for each file,
whether it is a file or a directory, and the date and time of its
creation.

If you specify the name of a directory with LIST, it lists information
about the files within that directory:

LIST c

In the second column after the filename you will see the protection flags
for the file. The acronym "rwed" refers to protection flags, for read,
write, execute, and delete. When each flag is set, using the PROTECT
command, a file is supposed to be readable, writable, executable, [and]
deletable.

=== Using the PROTECT Command ===

To try this command, your Workbench or CLI disk copy should be in drive 0.
This command protects (or unprotects) a file from being deleted
accidentally. Try the command

DATE >myfile
PROTECT myfile
LIST myfile

You will see that all of the protect flags have been set to "--------".
Now if you try:

DELETE myfile

AmigaDOS responds

"Not deleted - file is protected from deletion"

To reenable deletion of the file, type:

PROTECT myfile d

For more information about file protection flags, see the discussion of
the PROTECT command.

=== Getting Information About the File System ===

Your Workbench or CLI disk copy should still be in drive 0. Type the
command

INFO

It tells you how much space is used and how much is free on your disks,
whether they are read-only or read-write, and the name of the volume.
You can make more space on the disk by deleting files. You can change
the name of the volume by using the RELABEL command.

If you want to get information about a disk that isn't in your single
drive at the moment, issue the command as

INFO ?

AmigaDOS responds

DEVICE:

AmigaDOS has loaded the INFO command from your CLI disk and shows you the
template for the command. The response "DEVICE:" says that you can enter
any device name to get information about it. But you don't have to type
anything other than a RETURN key to have it perform the command. Remove
your CLI disk and insert the disk on which you want INFO to operate. Wait
for the disk activity light to go on and off. Then press RETURN. AmigaDOS
gives you INFO about this other disk. This works for DIR as well as INFO.

=== Changing Your Current Directory ===

Until now, we have only stayed at the "root" or topmost hierarchical level
of the disk directory. You will find more information about the directory
tree structure in "Using Directories" earlier. To see the level at which
you are currently positioned in your directory tree, you use the command:

CD

To change to a different current directory, you tell the system which
directory is to become the current one. For example, when you did a DIR
command on DF0:, the CLI disk, you say an entry "c (dir)". If you want to
make this directory the current one, you issue the command:

CD df0:c

Now when you issue the command DIR, it shows the contents of this level of
the filing system. The command CD (alone) shows you the name of your
current directory. You go up to the root directory (the top level) by
specifying:

CD :

on the current volume (if you refer to your disks by volume name) or

CD df0:

on the built-in drive.

=== Setting the Date and Time ===

You can set the AmigaDOS clock by using the DATE command:

DATE 12:00:00 12-oct-85

Now the system clock counts up from this date and time. If your system has
a battery-backed, real-time clock, you can set it using the DATE command
as described followed by the command:

SETCLOCK SAVE

The SETCLOCK SAVE command copies AmigaDOS time to the real-time clock.

=== Redirecting the Output of a Command ===

Before you try this command, your Workbench or CLI disk should be in drive
0.

Normally the output of all commands goes to the monitor screen. You can
change where the system puts the output by using the redirect command ">".
The forward arrow symbol means send the output towards this output
filename. Here's an example:

DATE >datefile

Execute the command so that you can use the datefile described below. This
command creates (or overwrites) a file named "datefile" in your current
directory.

=== Typing a Text File to the Screen ===

You can see the contents of a text file by using the TYPE command:

TYPE datefile

This command will display whatever you have in the specified file. If you
wish to stop the output momentarily to read something on the screen, press
the space bar. To restart it press the BACKSPACE key. If you wish to end
the TYPE command, hold down the Ctrl key, and press the C key.

=== Changing the Name of a File ===

Before you try this command, your Workbench or CLI disk copy should be in
drive 0.

You can change the name of a file by using the RENAME command:

RENAME FROM datefile TO newname

or

RENAME dateile newname

Now use TYPE to verify that the new new refers to the same contents.

TYPE newname

Notice that the alternate form of the command doesn't require that you use
the FROM and TO. Most of the AmigaDOS commands have an alternate form,
abbreviated from that shown in this tutorial section. The longer form has
been used primarily to introduce you to what the command does. Be sure to
examine the summary pages to familiarize yourself with the alternate
command forms that are available.

=== Deleting Files ===

To try this command, your Workbench or CLI disk should be in drive 0.

You may be working on several versions of a program or text file, and eventually wish to delete versions of that file that you don't need anymore. The DELETE command lets you erase files and releases the disk space to AmigaDOS for resuse.

{{Note|text=If you DELETE files, it is not always possible to retrieve them. Be certain that you really do wish to delete them.}}

Here is a sample command sequence, that creates a file using the redirection command, types it to verify that it is really there, then deletes it.

DIR >directorystuff
TYPE directorystuff
DELETE directorystuff
TYPE directorystuff

To the final command in the above sequence, AmigaDOS responds:

Can't open directorystuff

indicating that the file can't be found, because you deleted it.

=== Copying Files ===

Before you enter this command, your Workbench or CLI disk should be in
drive 0.

On a dual-drive system, copying files is easy:

COPY FROM df0:sourcepath TO df1:destinationpath

or

COPY df0:sourcepath df1:destinationpath

On a single-drive system, copying files is a little more complex. You
must copy certain files from your system diskette into the system memory.
This is also called the RAM: device, or RAM disk. Copy the file(s) to the
RAM disk, change your directory to the RAM disk, then copy from the RAM
disk onto the destination disk. Here is a sample sequence.

Be sure your Workbench or CLI disk is in the internal disk drive. Issue
the commands:

COPY df0:c/cd ram:
COPY df0:c/copy ram:
CD ram:

Insert the source data disk into the drive. (For this example, copy the
EXECUTE command from the Workbench or CLI disk, which is already in the
drive.) Type:

COPY df0:c/execute ram:execute
or
COPY df0:c/execute ram:

Remove the source disk, and insert the destination disk into the drive.
The destination disk can be any Amiga disk that has been formatted. Type:

COPY ram:execute df0:execute

The EXECUTE command has now been copied from the source disk to the
destination disk.

Remove the destination disk and inset your CLI or Workbench disk again.
Type:

CD df0:

and you are back where you started. The only other command you may want to
perform is:

DELETE ram:cd ram:copy ram:execute

which releases the RAM disk memory to the system for other uses.

=== Creating a New Directory ===

You can create a new diretory (newdrawer) within the current directory by
using the MAKEDIR command:

MAKEDIR newdrawer

Now if you issue the DIR command, you will see that there is an entry for:

newdrawer (dir)

You can also use the RENAME command to move a file from one directory
(drawer) to another on the same disk:

MAKEDIR newdrawer
RENAME FROM newname TO newdrawer/newname

moves the file from the current directory into the newdrawer you have
created. To check tht it has really been moved, issue the command:

DIR

Then type:

DIR newdrawer

AmigaDOS looks in the newdrawer, and shows you that the file named
"newname" is there.

=== Is My File Somewhere on This Disk? ===

Before you enter this command, your Workbench or CLI disk copy should be
in drive 0.

Sometimes you wish to see everything on the disk, instead of only one
directory at a time. You can use the DIR command with one of its options:

DIR OPT A

which lists all directories and subdirectories on the disk. Keep in mind
the space/BACKSPACE combination to pause and restart the listing.

To get a closer look at the disk's contents, you might redirect the
output to a file:

DIR >mydiskdir ALL

Notice that the redirect-the-output command character [(>)] and filename
MUST come before the list of options for the DIR command.

Now, if you wish, you can TYPE the file mydiskdir and press the space
bar to pause the listing. Use the RETURN [or BACKSPACE] key to resume the
listing. Or, you can use ED to view the file, as follows:

ED mydiskdir

Use the cursor keys to move up and down in the file.

Use the key combination Esc then T <RETURN> to move to the top of the
file. Such a combination can be referred to as "Esc-T", meaning Esc
followed by T.

Use the key combination Esc-B <RETURN> to move to the bottom of the
file.

Use the key combination Esc-M then a number <RETURN> to move to a
specific line number within the file.

Use the key combination Esc-Q <RETURN> to quit without changing the
file; or

Use Esc-X <RETURN> to write any changes to your file back into the
original filename.

=== Automating the Boot Sequence ===

There is a file in the "S" directory on your Workbench or CLI disk called startup-sequence. This is a script file. It contains a sequence of CLI
commands that AmigaDOS performs whenever you reboot the system. Also in your Workbench disk startup-sequence are LOADWB (load the Workbench
program) and ENCLI which basically leaves the Workbench program in control. You can make up your own startup-sequence file using NotePad to create a custom version of an EXECUTE command sequence. The EXECUTE command summary and tutorial section has details about various commands that you can have in this file. Note that startup-sequence can also be used to auto-run a program.

{{Note|text=The startup-sequence looks for a file called s:user-startup and executes it if one is found. Whenever possible, place all your startup additions and assignments in a file called s:user-startup rather than modifying the s:startup-sequence.}}

=== Assigning a Disk ===

Before you enter this command, your Workbench or CLI disk copy should be
in drive 0.

Occasionally, you might wish to change to a different disk and then
continue your work. For example, you may have booted the system using a
Workbench disk, then wish to change to a CLI disk. If the CLI disk has a
directory on it that contains the executable commands you want to perform
(for example, a "c" directory), you can change to that disk by using the
ASSIGN command.

If you don't use ASSIGN, you will have to swap disks to get commands
done. Here is an example. The intent is to change disks and begin using
"mydisk:" as the main disk. Before you begin, you must first create a disk
called "mydisk". To do this, make a copy of Workbench (refer to the
instructions for copying a disk given at the beginning of this section).
Then use the RELABEL command described earlier to change the name of the
new copy to "mydisk".

CD mydisk:

AmigaDOS responds "Insert volume mydisk into any drive". Insert it, then
type:

DIR

AmigaDOS prompts "Insert volume Workbench [or whatever the boot disk name
was] into any drive". It knows, from boot time, that the DIR command is in
the boot disk's "c" directory. AmigaDOS reads the DIR command, then asks
"insert mydisk in any drive". Any other AmigaDOS command also results in
the need for a disk swap. To avoid this, use the ASSIGN command as
follows:

ASSIGN c: mydisk:c

AmigaDOS asks "Insert volume mydisk into any drive". From now on, all
commands to AmigaDOS will be sought from the command ("c") directory of
mydisk and AmigaDOS won't ask for the original disk back for simple
commands.

Once you've done this, you'll probably want to type:

CD mydisk:

There are other things that AmigaDOS can assign. If you issue the command:

ASSIGN LIST

you will see the other things as well. If you run a program that requires
a serial device (modem, printer) or a parallel device (printer), AmigaDOS
looks in the directory currently assigned to DEVS: to locate the device.
If all the system directories are on this new main disk, you can avoid
having AmigaDOS ask you to reinsert the original disk by providing a
script file on your disks that reassigns all devices to that disk. The
contents of this script file for a disk named "mydisk" are as follows:

ASSIGN SYS: mydisk:
ASSIGN S: mydisk:s
ASSIGN DEVS: mydisk:devs
ASSIGN L: mydisk:l
ASSIGN FONTS: mydisk:fonts
ASSIGN LIBS: mydisk:libs

To create4 this script file, use the command:

COPY FROM * TO reassign

Then type the above ASSIGN lines. After you've typed the last line, enter
the key combination Ctrl-\\ which ends the file. The "*" stands for the
keyboard and current CLI window, so this method of creating a file is one
possible alternative to using ED or EDIT.

Once you have created the script file, you can run it by typing:

EXECUTE reassign

Now all the ASSIGNs that the system uses are set up for "mydisk" instead
of the original boot disk.

= Closing Comments =

Chapter 2 contains a reference section that shows the templates for each
of the commands in AmigaDOS. You can look at the description for each
command to find more information. Once you are familiar with the commands,
and the forms in which you can use them, the quick reference listing at
the end of the chapter will be useful to remind you of the commands that
are available.

Workbench Library

2016-05-18T16:43:21Z

Brian Deneen: /* The Info File */ Moved the sentence starting with "The icon type can be set. . ." from the end of the paragraph to the beginning. It is the topic sentence, not the conclusion.

== Workbench Library ==

Workbench is the graphic user interface to the Amiga file system that uses symbols called icons to represent disks, directories and files. This article shows how to use workbench.library.

Workbench is both a system program and a screen. Normally it is the first thing the user sees when the machine is booted providing a friendly operating environment for launching applications and performing other important system activities like navigating through the Amiga's hierarchical filing system.

All application programs should be compatible with Workbench. There are only two things you need to know to do this: how to make icons for your application, data files and directories; and how to get arguments if your application is launched from Workbench.

== The Info File ==

The iconic representation of Amiga filing system objects is implemented through ''.info'' files. In general, for each file, disk or directory that is visible in the Workbench environment, there is an associated ''.info'' file which contains the icon imagery and other information needed by Workbench.

Icons are associated with a particular file or directory by name. For example, the icon for a file named ''myapp'' would be stored in a ''.info'' file named ''myapp.info'' in the same directory.

To make your application program accessible (and visible) in the Workbench environment, you need only supply a ''.info'' file with the appropriate name and type. The are four main types of icons (and ''.info'' files) used to represent Amiga filing system objects.

{| class="wikitable"
|+ Basic Workbench Icon Types
! Workbench Icon Type
! Image
! Filing System Object
! Result When Icon Is Activated
|-
| Disk || [[File:LibDiskIcon.png]] || The root level directory || Window opens showing files and subdirectories
|-
| Drawer || [[File:LibDrawerIcon.png]] || A subdirectory || Window opens showing files and subdirectories
|-
| Tool || [[File:LibToolIcon.png]] || An executable file || Application runs (i.e., an application)
|-
| Project || [[File:LibProjectIcon.png]] || A data file || Typically, the application that created the data file runs and the data file is automatically loaded into it.
|}

Icons can be created with the IconEdit program (in the Tools directory of the Extras disk), or by copying an existing ''.info'' file of the correct type. Icons can also be created under program control with PutDiskObject(). See [[Icon Library]] for a discussion of the icon library functions.

'''The icon type can be set and the icon imagery edited with the IconEdit program.''' For an executable file the icon type must be set to tool. For a data file the icon type must be set to project. Create icons for your application disk and directories too. For a directory, the icon is stored in a ''.info'' file at the same level where the directory name appears (not in the directory itself). The icon type should be set to drawer. The icon for a disk should always be stored in a file named ''disk.info'' at the root level directory of the disk. The icon type should be set to disk.

== Workbench Environment ==

On the Amiga there are at least two ways to start a program running:

* By activating a tool or project icon in Workbench (an icon is activated by pointing to it with the mouse and double-clicking the mouse select button.)
* By typing the name of an executable file at the Shell (also known as the CLI or Command Line Interface)

In the Workbench environment, a program is run as a separate process. A process is simply a task with additional information needed to use DOS library.

By default, a Workbench program does not have a window to which its output will go. Therefore, ''stdin'', ''stdout'' and ''stderr'' do not point to legal file handles. This means you cannot use ''stdio'' functions such as printf() if your program is started from Workbench unless you first set up a ''stdio'' window.

Some compilers have options or defaults to provide a ''stdio'' window for programs started from Workbench. Applications can use an auto console window for ''stdio'' when started from Workbench by opening "CON:0/0/640/200/auto/close/wait" as a file. An auto console window will only open if ''stdio'' input or output occurs. This can also be handled in the startup code module that comes with your compiler.

=== Argument Passing in Workbench ===

Applications started from Workbench receive arguments in the form of a WBStartup structure. This is similar to obtaining arguments from a command line interface through argc and argv. The WBStartup message contains an argument count and a pointer to a list of file and directory names.

==== One Argument ====

A program started by activating its tool icon gets one argument in the WBStartup message: the name of the tool itself.

==== Two Arguments ====

All project icons (data files) have a ''default tool'' field associated with them that tells Workbench which application tool to run in order to operate on the data that the icon represents. When the user activates a project icon, Workbench runs the application specified in the default tool field passing it two arguments in the WBStartup message: the name of the tool and the project icon that the user activated.

==== Multiple Arguments ====

With ''extended select'', the user can activate many icons at once. (Extended select means the user holds down the Shift key while clicking the mouse select button once on each icon in a group, double-clicking on the last icon.) If one of the icons in a group activated with extended select is an application tool, Workbench runs that application passing it the name of all the other icons in the group. This allows the user to start an application with multiple project files as arguments. If none of the icons in a group activated with extended select is a tool icon, then Workbench looks in the default tool field of each icon in the order they were selected and runs the first tool it finds.

=== WBStartup Message ===

When Workbench loads and starts a program, its sends the program a WBStartup message containing the arguments as summarized above. Normally, the startup code supplied with your compiler will place a pointer to WBStartup in argv for you, set argc to zero and call your program.

The WBStartup message, whose structure is outlined in <workbench/startup.h>, has the following structure elements:

<syntaxhighlight>
struct WBStartup
{
struct Message sm_Message; /* a standard message structure */
struct MsgPort * sm_Process; /* the process descriptor for you */
BPTR sm_Segment; /* a descriptor for your code */
LONG sm_NumArgs; /* the number of elements in ArgList */
char * sm_ToolWindow; /* reserved for future use */
struct WBArg * sm_ArgList; /* the arguments themselves */
};
</syntaxhighlight>

The fields of the WBStartup structure are used as follows.

; sm_Message
: A standard Exec message. The reply port is set to the Workbench.

; sm_Process
: The process descriptor for the tool (as returned by CreateProcess())

; sm_Segment
: The loaded code for the tool (returned by LoadSeg())

; sm_NumArgs
: The number of arguments in sm_ArgList

; sm_ToolWindow
: Reserved (not currently passed in startup message)

; sm_ArgList
: This is the argument list itself. It is a pointer to an array of WBArg structures with sm_NumArgs elements.

Workbench arguments are passed as an array of WBArg structures in the sm_ArgList field of WBStartup. The first WBArg in the list is always the tool itself. If multiple icons have been selected when a tool is activated, the selected icons are passed to the tool as additional WBArgs. If the tool was derived from a default tool, the project will be the second WBArg. If extended select was used, arguments other than the tool are passed in the order of selection; the first icon selected will be first (after the tool), and so on.

Each argument is a struct WBArg and has two parts: wa_Name and wa_Lock.

<syntaxhighlight>
struct WBArg
{
BPTR wa_Lock; /* a lock descriptor */
BYTE * wa_Name; /* a string relative to that lock */
};
</syntaxhighlight>

The wa_Name element is the name of an AmigaDOS filing system object. The wa_Name field of the first WBArg is always the name of your program and the wa_Lock field is an AmigaDOS Lock on the directory where your program is stored.

If your program was started by activating a project icon, then you get a second WBarg with the wa_Name field containing the file name of the project and the wa_Lock containing an AmigaDOS Lock on the directory where the project file is stored.

If your program was started through extended select, then you get one WBArg for each icon in the selected group in the order they were selected. The wa_Name field contains the file name corresponding to each icon unless the icon is for a directory, disk, or the Trashcan in which case the wa_Name is set to NULL. The wa_Lock field contains an AmigaDOS Lock on the directory where the file is stored. (For disk or drawer icons the wa_Lock is a lock on the directory represented by the icon. Or, wa_Lock may be NULL if the icon type does not support locks.)

{{Note|title=Workbench Locks Belong to Workbench|text=You must never call UnLock() on a wa_Lock. These locks belong to Workbench, and Workbench will UnLock() them when the WBStartup message is replied by your startup code. You must also never UnLock() your program's initial current directory lock (i.e., the lock returned by an initial CurrentDir() call). The classic symptom caused by unlocking Workbench locks is a system hang after your program exits, even though the same program exits with no problems when started from the Shell.}}

You should save the lock returned from an initial CurrentDir(), and CurrentDir() back to it before exiting. In the Workbench environment, depending on your startup code, the current directory will generally be set to one of the wa_Locks. By using CurrentDir(wa_Lock) and then referencing wa_Name, you can find, read, and modify the files that have been passed to your program as WBArgs.

=== Example of Parsing Workbench Arguments ===

The following example will display all WBArgs if started from Workbench, and all Shell arguments if started from the Shell.

<syntaxhighlight>
/* prargs.c
**
** PrArgs.c - This program prints all Workbench or Shell (CLI) arguments.
*/
#include <exec/types.h>
#include <workbench/startup.h>
#include <proto/dos.h>

int main(int argc, char **argv)
{
struct WBStartup *argmsg;
struct WBArg *wb_arg;
int32 ktr;
BPTR olddir;
BPTR outFile;

/* argc is zero when run from the Workbench,
** positive when run from the CLI.
*/
if (argc == 0)
{
/* AmigaDOS has a special facility that allows a window */
/* with a console and a file handle to be easily created. */
/* CON: windows allow you to use fprintf() with no hassle */
if (ZERO != (outFile = IDOS->Open("CON:0/0/640/200/PrArgs", MODE_NEWFILE)))
{
/* In AmigaOS, argv is a pointer to the WBStartup message
** when argc is zero. (run under the Workbench.)
*/
argmsg = (struct WBStartup *)argv ;
wb_arg = argmsg->sm_ArgList ; /* head of the arg list */

IDOS->FPrintf(outFile, "Run from the workbench, %ld args.\n",
argmsg->sm_NumArgs);

for (ktr = 0; ktr < argmsg->sm_NumArgs; ktr++, wb_arg++)
{
if (ZERO != wb_arg->wa_Lock)
{
/* locks supported, change to the proper directory */
olddir = IDOS->CurrentDir(wb_arg->wa_Lock) ;

/* process the file.
** If you have done the CurrentDir() above, then you can
** access the file by its name. Otherwise, you have to
** examine the lock to get a complete path to the file.
*/
IDOS->FPrintf(outFile, "\tArg %2.2ld (w/ lock): '%s'.\n",
ktr, wb_arg->wa_Name);

/* change back to the original directory when done.
** be sure to change back before you exit.
*/
IDOS->CurrentDir(olddir) ;
}
else
{
/* something that does not support locks */
IDOS->FPrintf(outFile, "\tArg %2.2ld (no lock): '%s'.\n",
ktr, wb_arg->wa_Name);
}
}
/* wait before closing down */
IDOS->Delay(500L);
IDOS->Close(outFile);
}
}
else
{
/* using 'tinymain' from lattice c.
** define a place to send the output (originating CLI window = "*")
** Note - if you open "CONSOLE:" and your program is RUN, the user will not
** be able to close the CLI window until you close the "CONSOLE:" file.
*/
if (ZERO != (outFile = IDOS->Open("CONSOLE:", MODE_NEWFILE)))
{
IDOS->FPrintf(outFile, "Run from the CLI, %d args.\n", argc);

for ( ktr = 0; ktr < argc; ktr++)
{
/* print an arg, and its number */
IDOS->FPrintf(outFile, "\tArg %2.2ld: '%s'.\n", ktr, argv[ktr]);
}
IDOS->Close(outFile);
}
}

return 0;
}
</syntaxhighlight>

== The Workbench Library ==

Workbench arguments are sent to an application when it is started. There are also special facilities that allow an application that is already running to get additional arguments. These special facilities are known as AppWindow, AppIcon and AppMenuItem.

An AppWindow is a special kind of window that allows the user to drag icons into it. Applications that set up an AppWindow will receive a message from Workbench whenever the user moves an icon into the AppWindow. The message contains the name of the file or directory that the icon represents.

An AppIcon is similar to an AppWindow. It is a special type of icon that allows the user to drag other icons on top of it. Like AppWindows, an application that sets up an AppIcon will receive a message from Workbench whenever the user moves another icon on top of the AppIcon. The message contains the name of the file or directory that the moved icon represents.

An AppMenuItem allows an application to add a custom menu item to the usual set of menu choices supported by Workbench. An application that sets up an AppMenuItem will receive a message from Workbench whenever the user picks that item from the Workbench menus.

When an application receives the messages described above, the message will include struct WBArg *am_ArgList containing the names (wa_Name) and directory locks (wa_Lock) of all selected icons that were passed as arguments by the user. This am_ArgList has the same format as the sm_ArgList of a WBStartup message.

=== The AppMessage Structure ===

When Workbench notifies an application of AppWindow, AppIcon, or AppMenuItem activity, it sends an AppMessage to the application's message port (from <workbench/workbench.h>):

<syntaxhighlight>
#define AM_VERSION 1

struct AppMessage {
struct Message am_Message; /* standard message structure */
UWORD am_Type; /* message type */
ULONG am_UserData; /* application specific */
ULONG am_ID; /* application definable ID */
LONG am_NumArgs; /* # of elements in arglist */
struct WBArg *am_ArgList; /* the arguments themselves */
UWORD am_Version; /* will be AM_VERSION */
UWORD am_Class; /* message class */
WORD am_MouseX; /* mouse x position of event */
WORD am_MouseY; /* mouse y position of event */
ULONG am_Seconds; /* current system clock time */
ULONG am_Micros; /* current system clock time */
ULONG am_Reserved[8];
};
</syntaxhighlight>

The AppMessage's am_Type field tells the application which type of AppObject the message is about. The field will be:
* AMTYPE_APPWINDOW if the message is about an AppWindow,
* AMTYPE_APPICON if the message is about an AppIcon, or
* AMTYPE_APPMENUITEM if the message is about an AppMenuItem.

When an application creates an AppObject, it can assign the AppObject application specific data (most likely a pointer) and an ID. Workbench will pass an AppObject's data and ID back to the application when it sends an AppMessage about the AppObject. The AppMessage's am_UserData and am_ID fields hold the user data and the ID.

The am_NumArgs field tells how many icons were involved in the user's AppObject action. For an AppWindow or AppIcon, am_NumArgs is the number of icons the user dropped on the AppWindow or AppIcon. For an AppMenuItem, am_NumArgs represents the number of icons that were selected when the user selected this AppMenuItem. If no icons were selected during an AppMenuItem event or the user double-clicked on an AppIcon, am_NumArgs will be zero. Workbench does not send AppMessages if the user double-clicks an AppWindow.

The am_ArgList field is a pointer to a list of WBArgs (from <workbench/startup.h>) corresponding to each icon dropped (or selected). If there were no icons dropped or selected, this field will be NULL.

For future expansion possibilities, the AppMessage structure has a version number. The version number is #defined as AM_VERSION in <workbench/workbench.h>.

The am_MouseX and am_MouseY fields apply only to AppWindows and contain the coordinates of the mouse pointer when the user dropped the icon(s). These coordinates are relative to the AppWindow's upper left corner.

The am_Seconds and am_Micros fields represent the time that the event took place.

Any remaining fields are undefined at present and should be set to NULL.

=== Workbench Library Functions ===

AppWindows, AppIcons and AppMenuItems extend the user's ability to perform operations with the Workbench iconic interface. They all provide graphical methods for passing arguments to a running application. In order to manage AppWindows, AppIcons and AppMenuItems, the Amiga OS includes these Workbench library functions:

<syntaxhighlight>
struct AppIcon *AddAppIconA( ULONG, ULONG, char *, struct MsgPort *, struct FileLock *,
struct DiskObject *, struct *TagItem );
struct AppMenuItem *AddAppMenuItemA( ULONG, ULONG, char *, struct MsgPort *, struct *TagItem);
struct AppWindow *AddAppWindowA( ULONG, ULONG, struct Window *, struct MsgPort *, struct *TagItem);

BOOL RemoveAppIcon(struct AppIcon *);
BOOL RemoveAppMenuItem(struct AppMenuItem *);
BOOL RemoveAppWindow(struct AppWindow *);
</syntaxhighlight>

The functions AddAppMenuItemA(), AddAppWindowA() and AddAppIconA() have alternate entry points using the same function name without the trailing A. The alternate functions accept any TagItem arguments on the stack instead of from an array. See the listings below for examples.

=== An AppIcon Example ===

The example listed here shows how to create an AppIcon and obtain arguments from Workbench when the user drops other icons on top of it. The AppIcon will appear as a disk icon named "TestAppIcon" on the Workbench screen. (All AppIcons appear on the Workbench screen or window.)

For convenience, this example code uses GetDefDiskObject() to create the icon imagery for the AppIcon. Applications should never do this. Use your own custom imagery for AppIcons instead.

<syntaxhighlight>
/* appicon.c
/* Works from the Shell (CLI) only */

#include <exec/types.h> /* Need this for the Amiga variable types */
#include <workbench/workbench.h> /* This has DiskObject and AppIcon structs */
#include <workbench/startup.h> /* This has WBStartup and WBArg structs */
#include <exec/libraries.h> /* Need this to check library versions */

#include <proto/icon.h> /* Icon (DiskObject) function prototypes */
#include <proto/exec.h> /* Exec message, port and library functions*/
#include <proto/workbench.h> /* AppIcon function protos */

struct Library *IconBase;
struct Library *WorkbenchBase;
struct IconIFace *IIcon;
struct WorkbenchIFace *IWorkbench;

int main(int argc, char **argv)
{
struct DiskObject *dobj=NULL;
struct MsgPort *myport=NULL;
struct AppIcon *appicon=NULL;
struct AppMessage *appmsg=NULL;

LONG dropcount=0L;
ULONG x;
BOOL success=0L;

IconBase = IExec->OpenLibrary("icon.library", 50);
WorkbenchBase = IExec->OpenLibrary("workbench.library", 50);

IIcon = (struct IconIFace*)IExec->GetInterface(IconBase, "main", 1, NULL);
IWorkbench = (struct WorkbenchIFace*)IExec->GetInterface(WorkbenchBase, "main", 1, NULL);

/* Get the the right version of the Icon Library, initialize IconBase */
if(IIcon != NULL && IWorkbench != NULL)
{
/* This is the easy way to get some icon imagery */
/* Real applications should use custom imagery */
dobj = IIcon->GetDefDiskObject(WBDISK);
if(dobj != 0)
{
/* The type must be set to NULL for a WBAPPICON */
dobj->do_Type = NULL;

myport = IExec->AllocSysObjectTags(ASOT_PORT, NULL);
if(myport)
{
/* Put the AppIcon up on the Workbench window */
appicon = IWorkbench->AddAppIconA(0L,0L,"TestAppIcon",myport,NULL,dobj,NULL);
if(appicon)
{
/* For the sake of this example, we allow the AppIcon */
/* to be activated only five times. */
IDOS->Printf("Drop files on the Workbench AppIcon\n");
IDOS->Printf("Example exits after 5 drops\n");

while(dropcount<5)
{
/* Here's the main event loop where we wait for */
/* messages to show up from the AppIcon */
IExec->WaitPort(myport);

/* Might be more than one message at the port... */
while(appmsg=(struct AppMessage *)IExec->GetMsg(myport))
{
if(appmsg->am_NumArgs==0L)
{
/* If NumArgs is 0 the AppIcon was activated directly */
IDOS->Printf("User activated the AppIcon.\n");
IDOS->Printf("A Help window for the user would be good here\n");
}
else if(appmsg->am_NumArgs>0L)
{
/* If NumArgs is >0 the AppIcon was activated by */
/* having one or more icons dropped on top of it */
IDOS->Printf("User dropped %ld icons on the AppIcon\n",
appmsg->am_NumArgs);
for(x=0;x<appmsg->am_NumArgs;x++)
{
IDOS->Printf("#%ld name='%s'\n",x+1,appmsg->am_ArgList[x].wa_Name);
}
}
/* Let Workbench know we're done with the message */
IExec->ReplyMsg((struct Message *)appmsg);
}
dropcount++;
}
success = IWorkbench->RemoveAppIcon(appicon);
}
/* Clear away any messages that arrived at the last moment */
while(appmsg = (struct AppMessage *)IExec->GetMsg(myport))
IExec->ReplyMsg((struct Message *)appmsg);
IExec->FreeSysObject(ASOT_PORT, myport);
}
IIcon->FreeDiskObject(dobj);
}

IExec->DropInterface((struct Interface*)IWorkbench);
IExec->DropInterface((struct Interface*)IIcon);

IExec->CloseLibrary(WorkbenchBase);
IEec->CloseLibrary(IconBase);

return 0;
}
</syntaxhighlight>

=== An AppMenuItem Example ===

This example shows how to create an AppMenuItem. The example adds a menu item named "Browse Files" to the Workbench Tools menu. (All AppMenuItems appear in the Workbench Tools menu.) When the menu item is activated, the example program receives a message from Workbench and then attempts to start up an instance of the More program. (The More program is in the Utilities directory of the Workbench volume.)

The example starts up the More program as a separate, asynchronous process using the SystemTags() function. When the AppMenuItem has been activated five times, the program exits after freeing any system resources it has used.

<syntaxhighlight>
/* appmenuitem.c
/* Works from the Shell (CLI) only */

#include <exec/types.h> /* Need this for the Amiga variable types */
#include <workbench/workbench.h> /* This has DiskObject and AppIcon structs */
#include <workbench/startup.h> /* This has WBStartup and WBArg structs */
#include <exec/libraries.h>
#include <dos/dostags.h>

#include <proto/dos.h>
#include <proto/exec.h> /* Exec message, port and library functions*/
#include <proto/workbench.h> /* AppMenuItem function protos */

struct Library *WorkbenchBase;
struct WorkbenchIFace *IWorkbench;

int main(int argc, char **argv)
{
struct MsgPort *myport=NULL;
struct AppMenuItem *appitem=NULL;
struct AppMessage *appmsg=NULL;
LONG result, x, count=0L;
BOOL success=0L;
BPTR file;

WorkbenchBase = IExec->OpenLibrary("workbench.library", 50);
IWorkbench = (struct WorkbenchIFace*)IExec->GetInterface(WorkbenchBase, "main", 1, NULL);

if (IWorkbench != NULL)
{
if(myport = IExec->AllocSysObjectTags(ASOT_PORT, NULL))
{
/* Add our own AppMenuItem to the Workbench Tools Menu */
appitem = IWorkbench->AddAppMenuItemA(0L, /* Our ID# for item */
(ULONG)"SYS:Utilities/More", /* Our UserData */
"Browse Files", /* MenuItem Text */
myport,NULL); /* MsgPort, no tags */
if(appitem)
{
IDOS->Printf("Select Workbench Tools demo menuitem 'Browse Files'\n");

/* For this example, we allow the AppMenuItem to be selected */
/* only once, then we remove it and exit */
IExec->WaitPort(myport);
while((appmsg = (struct AppMessage *)IExec->GetMsg(myport)) && (count<1))
{
/* Handle messages from the AppMenuItem - we have only one */
/* item so we don't have to check its appmsg->am_ID number. */
/* We'll System() the command string that we passed as */
/* userdata when we added the menu item. */
/* We find our userdata pointer in appmsg->am_UserData */

IDOS->Printf("User picked AppMenuItem with %ld icons selected\n",
appmsg->am_NumArgs);
for(x=0;x<appmsg->am_NumArgs;x++)
IDOS->Printf(" #%ld name='%s'\n",x+1,appmsg->am_ArgList[x].wa_Name);

count++;
if( file=Open("CON:0/40/640/150/AppMenu Example/auto/close/wait",
MODE_OLDFILE) ) /* for any stdio output */
{
result=IDOS->SystemTags((UBYTE *)appmsg->am_UserData,SYS_Input,file,
SYS_Output,NULL,
SYS_Asynch,TRUE,
TAG_END);
/* If Asynch System() itself fails, we must close file */
if(result == -1) IDOS->Close(file);
}
IExec->ReplyMsg((struct Message *)appmsg);
}
success = IWorkbench->RemoveAppMenuItem(appitem);
}

/* Clear away any messages that arrived at the last moment */
/* and let Workbench know we're done with the messages */
while(appmsg=(struct AppMessage *)IExec->GetMsg(myport))
{
IExec->ReplyMsg((struct Message *)appmsg);
}
IExec->FreeSysObject(ASOT_PORT, myport);
}

IExec->DropInterface((struct Interface*)IWorkbench);
IExec->CloseLibrary(WorkbenchBase);

return 0;
}
</syntaxhighlight>

=== An AppWindow Example ===

This example shows how to create an AppWindow and obtain arguments from Workbench when the user drops an icon into it. The AppWindow will appear on the Workbench screen with the name "AppWindow" and will run until the window's close gadget is selected. If any icons are dropped into the AppWindow, the program prints their arguments in the Shell window.

<syntaxhighlight>
/* appwindow.c */
/* Works from the Shell (CLI) only */

#include <exec/types.h> /* Need this for the Amiga variable types */
#include <workbench/workbench.h> /* This has DiskObject and AppWindow */
#include <workbench/startup.h> /* This has WBStartup and WBArg structs */
#include <exec/libraries.h> /* Need this to check library versions */

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/intuition.h>
#include <proto/workbench.h>

struct Library *IntuitionBase;
struct Library *WorkbenchBase;
struct IntuitionIFace *IIntuition;
struct WorkbenchIFace *IWorkbench;

int main(int argc, char **argv)
{
struct MsgPort *awport;
struct Window *win;
struct AppWindow *appwin;
struct IntuiMessage *imsg;
struct AppMessage *amsg;
struct WBArg *argptr;

ULONG winsig, appwinsig, signals, id = 1, userdata = 0;
BOOL done = FALSE;
int i;

IntuitionBase = IExec->OpenLibrary("intuition.library", 50);
WorkbenchBase = IExec->OpenLibrary("workbench.library", 50);

IIntuition = (struct IntuitionIFace*)IExec->GetInterface(IntuitionBase, "main", 1, NULL);
IWorkbench = (struct WorkbenchIFace*)IExec->GetInterface(WorkbenchBase, "main", 1, NULL);

if (IIntuition != NULL)
{
if (IWorkbench != NULL)
{
if (awport = IExec->AllocSysObjectTags(ASOT_PORT, NULL))
{
if (win = IIntuition->OpenWindowTags(NULL,
WA_Width, 200, WA_Height, 50,
WA_IDCMP, CLOSEWINDOW,
WA_Flags, WINDOWCLOSE | WINDOWDRAG,
WA_Title, "AppWindow",
TAG_END))
{
if (appwin = IWorkbench->AddAppWindow(id, userdata, win, awport, NULL))
{
IDOS->Printf("AppWindow added... Drag files into AppWindow\n");
winsig = 1L << win->UserPort->mp_SigBit;
appwinsig = 1L << awport->mp_SigBit;

while (! done)
{
/* Wait for IDCMP messages and AppMessages */
signals = IExec->Wait( winsig | appwinsig );

if(signals & winsig) /* Got an IDCMP message */
{
while (imsg = (struct IntuiMessage *) IExec->GetMsg(win->UserPort))
{
if (imsg->Class = CLOSEWINDOW) done = TRUE;
IExec->ReplyMsg((struct Message *) imsg);
}
}
if(signals & appwinsig) /* Got an AppMessage */
{
while (amsg = (struct AppMessage *) IExec->GetMsg(awport))
{
IDOS->Printf("AppMsg: Type=%ld, ID=%ld, NumArgs=%ld\n",
amsg->am_Type, amsg->am_ID, amsg->am_NumArgs);
argptr = amsg->am_ArgList;
for (i = 0; i < amsg->am_NumArgs; i++)
{
IDOS->Printf(" arg(%ld): Name='%s', Lock=%lx\n",
i, argptr->wa_Name, argptr->wa_Lock);
argptr++;
}
IExec->ReplyMsg((struct Message *) amsg);
}
}
} /* done */
IWorkbench->RemoveAppWindow(appwin);
}
IIntuition->CloseWindow(win);
}
/* Make sure there are no more outstanding messages */
while(amsg = (struct AppMessage *)IExec->GetMsg(awport))
IExec->ReplyMsg((struct Message *)amsg);
IExec->FreeSysObject(ASOT_PORT, awport);
}
}
}

IExec->DropInterface((struct Interface*)IIntuition);
IExec->DropInterface((struct Interface*)IWorkbench);
IExec->CloseLibrary(IntuitionBase);
IExec->CloseLibrary(WorkbenchBase);

return 0;
}
</syntaxhighlight>

== Workbench and the Startup Code Module ==

Standard startup code handles the detail work of interfacing with the arguments and environment of Workbench and the Shell (or CLI). This section describes the behavior of standard startup modules such as the ones supplied with newlib and clib2.

The environment for a program started from Workbench is quite different from the environment for a program started from the Shell. The Shell does not create a new process for a program; it jumps to the program's code and the program shares the process with the Shell. Programs run under the Shell have access to all the Shell's environment, including the ability to modify that environment. (Programs run from the Shell should be careful to restore all values that existed on startup.) Workbench starts a program as a new DOS process, explicitly passing the execution environment to the program.

=== Workbench Startup ===

When the user activates a project or tool icon, the program is run as a separate process asynchronous to Workbench. This allows the user to take full advantage of the multitasking features of the Amiga. A process is simply a task with additional information needed to use DOS library.

When Workbench loads and starts a program, it sends the program a WBStartup message containing the arguments as described earlier. The WBStartup also contains a pointer to the new Process structure which describes the execution environment of the program. The WBStartup message is posted to the message port of the program's Process structure.

The Process message port is for the exclusive use of DOS, so this message must be removed from the port before using any DOS library functions. Normally this is handled by the startup code module that comes with your compiler so you don't have to worry about this unless you are writing your own startup code.

Standard startup code modules also set up SysBase, the pointer to the Exec master library, and open the DOS library setting up DOSBase. That is why Exec and AmigaDOS functions can be called by C applications without first opening a library; the startup code that applications are linked with handles this. Some special startups may also set up NIL: input and output streams, or may open a ''stdio'' window so that the Workbench applications can use stdio functions such as printf().

The startup code can tell if it is running in the Workbench environment because the pr_CLI field of the Process structure will contain NULL. In that case the startup code removes the WBStartup message from the Process message port with GetMsg() before using any functions in the DOS library.

{{Note|title=Do Not Use the Process Message Port for Anything Else|text=The message port in a Process structure is for the exclusive use of the DOS library.}}

Standard startup code will pass the WBStartup message pointer in argv and 0 (zero) in argc if the program is started from Workbench. The startup code calls the application code that it is linked with as a function. When the application code exits back to the startup code, the startup code closes and frees all opens and allocations it made. It will then Forbid(), and ReplyMsg() the WBStartup message, notifying Workbench that the application Process may be terminated and its code unloaded from memory.

{{Note|title=Avoid the DOS Exit() function|text=The DOS Exit() function does ''not'' return an application to the startup code that called it. If you wish to exit your application, use the exit function provided by your startup code (usually lower-case exit(), or _exit for assembler), passing it a valid DOS return code as listed in the include file <libraries/dos.h>.}}

=== Shell Startup ===

When a program is started from the Shell (or a Shell script), standard startup modules will parse the command line into an array of pointers to individual argument strings placing them in argv, and an argument count in argc.

If a program is started from the Shell, argc will always equal at least one and the first element in argv will always be a pointer to the command name. Other command line arguments are stored in turn. For example, if the command line was:

<pre>
df0:myprogram "my file1" file2 ;this is a comment
</pre>

then argc will be 3, argv[0] will be "df0:myprogram", argv[1] will be "my file1", and argv[2] will be "file2". Correct startup code will strip spaces between arguments and trailing spaces from the last argument and will also properly deal with quoted arguments with embedded spaces.

As with Workbench, standard startup code for the Shell sets up SysBase, the pointer to the Exec master library, and opens the DOS library setting up DOSBase. C applications that are linked with standard startup code can call an Exec or AmigaDOS functions without opening the library first.

The startup code also fills in the ''stdio'' file handles (_stdin, _stdout, etc.) for the application. Finally argv and argc, are pushed onto the stack and the application is called. When the application returns or exits back to the startup code, the startup code closes and frees all opens and allocations it has made for the application, and then returns to the system with the whatever value the program exited with.

Link your applications only with standard, tested startup code of some type such as the module supplied with your compiler. Startup code provides your programs with correct, consistent handling of Shell command line and Workbench arguments and will perform some initializations and cleanups which would otherwise need to be handled by your own code. Very small startups can be used for programs that do not require command line arguments.

A few words of warning for those of you who do not use standard startup code:

* If you are started as a Workbench process, you ''must'' GetMsg() the WBStartup message before using any functions in the DOS library.
* You ''must'' turn off task switching (with Forbid()) before replying the WBStartup message from Workbench. This will prevent Workbench from unloading your code before you can exit properly.
* If you do your own command line parsing, you ''must'' provide the user with consistent and correct handling of command line arguments.

== Function Reference ==

The following are brief descriptions of the functions in workbench.library. See SDK for details on each function call.

{| class="wikitable"
|+Workbench Library Functions
|-
! Function
! Description
|-
| AddAppIcon()
| Add an AppIcon to Workbench
|-
| AddAppMenuItem()
| Add an AppMenuItem to the Workbench Tools menu
|-
| AddAppWindow()
| Add an AppWindow to Workbench
|-
| RemoveAppIcon()
| Remove an AppIcon to Workbench
|-
| RemoveAppMenuItem()
| Remove an AppMenuItem to the Workbench Tools menu
|-
| RemoveAppWindow()
| Remove an AppWindow to Workbench
|}

AmigaOS Manual: Workbench Glossary

2016-05-18T16:34:07Z

Brian Deneen: */Tool Type/* added a link to the UI Style Guide list of default tool types

This glossary provides definitions of terms used in the Amiga manuals.

; acceleration
: An option, selected through the Input editor, that causes the pointer movement to increase as the mouse is moved at a constant speed. Acceleration provides a higher degree of control for small mouse movements and less control, but greater mouse speed, for large movements.

; action gadget
: A gadget in a window that performs an operation in the window when you select the gadget. Common action gadgets are Save, Continue, and Cancel.

; active
: Used in reference to the screen, Shell window, or Workbench window that is accepting input..

; Advanced Graphics Architecture (AGA)
: An Amiga custom chip set that delivers more displayable colors and improved performance.

; alias
: An alternative name for an AmigaDOS command or command string, specified with the ALIAS command.

; AmigaDOS
: The disk operating system (DOS) used by Amiga computers. A disk operating system provides the basic functions of the computer.

; AppIcon
: An icon created and used by an application.

; application
: A program or collection of programs that perform a specific task, such as a word processor, database, or video title.

; AppWindow
: An application window into which you can drag an icon to load the icon file into the application. The MultiView window and Amiga file requester are AppWindows.

; archive
# (n) A backup copy of a file or files.
# (v) To copy files to disk or tape for backup purposes.

; argument
: An additional piece of information, such as a file name, value, or option, included along with a command. This information determines the exact actions of the command.

; argument passing
: Specifying parameters on the command line for a program or command to follow.

; ASCII (American Standard Code for Information Interchange)
: A standardized format for text that assigns code numbers to characters, allowing the exchange of information between different types of computers.

; aspect ratio
: The proportion of an image's height to its width.

; assign
: To link a logical device name to a directory name with the ASSIGN command. This lets programs that use that directory use a single device name in all cases. For example, the device name T: is commonly assigned to the directory name RAM:T.

; attributes
: A series of flags stored with every file. Attributes indicate file type and control the operations (read, write, delete, and so forth) permissible on the file. Also called protection bits.

; autoscroll
: To automatically move a screen when the pointer reaches the edges of the viewable area.

; backdrop
: A special type of window that has no borders, is as large as the screen, and is always behind all other windows on the screen.

; backup
: A copy of a file on disk or tape used to replace lost data.

; back up
: To make a backup copy.

; baud rate
: The speed at which a device receives or transmits information in serial communication. Roughly equivalent to bits per second.

; binary
: The base-2 number system that uses only the digits 0 and 1.

; bit
: A single binary digit (1 or 0).

; bitplane
: An area of RAM that holds screen graphics data. Each bit in a bitplane controls one screen pixel. The number of bitplanes for a screen controls the maximum number of simultaneous colors possible for that screen.

; block
# A contiguous series of bytes (usually 512) treated as a single logical unit in RAM or permanent storage media.
# A user-marked area of a text file.

; boot
: To start the system by reading the information needed from a storage device, such as a floppy or hard disk, into the computer's memory. Also refers to items used in this process: the boot disk. (See reboot.)

; bootable
: Refers to a device from which the Amiga can boot. A bootable disk must contain all the system files needed for the computer to start operation.

; Bridgeboard
: An expansion board from Commodore that allows hardware emulation of PC-compatible computers.

; brush
: An IFF graphics file, usually a section cut from a full-sized picture.

; buffer
: A temporary storage area in RAM.

; bug
: An error in software or hardware.

; busy pointer
: An image of a stopwatch that appears in place of the normal pointer when the Workbench is busy and cannot accept further input. Also called the wait pointer.

; byte
: A unit of memory consisting of eight bits, usually equivalent to one character.

; cache memory
: A temporary area in memory with extremely fast access that improves the system performance.

; catalog
: The files that contain the system texts and messages translated to a different language.

; CD-ROM
: A read only storage media. Stores upward of 550 MB on a disk similar to an audio compact disc.

; check box
: A gadget that lets you turn an option on or off. When a check mark appears in the box, the option is selected, or on.

; chip
: A miniaturized electronic circuit, housed in a small, black, rectangular block edged by metal connector pins. A computer is made up of a variety of specialized chips.

; Chip RAM
: The area of RAM accessible to the Amiga's custom chip set. This memory is used for graphics and sound data. Also called graphics memory.

; clear
# To change a bit or flag to its 0, off, or disabled state. Opposite of set.
# To erase a screen or window display.

; CLI (Command Line Interface)
: A means of communicating with a computer by issuing commands from the keyboard. The Shell is the Amiga's CLI.

; click
: To press and release a mouse button. Refers to the selection (left) mouse button unless otherwise specified.

; Clipboard
: An area in memory that is used to store text and graphics while they are being transferred between programs.

; close
: To remove a window from the screen, to end a program, or to finish the access to a data file.

; close gadget
: A gadget that can appear in the upper left corner of a window to allow you to close the window.

; cold boot
: To boot the Amiga from a powered off state.

; color correction
: A printing option, selected through the PrinterGfx editor, that tries to better match the colors of a printout to the colors on the screen.

; command
: A statement given to the Amiga to perform a task or achieve a result.

; command history
: A feature of the Shell that allows you to recall previously entered command lines by using the cursor keys.

; command line
: The line on which commands and their arguments are typed. Also, all the information that has been typed on the line.

; console window
: A window used for the input and output of text, such as a Shell window.

; Control-key combination
: A key combination that performs a special function, entered by holding down Ctrl while pressing another key on the keyboard. Some Control-key combinations are executed as soon as they are pressed, such as when Ctrl+C is used to abort the execution of an AmigaDOS command. Some produce a reversed character image and have no immediate effect.

; coprocessor
: A separate processor chip that assists the CPU by performing specific tasks, such as mathematical computations or rapid data transfer.

; copy and paste
: The act of copying a block of text or graphics and inserting it at a new location.

; CPU (Central Processing Unit)
: The "brain" of a computer; the integrated circuit chip primarily responsible for executing the instructions in a program.

; current directory
: The current location in the directory structure. The directory AmigaDOS uses as the default directory to operate within, if no other directory is specified.

; current window
: The highlighted window that accepts input from the keyboard. A Shell window is current when it is opened.

; cursor
: A highlighted rectangle or vertical bar on the screen used to indicate text position.

; cycle gadget
: A gadget for selecting one of several options. One option is displayed at a time and as the gadget is selected, the other options become visible. The displayed option is the selected option.

; cylinder
: A logical division of a magnetic storage disk. Amiga 3.5 inch floppy disks are divided into 80 cylinders during the formatting process.

; data
: A collection of information.

; dead key
: A key, or key combination, that modifies the output of the next key to be pressed. For example, on an American keyboard. Alt+H superimposes a caret (^) symbol over the next key to be pressed. Alt+H is a dead key combination.

; debug
: To find and fix mistakes in software or hardware.

; default
: A value or action assumed if you have not specified something else.

; Default Tool
: A tool specified in a project icon's Information window. When the project icon is opened, the Default Tool is automatically loaded and run.

; delete
: To erase or discard a file, buffer, or other stored item.

; delimiter
: A special character marking the beginning and end of a string.

; density
: The number of printer dots per inch. Many printers support several print densities. Usually, the higher the density, the darker and sharper the printout.

; depth gadget
: A gadget that may appear in the upper right corner of a window or screen for moving that window or screen in front of or behind other windows or screens. This is sometimes referred to as depth arranging.

; destination
: The device, directory, or file that is receiving information.

; device
: A physical mechanism, such as a printer or disk drive, or a software entity (logical device), such as CON: or NIL:, used as a source or destination for information.

; device name
: A short name, such as DF0:, PC1:, or PRT:, that identifies a particular hardware or software device. Device names must end in a colon (:).

; directory
: A subdivision in a computer's filing system used to organize files and other directories (subdirectories). Directories are represented on the Workbench by drawer icons.

; disk
: A medium for mass storage of computer data. Most computer disks store information magnetically; optical (laser-read) disks are also used.

; disk drive
: A storage device that reads and writes data from and to a storage disk such as a floppy disk.

; disk operating system (DOS)
: The software that controls the basic input and storage functions of a computer.

; display box
: A rectangular box, usually under a scroll gadget or next to a selection gadget, that displays the current selection. You cannot edit a display box.

; display mode
: A name given to the set of parameters, such as resolution and scan frequency, that define a screen. For example, a High Res display mode is 640 pixels wide and 200 pixels high (for NTSC Amigas).

; dithering
# Creating smoother color or grey scale shading of screen or printed displays by altering pixel color or density. The PrinterGfx and PrinterPS Preferences editors provides several settings for automatic dithering of printed graphics.
# Creating the illusion of a color by using a pattern of other colors. For example, creating the illusion of purple by alternating pixels of red and blue.

; double-click
: To quickly press and release the selection button twice.

; drag
: To move an icon, window, gadget, or screen across the display by pointing to the object, holding down the selection button, and moving the mouse.

; drag selection
: The process of selecting several icons at once by holding down the selection button and using the mouse to draw a box around the icons you want to select. When you release the mouse button, all the icons in the box are selected.

; drawer
: A subdivision of a disk storage area. A drawer corresponds to an AmigaDOS directory.

; drive name
: The device name assigned to a disk drive, such as DF0: or DH1:.

; dump
: A printout of the image displayed on the screen.

; ECS (Enhanced Chip Set)
: The upgraded versions of the Amiga's Agnus and Denise coprocessor chips. The Enhanced Chip Set offers additional display modes (ECS modes) and expands previous graphics capabilities. Many of the benefits of the ECS are available only in conjunction with Release 2 or higher of the operating system.

; editor
: A program that lets you create and/or modify certain types of files. The Amiga provides Preferences editors to change Prefs settings and the text editors, MEmacs and ED, for changing text files.

; escape sequence
: A sequence of characters, beginning with the Escape character, that performs a special function when entered on a command line or printed as part of a string. Escape sequences are typically used to alter the style of type used by a printer or in a console window.

; execute
: To carry out the instructions in a command line, program, or script.

; extended selection
: The process of selecting several icons at once by holding down Shift while selecting each icon with the mouse.

; extension
: A sequence of characters beginning with a period, such as .info, added to the end of a filename to identify the type of file.

; Extra Halfbrite
: A special graphics mode that doubles the number of colors on the screen by duplicating existing colors at half their brightness.

; Fast RAM
: General memory used by programs and data. As the name implies, normally faster than Chip RAM.

; field
: The screen area behind the text of a Workbench icon label. The color of the field can be changed with the Font editor.

; file
: An organized collection of data referred to by a name and stored on some type of media.

; file system
: The organization and software that controls the data, files, and directories stored on a volume. The primary types of Amiga file systems are FFS (FastFileSystem) and OFS (OldFileSystem).

; floppy disk
: A removable magnetic storage medium. The Amiga uses 3.5 inch, double-sided, floppy disk in a rigid plastic case.

; font
: Also called typeface. A particular design of a set of letters, symbols, and numbers used for text display, such as Topaz and Helvetica. Fonts are usually available in several sizes, defined in points (10 point, 12 point, and so on).

; format
# To prepare a disk for use with the Amiga. Formatting a disk erases all previously stored data.
# A way of describing the proper syntax for AmigaDOS commands.

; fragmentation
: A scattered distribution of data on a disk or in memory. Disk fragmentation results in slower disk performance; memory fragmentation can prevent some programs from running properly.

; function keys
: Keys at the top of the Amiga keyboard, labeled F1 to F10, that can be programmed to perform special tasks.

; gadget
: Any of various programmed graphic images that may appear in a window, requester, or screen and can be manipulated with the mouse to perform a certain function. Each gadget is of a specific type and performs a specific action. Most gadgets appear raised and when selected, appear to sink into the screen.

; genlock
: A piece of hardware that allows Amiga graphics to be overlaid onto another video source, for example, from a camera or VCR. A genlock is typically used for applying titles or captions to video media.

; ghosting
: Displaying menu or gadget items on the screen less distinctly than normal to indicate that they are currently unavailable.

; graphics memory
: See Chip RAM.

; GUI (Graphical User Interface)
: A visually-oriented system allowing you to tell a computer what to do by manipulating graphic symbols rather than by typing in commands. The Workbench is the Amiga GUI.

; HAM (Hold And Modify)
: An Amiga graphics mode that allows the full Amiga color palette to be displayed on the screen.

; handshaking
: The electronic protocol required for serial communication between two computing devices.

; hard disk
: A high-speed, large-capacity mass-storage device from which the disks usually cannot be removed. Often called a hard drive or hard disk drive.

; hierarchical
: A term used to describe the multi-leveled AmigaDOS file structure in which directories can contain other directories and/or files.

; history buffer
: A section of memory that stores the most recent commands for a given Shell.

; hold down
: To continually press a mouse button until instructed to release it.

; hot key
: A key or key combination used by Commodity Exchange programs to open a hidden window.

; hot spot
: The pixel in a pointer, normally the tip of an arrow or the center of a crosshair, that must be touching an object on the screen to select it.

; icon
: An image appearing on the screen to represent a disk, drawer, project or tool. Icons can be moved and selected with the mouse to allow you to work with the items they represent.

; IFF (Interchange File Format)
: The standardized format in which the Amiga stores picture, sound, and other types of data.

; .info file
: A file containing the image and position data for an icon (referred to as "dot-info").

; initialize
: A synonym for format.

; input buffer
: An area of memory used during serial communication to hold incoming information.

; interlace
: A property of some Amiga display modes that doubles the vertical screen resolution.

; Internal
: Refers to an AmigaDOS command that is built into the Shell, rather than loaded from disk.

; KB (Kilobyte)
: 1024 bytes. Often abbreviated as K.

; keyboard shortcut
: A method for performing a mouse action by pressing a key or key combination.

; keymap
: A file that determines the arrangement of characters on the keyboard and determines the meaning of each key. Different languages have different keymaps.

; keyword
: A word recognized by an AmigaDOS command or a Tool Type entry as ientifying an argument or specifying an option.

; Kickstart
: Refers to the portion of the Amiga operating system that is in ROM.

; library
: An integrated set of functions and data that can be used by different programs. Libraries can be found in ROM and in the LIBS: drawer.

; macro
: A single command that represents a sequence of commands. Many editors and applications support the use of macros to facilitate commonly used command sequences. ARexx programs are often called macros.

; MB (Megabyte)
: 1024KB (1,048,576 bytes). Often abbreviated as M or Meg.

; memory
: The Amiga's internal storage circuitry that holds programs and data. The Amiga has Chip (graphics) memory. Fast (normal) memory, and ROM (Read Only Memory). The amount of RAM (Random Access Memory) limits the size and number of programs that can be operating within the Amiga at one time.

; menu
: A list of on-screen options, displayed by using the menu button, from which you can choose commands that control a program.

; menu bar
: The list of headings that appears across the top of the screen when the menu button is held down.

; menu button
: The right mouse button.

; menu item
: An option that appears in a menu. For example, New Drawer is the first menu item in the Workbench's window menu.

; modem
: A device allowing serial communication over telephone lines.

; monitor
: A video display terminal on which a computer's visual output is shown. There are many types of monitors; the Amiga's standard output uses an analog RGB color monitor to display both graphics and text.

; mouse
: The device used to move the pointer on the screen and to communicate with the Amiga. Ist buttons can be used for displaying menus, and for selecting and dragging icons, windows and screens.

; multiscan
: A type of video monitor than can accept several different scan rates (types of video output).

; multitasking
: The ability to Perform more than one operation, or task, at a time. The Amiga's multiasking operating system can have several independent programs running at once. For instance, you could simultaneously be displaying an animation, playing a sound file, communicating with another computer, and formatting a floppy disk.

; nonproportional font
: A font, such as Topaz, in which each character takes up an equal amount of space. For example, an uppercase W is allotted the same amount of space as a lowercase 1. Also calls a monospaced font.

; offset
: To shift or move over.

; open
: To make the selected object available for use. Open an icon by double-clicking on it or by selecting it then choosing the Open menu item from the Icons menu. When you open a disk or drawer icon, a window appears, displaying its contents. When you open a project or tool icon, a program is started.

; operating system (OS)
: Software, in ROM or supplied on floppy or hard disk, that controls the basic functions of a computer.

; overscan area
: The normally unused area surrounding a standard-size screen. The Overscan editor allows you to expand your screen to fill this area.

; overwrite
: To write information to memory, a file, or disk, replacing any information that previously was stored there.

; parallel
: An interface port that transfers data one complete byte (8 bits) at a time, contrasted to a serial interface that sends a single bit at a time. The Amiga has an external parallel port to which a printer can be connected.

; parent
: The window from which another window was generated. The directory that contains the current directory a drawer.

; parity
: A method of detecting errors in serial communication by attaching an extra bit to bytes of data.

; partition
: A section of the hard disk that the system treats as if it were a separate drive.

; path
: The series of volume and drawer names that define the location of a file.

; pattern matching
: An AmigaDOS feature that lets you specify file and directory names by using wildcard characters. With wildcards, you can create search patterns that allow you to refer to a number of files whose names share a common text pattern without naming each file individually.

; peripheral
: An external hardware device connected to the Amiga.

; pitch
: The number of characters printed in a horizontal inch.

; pixel
: The dots of light that make up the Amiga screen display. A pixel is the smallest unit of display information on a given screen. Derived from "Picture Element".

; point
: (v) To place the mouse pointer so that its hot spot is touching the object pointed to.: (n) The unit of measurement of vertical font size. Traditionally this is 1/72 of an inch; on the Amiga it means one screen pixel.

; pointer
: An image on the screen, usually arrow-shaped, that moves as you move the mouse. Use the pointer to select icons and gadgets and to choose menu items.

; PostScript printer
: A high-resolution printer that can accept text and graphics information in the PostScript page description language.

; Preferences (Prefs)
: A Workbench drawer containing editors that let you configure and customize your Amiga environment, such as changing the colors of your screen and setting the specifications for communication through the serial port.

; printer driver
: A program that enables the Amiga to communicate with a given printer. A printer driver works as a translator between a computer and a printer, taking the information in a standardized form (ASCII characters and ANSI escape sequences) from the computer and presenting it to the printer in a format that the printer can understand.

; program
: A series of instructions that tell the Amiga how to perform certain tasks. Applications and system software are programs.

; project
: A file in which information crated or used by a tool is stored. For example, files created with a text editor or paint program are projects.

; prompt
: A message or symbol that indicates that text input to the computer is expected.

; protection bits
: (See attributes.)

; pseudo-icon
: An icon that is displayed for an object that does not have a .info file when the Show All Files menu item is chosen.

; pure
: Describes a command or program that can be made resident. If a file is pure, the p attribute is set.

; qualifier
: A key, such as Shift, Ctrl, or Alt, that change the Amiga's interpretation of a simultaneous or subsequent keystroke or mouse click. Commonly used with Commodity Exchange programs.

; radio button
: A circular gadget beside an option on a list. To select an option, select its radio button. You can only option from the list at a time.

; RAM (Random Access Memory)
: Part of the Amiga's internal memory that can be used for data storage and is directly accessible by the CPU. Applications are loaded into RAM from disk and use additional RAM to process and store data while the computer is on. Data in RAM is lost when the Amiga is rebooted or powered off.

; Ram Disk
: A section of RAM set aside to function as if it were a disk drive. This is much faster than a physical drive, since there are no mechanical elements.

; read
: To retrieve stored information.

; Read Only
: If disk status is Read Only, you can only look at the contents of the disk, you cannot alter them.

; Read/Write
: If disk status is Read/Write, you can both look at and alter the contents of the disk.

; reboot
: To reset the Amiga by pressing Ctrl, left Amiga, and right Amiga. This is roughly equivalent to turning the power off, then on again. Memory is reset. Also called warm boot.

; redirect
: To change the source or destination of a command's input or output from the default by using the special characters < or >.

; requester
: A window that appears when the system needs a response from you. A requester contains action gadgets that give you a choice of continuing or aborting the operation in progress. To exit the requester, you must select one of the displayed gadgets.

; resident
: Describes a command or program that has been copied into memory, with the RESIDENT command, for quicker execution. Resident commands are specially set up to prevent reloading on subsequent executions. Only pure files can be made resident.

; resolution
: The dimensions, in pixels, associated with a particular display mode. For example, a normal NTSC High Res screen has a resolution of 640 (horizontal) by 200 (vertical) pixels.

; RGB (Red-Green-Blue)
: A type of video signal in which the three primary color signals are sent separately. Standard Amiga output uses an RGB monitor.

; ROM (Read Only Memory)
: Permanent memory that is pre-programmed with system instructions and does not change. The contents of ROM are not affected by user commands or program operation.

; root block
: The area of a disk that contains the name of the disk and information pertaining to the disk layout. If the root block is erased, you cannot retrieve any information from the disk -- it is effectively blank.

; root directory
: The main directory on a volume. The root directory is at the top of the filing hierarchy and is created when a volume is formatted. All other directories on the volume exist within the root. The root directory is specified by the volume name followed by a colon.

; scaling
: Changing the size of an image or font for printing or display. Usually, a screen image is scaled down to a smaller size for printing, but you can also enlarge, or scale up, an image.

; screen
: An area of the display that has certain graphical attributes, such as resolution and colors. Screens are always at least the full width of the viewable area. The Amiga can have several screens with different attributes open and visible at once.

; script
: A text file containing a series of commands that can be automatically executed to perform a complex or repetitive task. An example of a script is the Startup-sequence file executed when you boot your Amiga.

; scroll
: To move through the viewing area of a window or list.

; scroll arrows
: Gadgets that may appear in a window to allow you to move the viewing area continuously.

; scroll bar
: The highlighted area within the scroll boy that can be dragged to display the hidden contents of a window. It changes in size to indicate the portion of the window that is currently visible.

; scroll box
: The shaded area within which the scroll bar can be dragged. You can click in the scroll box to move the scroll bar.

; scroll gadget
: A gadget that can appear in a window to let you move through a list of options or through the viewing area of a window. A scroll gadget is made up of the scroll bar, scroll box, and scroll arrows.

; scrolling list
: The options that appear inside a scroll gadget. If the list is too long to be displayed in the scroll gadget, you can use the scroll bar or scroll arrows to move (scroll) through the list.

; search path
: The list of directories that AmigaDOS uses when it is looking for a command. Directories are added or removed from the search path with the PATH command.

; select
: To choose an item to work with by pointing to it with the mouse, then clicking the selection button.

; selection button
: The left mouse button.

; selection gadget
: A gadget from which you can choose one of several displayed options, often used for colors.

; serial
: An interface port that transfers data a single bit at a time, contrasted to a parallel interface which sends one complete byte (eight bits) at a time. The Amiga has an external serial port to which a modem, MIDI interface, or printer is often connected.

; set
: To change a bit or flag to its on or enabled state. Opposite of clear.

; Shell
: The command line interface used to send typed commands to the Amiga. The Shell is a console window that supports many special features, such as command-line history, aliases, and copy and paste operations.

; sizing gadget
: A gadget that can appear in the lower right corner of a window to allow you to enlarge or shrink the size of the window.

; slider gadget
: A gadget from which you can select a value by dragging a bar through the gadget. As you move the slider bar, different values are displayed.

; slider value
: A number that appears next to a slider gadget to indicate the currently selected value.

; smoothing
: A printing option available in the PrinterGfx editor that attempts to eliminate, or smooth, jagged lines that can sometimes appear in printouts.

; snapshot
: To save the positions of a window and/or the icons within it.

; source
: A device, drawer, or file that is supplying information. for example, when you copy a disk, the disk you are copying is the source disk.

; stack
: A special area of RAM reserved by a program for temporary storage.

; Startup-sequence
: An AmigaDOS script file, executed when the Amiga is booted, that helps set up the hardware and directory systems.

; stop bits
: Extra bits added to signal the end of a character, used during serial communication.

; string
: A piece of text treated as a single unit.

; subdirectory
: A directory that is within another directory; equivalent to a drawer within a drawer.

; submenu
: A secondary menu that appears when some menu items are highlighted. If a menu item has a submenu, a » symbol appears to the right of the menu item.

; swap
: To alternately place different floppy disks into the same drive, as when performing a single-drive disk copy.

; SYS:
: The name assigned to the volume that the Amiga searches for its system files and directories. Usually the volume booted from.

; text gadget
: A rectangular box in which you can type information, such as a filename or command. Text gadgets are used by the Rename and Execute Command menu items, as well as many programs.

; threshold
: A PrinterGfx value related to color intensity. It determines which colors are printed as black and which are printed as white during black-and-white printing.

; timestamp
: The date and time associated with a file or directory. This is usually the date and time when the file or directory was created or last modified.

; title bar
: The top border of a screen or window, which commonly displays the name of the screen or window.

; toggle
: An option that can be switched between two states, such as on and off.

; tool
: A program that creates or uses data, such as a text editor or paint program.

; Tool Type
: An optional parameter that you can enter in an icon's Information window to control a program. For example, if you enter the SECONDS Tool Type in the Clock's Information window, the Clock displays the seconds when it is opened. For a list of standard Tool Types and a basic explanation of how they work refer to the [[UI_Style_Guide_Workbench#Tool_Types_and_Default_Tool|Amiga User Interface Style Guide]].

; Trashcan
: A directory for storing files that you want to delete.

; type ahead
: A feature of the Shell that lets you enter commands as a previous command's output is being displayed.

; User-startup
: A user-created file containing specific system settings that are red and executed during the system startup sequence.

; volume
: A mounted storage unit, such as a floppy disk or hard disk partition.

; volume name
: The name of a volume, as distinguished from its device name. Renaming a disk changes its volume name, not its device name.

; wildcard
: A symbol used in pattern matching to represent a range of possible values, such as when specifying filenames that all start or end with the same character. The question mark (?), for example, is used as a wildcard to match any single character.

; window
: A rectangular screen area that can accept or display information. A window has a title bar identifying it and may contain gadgets in its border.

; Workbench
: The Amiga's icon-based, graphical user interface.

; write
: To record data in memory or on a storage medium such as a floppy disk.

; write-enable
: To allow information to be written onto a storage device. When a floppy disk is write-enabled or Read/Write, a small, plastic tab is covering the hole in the corner of the disk.

; write-protect
: To prevent information from being written onto a storage device. Floppy disks have a plastic tab that can be moved to write-protect the entire disk, making it read-only. Also called write-inhibit.

; zoom gadget
: A gadget that may appear in the upper right corner of a window to allow the window to alternate between two sizes.

Icon Library

2016-05-18T15:55:53Z

Brian Deneen: /* The Tool Types Array */ added actual link to the UI Style Guide list of standard tool types

= The Icon Library =

The ''.info'' file is the center of interaction between applications and Workbench. To help support the Workbench iconic interface and manage ''.info'' files, the Amiga operating system provides the icon library. The icon library allows you to create icons for data files and directories under program control and examine icons to obtain their Tool Types and other characteristics.

= Icon Library Data Structures =

The preceding sections discussed how icons are used to pass file name arguments to an application run from the Workbench. Workbench allows other types of arguments to be passed in the Tool Types array of an icon. To examine the Tool Types array or find other characteristics of the icon such as its type, applications need to read in the ''.info'' file for the icon.

== The DiskObject Structure ==

The actual data present in the ''.info'' file is organized as a DiskObject structure which is defined in the include file <workbench/workbench.h>. For a complete listing, see the SDK. The DiskObject structure contains the following elements:

<syntaxhighlight>
struct DiskObject
{
UWORD do_Magic; /* magic number at start of file */
UWORD do_Version; /* so we can change structure */
struct Gadget do_Gadget; /* a copy of in core gadget */
UBYTE do_Type;
char *do_DefaultTool;
char **do_ToolTypes;
LONG do_CurrentX;
LONG do_CurrentY;
struct DrawerData *do_DrawerData;
char *do_ToolWindow; /* only applies to tools */
LONG do_StackSize; /* only applies to tools */
};
</syntaxhighlight>

; do_Magic
: A magic number that the icon library looks for to make sure that the file it is reading really contains an icon. It should be the manifest constant WB_DISKMAGIC. PutDiskObject() will put this value in the structure, and GetDiskObject will not believe that a file is really an icon unless this value is correct.

; do_Version
: This provides a way to enhance the .info file in an upwardly-compatible way. It should be WB_DISKVERSION. The icon library will set this value for you and will not believe weird values.

; do_Gadget
: This contains all the imagery for the icon. See the "Gadget Structure" section below for more details.

; do_Type
: The type of the icon; can be set to any of the following values.

:{| class="wikitable"
| WBDISK || The root of a disk
|-
| WBDRAWER || A directory on the disk
|-
| WBTOOL || An executable program
|-
| WBPROJECT || A data file
|-
| WBGARBAGE || The Trashcan directory
|-
| WBKICK || A Kickstart disk
|-
| WBAPPICON || Any object not directly associated with a filing system object, such as a print spooler.
|}

; do_DefaultTool
: Default tools are used for project and disk icons. For projects (data files), the default tool is the program Workbench runs when the project is activated. Any valid AmigaDOS path may be entered in this field such as "SYS:myprogram", "df0:mypaint", "myeditor" or ":work/mytool".

: For disk icons, the default tool is the diskcopy program ("SYS:System/DiskCopy") that will be used when ''this disk is the source'' of a copy.

; do_ToolTypes
: This is an array of free-format strings. Workbench does not enforce any rules on these strings, but they are useful for passing environment information. See the section on "The ToolTypes Array" below for more information.

; do_CurrentX, do_CurrentY
: Drawers have a virtual coordinate system. The user can scroll around in this system using the scroll gadgets on the window that opens when the drawer is activated. Each icon in the drawer has a position in the coordinate system. CurrentX and CurrentY contain the icon's current position in the drawer. Picking a position for a newly created icon can be tricky. NO_ICON_POSITION is a system constant for do_CurrentX and do_CurrentY that instructs Workbench to pick a reasonable place for the icon. Workbench will place the icon in an unused region of the drawer. If there is no space in the drawers window, the icon will be placed just to the right of the visible region.

; do_DrawerData
: If the icon is associated with a directory (WBDISK, WBDRAWER, WBGARBAGE), it needs a DrawerData structure to go with it. This structure contains an Intuition NewWindow structure (see [[Intuition Windows]] for more information):

<syntaxhighlight>
struct DrawerData
{
struct NewWindow dd_NewWindow; /* structure to open window */
LONG dd_CurrentX; /* current x coordinate of origin */
LONG dd_CurrentY; /* current y coordinate of origin */
};
</syntaxhighlight>

: Workbench uses this to hold the current window position and size of the window so it will reopen in the same place.

; do_ToolWindow
: This field is reserved for future use.

; do_StackSize
: This is the size of the stack (in bytes) used for running the tool. If this is NULL, then Workbench will use a reasonable default stack size (currently 4K bytes).

{{Note|title=Stack Size is Taken from the Project Icon|text=When a tool is run ''via the default tool mechanism'' (i.e., a project was activated, not the tool itself), Workbench uses the stack size specified in the project's ''.info'' file and the tool's ''.info'' file is ignored.}}

== The Gadget Structure ==

To hold the icon's image, Workbench uses an Intuition Gadget structure, defined in <intuition/intuition.h>. Workbench restricts some of the values of the gadget. All unused fields should be set to 0 or NULL. The Intuition gadget structure members that Workbench icons use are listed below.

; Width
: This is the width (in pixels) of the icon's active region. Any mouse button press within this range will be interpreted as having selected this icon.

; Height
: This is the height (in pixels) of the icon's active region. Any mouse button press within this range will be interpreted as having selected this icon.

; Flags
: The gadget ''must'' be of type GADGIMAGE. Three highlight modes are supported: GADGHCOMP, GADGHIMAGE, and GADGBACKFILL. GADGHCOMP complements everything within the area defined by CurrentX, CurrentY, Width, Height. GADGHIMAGE uses an alternate selection image. GADGBACKFILL is similar to GADGHCOMP, but ensures that there is no "ring" around the selected image. It does this by first complementing the image, and then flooding all color 3 pixels that are on the border of the image to color 0. All other flag bits should be 0.

; Activation
: The activation should have only RELVERIFY and GADGIMMEDIATE set.

; Type
: The gadget type should be BOOLGADGET.

; GadgetRender
: Set this to an appropriate Image structure.

; SelectRender
: Set this to an appropriate alternate Image structure if and only if the highlight mode is GADGHIMAGE.

The Image structure is typically the same size as the gadget, except that Height is often one pixel less than the gadget height. This allows a blank line between the icon image and the icon name. The image depth ''must'' be 2; PlanePick ''must'' be 3; and PlaneOnOff should be 0. The NextImage field should be null.

= Icon Library Functions =

The icon library functions do all the work needed to read, write and examine an icon's ''.info'' file and corresponding DiskObject structure:

<syntaxhighlight>
struct DiskObject *GetDiskObject(UBYTE *name);
struct DiskObject *GetDiskObjectNew(UBYTE *name);
BOOL PutDiskObject(UBYTE *name, struct DiskObject *diskobj);
void FreeDiskObject(struct DiskObject *diskobj);
BOOL DeleteDiskObject(UBYTE *);

UBYTE *FindToolType(UBYTE **toolTypeArray, UBYTE *typeName);
BOOL MatchToolValue(UBYTE *typeString, UBYTE *value);

struct DiskObject *GetDefDiskObjectNew(LONG type);
BOOL PutDefDiskObject(struct DiskObject *diskobj);

UBYTE *BumpRevision(UBYTE *newbuf, UBYTE *oldname);
</syntaxhighlight>

The icon library routine GetDiskObject() reads an icon's ''.info'' file from disk into a DiskObject structure it creates in memory where it can be examined or altered. PutDiskObject() writes the DiskObject out to disk and FreeDiskObject() frees the memory it used. If you modify any pointers in a DiskObject acquired via GetDiskObject(), replace the old pointers before calling FreeDiskObject() so that the proper memory will be freed.

GetDiskObjectNew() works the same as GetDiskObject() except that if no ''.info'' file is found, a default DiskObject will be created for you. DeleteDiskObject() is for removing ''.info'' files from disk, and the functions GetDefDiskObject() and PutDefDiskObject() allow the default icons to be copied or replaced with new defaults.

Once an icon's ''.info'' file has been read into a DiskObject structure, the functions FindToolType() and MatchToolType() can be used to examine the icon's Tool Types array.

= The Tool Types Array =

Earlier sections discussed how Workbench passes filenames as arguments to a program that's about to run. Workbench also allows other types of arguments to be passed in the Tool Types array of an icon. The Tool Types array is found in the do_ToolTypes field of the icon's DiskObject structure.

In brief, Tool Types is an array of pointers to strings that contain any information an application wants to store such as the program options that were in effect when the icon was created. These strings can be used to encode information which will be available to all applications that read the icon's ''.info'' file. Users can enter and change a selected icon's Tool Types by choosing Information in the Workbench Icons menu.

Workbench does not place many restrictions on the Tool Types array, but there are a few conventions you should follow. A string may be no more than 128 bytes long. The alphabet used is 8-bit ANSI (for example, normal ASCII with foreign-language extensions). This means that users may enter Tool Type strings containing international characters. Avoid special or nonprinting characters. The case of the characters is currently significant, so the string "Window" is not equal to "WINDOW".

The general format for a Tool Types entry is <''name''>=<''value''>[|<''value''>], where <''name''> is the field name and <''value''> is the text to associate with that name. Multiple values for one name may be separated by a vertical bar. The values may be the type of the file, programs that can access the data, parameters to be passed to an application, etc. For example, a paint program might set:

<pre>
FILETYPE = PaintProgram | ILBM
</pre>

This Tool Type indicates that the file is an ILBM, perhaps with some additional chunks of data specific to PaintProgram.

Tool Type strings have few restrictions but there are some reserved Tool Types that are parsed by Workbench itself when an application is started from an icon. The reserved Tool Types are TOOLPRI=''n'' (sets the Exec task priority at which Workbench will start the application), STARTPRI=''n'' (sets the starting order for icons in the Wbstartup drawer), and DONOTWAIT (tells Workbench not to wait for the return of a program started via an icon in the Wbstartup drawer). In addition to the reserved Tool Types, which applications should not use, there are standard Tool Types, which applications should use only in the standard way. For a list of standard Tool Types refer to the [[UI_Style_Guide_Workbench#Tool_Types_and_Default_Tool|Amiga User Interface Style Guide]].

Two routines are provided to help you deal with the Tool Types array. FindToolType() returns the value of a Tool Type element. Using the above example, if you are looking for FILETYPE, the string "PaintProgram|ILBM" will be returned. MatchToolValue() returns nonzero if the specified string is in the reference value string. This routine knows how to parse vertical bars. For example, using the reference value strings of "PaintProgram" or "ILBM", MatchToolValue() will return TRUE for "ILBM" and "PaintProgram" and FALSE for everything else.

= Example of Reading Icons and Parsing Tool Types =

The following example demonstrates icon creation, icon reading and Tool Type parsing in the Workbench environment. When called from the Shell, the example creates a small data file in RAM: and creates or updates a project icon for the data file. The created project icon points to this example as its default tool. When the new project icon is double-clicked, Workbench will invoke the default tool (this example) as a Workbench process, and pass it a description of the project data file as a Workbench argument (WBArg) in the WBStartup message.

<syntaxhighlight>
/*
** iconexample.c - Workbench icon startup, creation, and parsing example
*/

#include <exec/types.h>
#include <libraries/dos.h>
#include <workbench/workbench.h>
#include <workbench/startup.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/icon.h>

#include <stdlib.h>
#include <stdio.h>
#include <string.h>

/* our functions */
void cleanexit(UBYTE *,LONG);
void cleanup(void);
void message(UBYTE *);
BOOL makeIcon(UBYTE *, char **, char *);
BOOL showToolTypes(struct WBArg *);

UBYTE *projname = "RAM:Example_Project";
UBYTE *conwinname = "CON:10/10/620/180/iconexample";

UBYTE deftoolname[] = {"iconexample"};

USHORT IconImageData1[] = {
/* Plane 0 */
0x0000,0x0000,0x0000,0x1000,0x0000,0x0000,0x0000,0x3000,
0x0FFF,0xFFFC,0x0000,0x3000,0x0800,0x0004,0x0000,0x3000,
0x0800,0x07FF,0xFFC0,0x3000,0x08A8,0xA400,0x00A0,0x3000,
0x0800,0x0400,0x0090,0x3000,0x08AA,0xA400,0x0088,0x3000,
0x0800,0x042A,0xA0FC,0x3000,0x082A,0xA400,0x0002,0x3000,
0x0800,0x0400,0x0002,0x3000,0x0800,0xA42A,0xA0A2,0x3000,
0x0800,0x0400,0x0002,0x3000,0x0950,0xA42A,0x8AA2,0x3000,
0x0800,0x0400,0x0002,0x3000,0x082A,0xA400,0x0002,0x3000,
0x0800,0x042A,0x2AA2,0x3000,0x0FFF,0xFC00,0x0002,0x3000,
0x0000,0x0400,0x0002,0x3000,0x0000,0x07FF,0xFFFE,0x3000,
0x0000,0x0000,0x0000,0x3000,0x7FFF,0xFFFF,0xFFFF,0xF000,
/* Plane 1 */
0xFFFF,0xFFFF,0xFFFF,0xE000,0xD555,0x5555,0x5555,0x4000,
0xD000,0x0001,0x5555,0x4000,0xD7FF,0xFFF9,0x5555,0x4000,
0xD7FF,0xF800,0x0015,0x4000,0xD757,0x5BFF,0xFF55,0x4000,
0xD7FF,0xFBFF,0xFF65,0x4000,0xD755,0x5BFF,0xFF75,0x4000,
0xD7FF,0xFBD5,0x5F01,0x4000,0xD7D5,0x5BFF,0xFFFD,0x4000,
0xD7FF,0xFBFF,0xFFFD,0x4000,0xD7FF,0x5BD5,0x5F5D,0x4000,
0xD7FF,0xFBFF,0xFFFD,0x4000,0xD6AF,0x5BD5,0x755D,0x4000,
0xD7FF,0xFBFF,0xFFFD,0x4000,0xD7D5,0x5BFF,0xFFFD,0x4000,
0xD7FF,0xFBD5,0xD55D,0x4000,0xD000,0x03FF,0xFFFD,0x4000,
0xD555,0x53FF,0xFFFD,0x4000,0xD555,0x5000,0x0001,0x4000,
0xD555,0x5555,0x5555,0x4000,0x8000,0x0000,0x0000,0x0000,
};

struct Image iconImage1 =
{
0, 0, /* Top Corner */
52, 22, 2, /* Width, Height, Depth */
&IconImageData1[0], /* Image Data */
0x003, 0x000, /* PlanePick,PlaneOnOff */
NULL /* Next Image */
};

UBYTE *toolTypes[] =
{
"FILETYPE=text",
"FLAGS=BOLD|ITALICS",
NULL
};

struct DiskObject projIcon =
{
WB_DISKMAGIC, /* Magic Number */
WB_DISKVERSION, /* Version */
{ /* Embedded Gadget Structure */
NULL, /* Next Gadget Pointer */
97,12,52,23, /* Left,Top,Width,Height */
GADGIMAGE|GADGHBOX, /* Flags */
GADGIMMEDIATE|RELVERIFY, /* Activation Flags */
BOOLGADGET, /* Gadget Type */
(APTR)&iconImage1, /* Render Image */
NULL, /* Select Image */
NULL, /* Gadget Text */
NULL, /* Mutual Exclude */
NULL, /* Special Info */
0, /* Gadget ID */
NULL /* User Data */
},
WBPROJECT, /* Icon Type */
deftoolname, /* Default Tool */
toolTypes, /* Tool Type Array */
NO_ICON_POSITION, /* Current X */
NO_ICON_POSITION, /* Current Y */
NULL, /* Drawer Structure */
NULL, /* Tool Window */
4000 /* Stack Size */
};

/* Opens and allocations we must clean up */
struct Library *IconBase = NULL;
struct IconIFace *IIcon = NULL;
FILE *conwin = NULL;
LONG olddir = -1;

BOOL FromWb;

int main(int argc, char **argv)
{
struct WBStartup *WBenchMsg;
struct WBArg *wbarg;
FILE *file;
LONG wLen;
SHORT i;

FromWb = (argc==0) ? TRUE : FALSE;

/* Open icon.library */
IconBase = IExec->OpenLibrary("icon.library", 50);
IIcon = (struct IconIFace*)IExec->GetInterface(IconBase, "main", 1, NULL);
if (IIcon == NULL)
cleanexit("Can't open icon.library\n",RETURN_FAIL);

/* If started from CLI, this example will create a small text
* file RAM:Example_Project, and create an icon for the file
* which points to this program as its default tool.
*/
if(!FromWb)
{
/* Make a sample project (data) file */
wLen = -1;
if(file=fopen(projname,"w"))
{
wLen = fprintf(file,"Have a nice day\n");
fclose(file);
}
if(wLen < 0) cleanexit("Error writing data file\n",RETURN_FAIL);

/* Now save/update icon for this data file */
if(makeIcon(projname, toolTypes, deftoolname))
{
IDOS->Printf("%s data file and icon saved.\n",projname);
IDOS->Printf("Use Workbench menu Icon Information to examine the icon.\n");
IDOS->Printf("Then copy this example (iconexample) to RAM:\n");
IDOS->Printf("and double-click the %s project icon\n",projname);
}
else cleanexit("Error writing icon\n",RETURN_FAIL);
}

else /* Else we are FromWb - ie. we were either
* started by a tool icon, or as in this case,
* by being the default tool of a project icon.
*/
{
if(!(conwin = fopen(conwinname,"r+")))
cleanexit("Can't open output window\n",RETURN_FAIL);

WBenchMsg = (struct WBStartup *)argv;

/* Note wbarg++ at end of FOR statement steps through wbargs.
* First arg is our executable (tool). Any additional args
* are projects/icons passed to us via either extend select
* or default tool method.
*/
for(i=0, wbarg=WBenchMsg->sm_ArgList;
i < WBenchMsg->sm_NumArgs;
i++, wbarg++)
{
/* if there's a directory lock for this wbarg, CD there */
olddir = -1;
if((wbarg->wa_Lock)&&(*wbarg->wa_Name))
olddir = IDOS->CurrentDir(wbarg->wa_Lock);

showToolTypes(wbarg);

if((i>0)&&(*wbarg->wa_Name))
fprintf(conwin,"In Main. We could open the %s file here\n",
wbarg->wa_Name);
if(olddir != -1) IDOS->CurrentDir(olddir); /* CD back where we were */
}
IDOS->Delay(500);
}
cleanup();
return RETURN_OK;
}

BOOL makeIcon(UBYTE *name, char **newtooltypes, char *newdeftool)
{
struct DiskObject *dobj;
char *olddeftool;
char **oldtooltypes;
BOOL success = FALSE;

if(dobj = IIcon->GetDiskObject(name))
{
/* If file already has an icon, we will save off any fields we
* need to update, update those fields, put the object, restore
* the old field pointers and then free the object. This will
* preserve any custom imagery the user has, and the user's
* current placement of the icon. If your application does
* not know where the user currently keeps your application,
* you should not update his dobj->do_DefaultTool.
*/
oldtooltypes = dobj->do_ToolTypes;
olddeftool = dobj->do_DefaultTool;

dobj->do_ToolTypes = newtooltypes;
dobj->do_DefaultTool = newdeftool;

success = IIcon->PutDiskObject(name,dobj);

/* we must restore the original pointers before freeing */
dobj->do_ToolTypes = oldtooltypes;
dobj->do_DefaultTool = olddeftool;
IIcon->FreeDiskObject(dobj);
}
/* Else, put our default icon */
if(!success) success = IIcon->PutDiskObject(name,&projIcon);
return(success);
}

BOOL showToolTypes(struct WBArg *wbarg)
{
struct DiskObject *dobj;
char **toolarray;
char *s;
BOOL success = FALSE;

fprintf(conwin,"\nWBArg Lock=0x%lx, Name=%s\n",
wbarg->wa_Lock,wbarg->wa_Name);

if((*wbarg->wa_Name) && (dobj = IIcon->GetDiskObject(wbarg->wa_Name)))
{
fprintf(conwin," We have read the DiskObject (icon) for this arg\n");
toolarray = (char **)dobj->do_ToolTypes;

if(s=(char *)IIcon->FindToolType(toolarray,"FILETYPE"))
{
fprintf(conwin," Found tooltype FILETYPE with value %s\n",s);
}
if(s=(char *)IIcon->FindToolType(toolarray,"FLAGS"))
{
fprintf(conwin," Found tooltype FLAGS with value %s\n",s);
if(IIcon->MatchToolValue(s,"BOLD"))
fprintf(conwin," BOLD flag requested\n");
if(IIcon->MatchToolValue(s,"ITALICS"))
fprintf(conwin," ITALICS flag requested\n");
}
/* Free the diskobject we got */
IIcon->FreeDiskObject(dobj);
success = TRUE;
}
else if(!(*wbarg->wa_Name))
fprintf(conwin," Must be a disk or drawer icon\n");
else
fprintf(conwin," Can't find any DiskObject (icon) for this WBArg\n");
return(success);
}

/* Workbench-started programs with no output window may want to display
* messages in a different manner (requester, window title, etc)
*/
void message(UBYTE *s)
{
if(FromWb && conwin) fprintf(conwin,s,strlen(s));
else if (!FromWb) printf(s);
}

void cleanexit(UBYTE *s, LONG n)
{
if(*s) message(s);
cleanup();
exit(n);
}

void cleanup()
{
if(conwin) fclose(conwin);
IExec->DropInterface((struct Interface*)IIcon);
IExec->CloseLibrary(IconBase);
}
</syntaxhighlight>

= Function Reference =

The following are brief descriptions of the functions in icon.library. See SDK for details on each function call.

{| class="wikitable"
|+ Icon Library Functions
|-
! Function
! Description
|-
| GetDiskObject()
| Read the ''.info'' file of an icon into a DiskObject structure
|-
| GetDiskObjectNew()
| Same as GetDiskObject() but returns a default icon if none exists
|-
| PutDiskObject()
| Write a DiskObject structure to disk as a ''.info'' file
|-
| FreeDiskObject()
| Free the DiskObject structure created by GetDiskObject()
|-
| DeleteDiskObject()
| Deletes a given ''.info'' file from disk
|-
| FindToolType()
| Return the value of an entry in the icon's Tool Type array
|-
| MatchToolValue()
| Check a Tool Type entry against a given value
|-
| GetDefDiskObject()
| Read the default icon for a given icon type
|-
| PutDefDiskObject()
| Replace the default icon for a given icon type
|-
| AddFreeList()
| Add memory you have allocated to a FreeList
|-
| FreeFreeList()
| Free all the memory for entries in the FreeList
|-
| BumpRevision()
| Create a new name for a second copy of a Workbench object
|}

AmigaOS Manual: AmigaDOS Advanced Features

2016-05-18T14:43:06Z

Brian Deneen: /* Using PIPE: */ corrected typo "yource" to "source"

The information in this appendix is intended for experienced AmigaDOS users. It includes the following:

* Customizing the window
* Customizing your Shell environment
* Using Escape sequences
* Customizing startup files

= Customizing the Window =

The Shell supports a WINDOW Tool Type in the Shell icon that allows you to specify the size, position, and features of the Shell window. The format of the Tool Types is as follows:

WINDOW=CON:x/y/width/height/title/option/options

For a description of the options and arguments for the Shell window specification, see the description of the NEWSHELL command in Chapter 6 and the examples in Chapter 8.

== Public Screens - PUBSCREEN Option ==

Applications creating screens can mark them as public, enabling other applications and utilities to open windows on the same screen. AmigaDOS commands that have PUBSCREEN/K in their templates allow the commands to open windows on public screens.

For example, the Input Preferences editor template contains PUBSCREEN/K; open this editor on a public screen by entering the following:

1> INPUT PUBSCREEN "public screen name"

You must supply the name of the public screen. The internal names for public screens are given by applications and do not necessarily match the screen title printed in the screen's title bar. A screen's name can be the same as the application's name; however, consult the application's documentation to determine if it opens public screens and how it names them.

= Customizing the Shell =

You can customize your Shell environment by changing the S:Shell-startup file, which is a script that is executed each time a new Shell is opened. You can edit Shell-startup to set up command aliases and to change the Shell prompt.

== Using Aliases ==

An aliases is an abbreviation for a long and/or frequently used command. Aliases can be local or global. Local aliases are entered in a Shell window and are only recognized in that Shell. Global aliases area entered into the Shell-startup file and are recognized by all Shells.

The Alias format is as follows:

ALIAS <name> <string>

where <name> is the alias name to be entered at the Shell prompt to execute a command. The <string> is the command line to be executed.

See Chapter 6 for a full description of the ALIAS command and Chapter 8 for a list of useful aliases.

== Changing the Prompt ==

The PROMPT command lets you customize the Shell prompt. By default, it shows the process number, a period, the current directory, a right angle bracket (>), and a space:

1.Workbench:>

The prompt can display almost anything, with or without the process number and directory information. The return code of the last command executed can be included. The prompt can contain escape sequences, allowing you to change text color and style in the prompt string or clear the screen.

Benefits of customizing your Shell prompt include making the prompt:

* Easier to distinguish from commands and their output
* Match a prompt style with which you are familiar
* More informative
* Shorter

See Chapter 8 for examples of how to use escape sequences to make the prompt more readable.

= Using Escape Sequences =

Escape sequences can control how the text appears in a console window, such as the texrt color, style (bold, italics, underline), and margins. AmigaDOS recognizes standard ANSI X3.64 sequences entered on the command line or embedded in strings. Escape sequences consist of one or more characters, sometimes with a numerical argument, prefaced by the escape character. Spaces are not normally used in the sequence of characters.

The escape sequence is shown using the following format:

Esc[#X

where:

{| class="wikitable"
| Esc || Represents the Escape key. Press Esc or substitute *E if you are in an application such as ED that uses the Esc key for its own purposes. When you press Esc, a reversed-color open bracket ([) appears in the console window.
|-
| [ || Represents the open bracket key, displayed in Figure D-1. If you country's keyboard does not have an open bracket key, press Alt plus the key shown, regardless of what is shown on the keycap.
|-
| # || Represents a numerical argument.
|-
| X || Represents an alphabetic key. Escape codes are case-sensitive. If an upper case letter is shown, press Shift and the key. If a lower case letter is shown, press the unshifted key.
|}

[[File:DosFigD-1.png|center|frame|Open Bracket Key Location]]

The standard escape sequences for console windows are:

{| class="wikitable"
! Sequence !! Action
|-
| Escc || Clears the window and resets all modes to defaults.
|-
| Esc[0m || Resets graphics modes to defaults.
|-
| Esc[1m || Turns on text boldface.
|-
| Esc[3m || Turns on text italic.
|-
| Esc[4m || Turns on text underlining.
|-
| Esc[7m || Turns on reverse video text.
|-
| Esc[8m || Makes text match background color.
|-
| Esc[22m || Turns off boldface.
|-
| Esc[23m || Turns off italics.
|-
| Esc[24m || Turns off underlining.
|-
| Esc[27m || Turns off reverse video.
|-
| Esc[28m || Returns the text color to normal.
|-
| Esc[30m || Turns on text color0 (background, default grey).
|-
| Esc[31m || Turns on text color1 (shadow, default black).
|-
| Esc[32m || Turns on text color2 (shine, default white).
|-
| Esc[33m || Turns on text color3 (accent, default blue).
|-
| Esc[3#m || Turns on text color# (4-7).
|-
| Esc[39m || Turns on text default color (color1).
|-
| Esc[40m || Turns on text background color0 (default grey).
|-
| Esc[41m || Turns on text background color1 (default black).
|-
| Esc[42m || Turns on text background color2 (default white).
|-
| Esc[43, || Turns on text background color3 (default blue).
|-
| Esc[4#m || Turns on text background color# (4-7).
|-
| Esc[49m || Turns on default text background color (color0).
|-
| Esc[#u || Sets maximum length of lines in window to #.
|-
| Esc[#t || Sets maximum number of lines in window to #.
|-
| Esc[#x || Starts text # pixels from left edge of window.
|-
| Esc[#y || Starts text # pixels from top edge of window.
|}

The escape sequence is executed when you press Return or when the string containing the sequence is printed.

Certain characters cannot normally be used in string arguments for AmgaDOS commands. Preceding these characters with an asterisk allows them to be used in string arguments for most commands, as follows.

{| class="wikitable"
| *E || Represents the Escape key in a string.
|-
| *N || Forces a new line in the output.
|-
| *" || Allows a quotation mark character inside quotation marks.
|-
| ** || Gives a single asterisk.
|}

= Customizing Startup Files =

Each time your Amiga is booted, it executes the Startup-sequence script file Startup-sequence script file located in the S: directory. The Startup-sequence file allocates disk buffers, makes device assignments, reads saved Preferences settings, and performs other functions that configure the Amiga for use.

Because any errors introduced into the Startup-sequence file can cause a fatal disruption of the normal system startup, we strongly recommend that you do not alter your Startup-sequence file. Instead, we recommend that you create a file called User-startup in the S:directory. Creating a User-startup file allows you to customize your system at startup while preventing any disruption of the normal booting process. This file is automatically executed by the Startup-sequence before opening Workbench.

{{Note|Do not modify the original Startup-sequence file. Altering your Startup-sequence file can cause fatal system startup errors.}}

The User-startup and other startup files in the S:directory can be modified to run programs at startup, print special introductory messages, or automatically open a Shell window on the Workbench screen. Any AmigaDOS command can appear in a startup script, including commands to execute other scripts.

Refer to Chapters 6 and 7 for complete specifications about each command before making changes to any existing script.

= Editing Startup Files =

If you have a floppy-only system, make changes to your startup files only if you are working on a copy of your Workbench disk, not the original. If you make a mistake in your startup files and the execution of the Startup-sequence is aborted, only a Shell prompt remains. Normally, the FAILAT 21 command ensures that the Startup-sequence completes execution even after an error.

As long as you do not alter your standard Startup-sequence file, the possibility of a serious startup error is unlikely. If you attempt to boot from a disk that has no file named S:Startup-sequence or there is serious error in the startup process, you may see a screen similar to that shown in Figure D-2.

[[File:DosFigD-2.png|center|frame|AmigaDOS Boot Failure Shell Window]]

This is a Shell window at which you can enter commands, but from which your usual aliases and search path may not be available. This Shell allows you to try to edit the startup file that caused the problem. Because the system has not been fully configured, this can be difficult. It is usually easier to reboot using a different disk.

When editing your User-startup file:

* Be sure to use the correct command syntax. Test any commands you plan to insert into the User-startup in a Shell window first. If a command works properly in the Shell, it should work as expected in the User-startup.
* Pay attention to the order of commands commands:order of commands in script in the script. Some commands, such ECHOcommands:ECHO and RESIDENT, can be put anywhere. However, when inserting commands that refer to directories and files, an error can result if you reference anything that has not yet been created, assigned, or given a valid path.
* Specify the complete path to directories that you wish to access.
* Add commands to your scripts. If you insert a semicolon at the end of a command line, anything to the right of the semicolon is ignored by AmigaDOS, but appears in the script as a comment. For example:
: ASSIGN T: RAM:T ; set up directory for scripts
: explains why you inserted the command.
* Test changes to your User-startup file. When experimenting with your User-startup file, reboot your Amiga after each change to test the result. However, be sure to wait until you are sure the file is completely written to disk before the reboot to avoid potential data loss.

== Common Additions to the Startup Files ==

The following is a list of some of the most common additions that can be made to your startup files.

* Opening a Shell window
* Adding directories to the search path
* Adding logical device names to the assign list
* Making additional commands resident
* Starting input commodities and other programs
* Adding drive cache buffers

= Using PIPE: =

The PIPE: device transfers data from one program to another using temporary storage in RAM. Use a pipe: when you wish to apply output from one process as input to another process. Using a pipe to transfer data reduces the possibility of running out of memory when working with very large files and eliminates the need to create, save, and later delete a file needed only once.

The source and destination processes cannot be the same when using PIPE:. As you write information to the pipe, another process can read the data in First In First Out (FIFO) order. Providing a name after PIPE: gives the pipe a name.

Data sent to PIPE: is buffered in memory. When another application reds the pipe it gets the data in the order it came in. The pipe stays in RAM until its contents are emptied by the reading processes or until the next reboot.

PIPE: uses at least a 4 KB buffer per pipe-name. When the maximum buffer capacity is reached, PIPE: stops accepting data until another process reads data out of the buffer. If a process is reading data, it waits until more data arrives in the buffer. Buffer size can only be specified on the first reference to a particular channel.

The following are the options for PIPE:PIPE:options.

{| class="wikitable"
| channel_name || A unique channel name. Must begin with a non-numeric character. The channel_name is optional; using PIPE: alone is possible if not using multiple pipes.
|-
| Buf_size || Size in bytes of the buffer to allocate. (The default size is 4 KB). The buf_size is optional.
|-
| max_buffers || Maximum number of buffers allowed. Suspends the output channel if exceeded. Max_buffers = 0 indicates there should be no fixed limit on the number of buffers allocated.
|}

PIPE: can be used from other programs, such as word processors or terminal programs. You can use any pipe-name. If the application reads the file sequentially, you can specify PIPE:<name> and it appears the same as an ordinary file to the application.

Information from one pipe can be copied to another. For example:

Shell window 1:
COPY Hugefile PIPE:a

Shell window 2:
COPY PIPE:a PIPE:b

Shell window 3:
COPY PIPE:b PIPE:c

Shell window 4:
COPY PIPE:b PIPE:d

Shell window 5:
COPY PIPE:d PIPE:e

Shell window 6:
TYPE PIPE:e ;Hugefile is TYPEd

The DOSDrivers mount file for PIPE: mount files:for PIPE:is as follows:

Handler = L:Queue Handler
Priority = 5
StackSize = 3000
GlobVec = -1

PIPE: is mounted by default during the standard Startup-sequence.

See Chapter 8 for additional PIPE: examples.

AmigaOS Manual: AmigaDOS Advanced Features

2016-05-18T14:39:52Z

Brian Deneen: /* Customizing Startup Files */ removed redundant "User-startup file" phrase

The information in this appendix is intended for experienced AmigaDOS users. It includes the following:

* Customizing the window
* Customizing your Shell environment
* Using Escape sequences
* Customizing startup files

= Customizing the Window =

The Shell supports a WINDOW Tool Type in the Shell icon that allows you to specify the size, position, and features of the Shell window. The format of the Tool Types is as follows:

WINDOW=CON:x/y/width/height/title/option/options

For a description of the options and arguments for the Shell window specification, see the description of the NEWSHELL command in Chapter 6 and the examples in Chapter 8.

== Public Screens - PUBSCREEN Option ==

Applications creating screens can mark them as public, enabling other applications and utilities to open windows on the same screen. AmigaDOS commands that have PUBSCREEN/K in their templates allow the commands to open windows on public screens.

For example, the Input Preferences editor template contains PUBSCREEN/K; open this editor on a public screen by entering the following:

1> INPUT PUBSCREEN "public screen name"

You must supply the name of the public screen. The internal names for public screens are given by applications and do not necessarily match the screen title printed in the screen's title bar. A screen's name can be the same as the application's name; however, consult the application's documentation to determine if it opens public screens and how it names them.

= Customizing the Shell =

You can customize your Shell environment by changing the S:Shell-startup file, which is a script that is executed each time a new Shell is opened. You can edit Shell-startup to set up command aliases and to change the Shell prompt.

== Using Aliases ==

An aliases is an abbreviation for a long and/or frequently used command. Aliases can be local or global. Local aliases are entered in a Shell window and are only recognized in that Shell. Global aliases area entered into the Shell-startup file and are recognized by all Shells.

The Alias format is as follows:

ALIAS <name> <string>

where <name> is the alias name to be entered at the Shell prompt to execute a command. The <string> is the command line to be executed.

See Chapter 6 for a full description of the ALIAS command and Chapter 8 for a list of useful aliases.

== Changing the Prompt ==

The PROMPT command lets you customize the Shell prompt. By default, it shows the process number, a period, the current directory, a right angle bracket (>), and a space:

1.Workbench:>

The prompt can display almost anything, with or without the process number and directory information. The return code of the last command executed can be included. The prompt can contain escape sequences, allowing you to change text color and style in the prompt string or clear the screen.

Benefits of customizing your Shell prompt include making the prompt:

* Easier to distinguish from commands and their output
* Match a prompt style with which you are familiar
* More informative
* Shorter

See Chapter 8 for examples of how to use escape sequences to make the prompt more readable.

= Using Escape Sequences =

Escape sequences can control how the text appears in a console window, such as the texrt color, style (bold, italics, underline), and margins. AmigaDOS recognizes standard ANSI X3.64 sequences entered on the command line or embedded in strings. Escape sequences consist of one or more characters, sometimes with a numerical argument, prefaced by the escape character. Spaces are not normally used in the sequence of characters.

The escape sequence is shown using the following format:

Esc[#X

where:

{| class="wikitable"
| Esc || Represents the Escape key. Press Esc or substitute *E if you are in an application such as ED that uses the Esc key for its own purposes. When you press Esc, a reversed-color open bracket ([) appears in the console window.
|-
| [ || Represents the open bracket key, displayed in Figure D-1. If you country's keyboard does not have an open bracket key, press Alt plus the key shown, regardless of what is shown on the keycap.
|-
| # || Represents a numerical argument.
|-
| X || Represents an alphabetic key. Escape codes are case-sensitive. If an upper case letter is shown, press Shift and the key. If a lower case letter is shown, press the unshifted key.
|}

[[File:DosFigD-1.png|center|frame|Open Bracket Key Location]]

The standard escape sequences for console windows are:

{| class="wikitable"
! Sequence !! Action
|-
| Escc || Clears the window and resets all modes to defaults.
|-
| Esc[0m || Resets graphics modes to defaults.
|-
| Esc[1m || Turns on text boldface.
|-
| Esc[3m || Turns on text italic.
|-
| Esc[4m || Turns on text underlining.
|-
| Esc[7m || Turns on reverse video text.
|-
| Esc[8m || Makes text match background color.
|-
| Esc[22m || Turns off boldface.
|-
| Esc[23m || Turns off italics.
|-
| Esc[24m || Turns off underlining.
|-
| Esc[27m || Turns off reverse video.
|-
| Esc[28m || Returns the text color to normal.
|-
| Esc[30m || Turns on text color0 (background, default grey).
|-
| Esc[31m || Turns on text color1 (shadow, default black).
|-
| Esc[32m || Turns on text color2 (shine, default white).
|-
| Esc[33m || Turns on text color3 (accent, default blue).
|-
| Esc[3#m || Turns on text color# (4-7).
|-
| Esc[39m || Turns on text default color (color1).
|-
| Esc[40m || Turns on text background color0 (default grey).
|-
| Esc[41m || Turns on text background color1 (default black).
|-
| Esc[42m || Turns on text background color2 (default white).
|-
| Esc[43, || Turns on text background color3 (default blue).
|-
| Esc[4#m || Turns on text background color# (4-7).
|-
| Esc[49m || Turns on default text background color (color0).
|-
| Esc[#u || Sets maximum length of lines in window to #.
|-
| Esc[#t || Sets maximum number of lines in window to #.
|-
| Esc[#x || Starts text # pixels from left edge of window.
|-
| Esc[#y || Starts text # pixels from top edge of window.
|}

The escape sequence is executed when you press Return or when the string containing the sequence is printed.

Certain characters cannot normally be used in string arguments for AmgaDOS commands. Preceding these characters with an asterisk allows them to be used in string arguments for most commands, as follows.

{| class="wikitable"
| *E || Represents the Escape key in a string.
|-
| *N || Forces a new line in the output.
|-
| *" || Allows a quotation mark character inside quotation marks.
|-
| ** || Gives a single asterisk.
|}

= Customizing Startup Files =

Each time your Amiga is booted, it executes the Startup-sequence script file Startup-sequence script file located in the S: directory. The Startup-sequence file allocates disk buffers, makes device assignments, reads saved Preferences settings, and performs other functions that configure the Amiga for use.

Because any errors introduced into the Startup-sequence file can cause a fatal disruption of the normal system startup, we strongly recommend that you do not alter your Startup-sequence file. Instead, we recommend that you create a file called User-startup in the S:directory. Creating a User-startup file allows you to customize your system at startup while preventing any disruption of the normal booting process. This file is automatically executed by the Startup-sequence before opening Workbench.

{{Note|Do not modify the original Startup-sequence file. Altering your Startup-sequence file can cause fatal system startup errors.}}

The User-startup and other startup files in the S:directory can be modified to run programs at startup, print special introductory messages, or automatically open a Shell window on the Workbench screen. Any AmigaDOS command can appear in a startup script, including commands to execute other scripts.

Refer to Chapters 6 and 7 for complete specifications about each command before making changes to any existing script.

= Editing Startup Files =

If you have a floppy-only system, make changes to your startup files only if you are working on a copy of your Workbench disk, not the original. If you make a mistake in your startup files and the execution of the Startup-sequence is aborted, only a Shell prompt remains. Normally, the FAILAT 21 command ensures that the Startup-sequence completes execution even after an error.

As long as you do not alter your standard Startup-sequence file, the possibility of a serious startup error is unlikely. If you attempt to boot from a disk that has no file named S:Startup-sequence or there is serious error in the startup process, you may see a screen similar to that shown in Figure D-2.

[[File:DosFigD-2.png|center|frame|AmigaDOS Boot Failure Shell Window]]

This is a Shell window at which you can enter commands, but from which your usual aliases and search path may not be available. This Shell allows you to try to edit the startup file that caused the problem. Because the system has not been fully configured, this can be difficult. It is usually easier to reboot using a different disk.

When editing your User-startup file:

* Be sure to use the correct command syntax. Test any commands you plan to insert into the User-startup in a Shell window first. If a command works properly in the Shell, it should work as expected in the User-startup.
* Pay attention to the order of commands commands:order of commands in script in the script. Some commands, such ECHOcommands:ECHO and RESIDENT, can be put anywhere. However, when inserting commands that refer to directories and files, an error can result if you reference anything that has not yet been created, assigned, or given a valid path.
* Specify the complete path to directories that you wish to access.
* Add commands to your scripts. If you insert a semicolon at the end of a command line, anything to the right of the semicolon is ignored by AmigaDOS, but appears in the script as a comment. For example:
: ASSIGN T: RAM:T ; set up directory for scripts
: explains why you inserted the command.
* Test changes to your User-startup file. When experimenting with your User-startup file, reboot your Amiga after each change to test the result. However, be sure to wait until you are sure the file is completely written to disk before the reboot to avoid potential data loss.

== Common Additions to the Startup Files ==

The following is a list of some of the most common additions that can be made to your startup files.

* Opening a Shell window
* Adding directories to the search path
* Adding logical device names to the assign list
* Making additional commands resident
* Starting input commodities and other programs
* Adding drive cache buffers

= Using PIPE: =

The PIPE: device transfers data from one program to another using temporary storage in RAM. Use a pipe: when you wish to apply output from one process as input to another process. Using a pipe to transfer data reduces the possibility of running out of memory when working with very large files and eliminates the need to create, save, and later delete a file needed only once.

The yource and destination processes cannot be the same when using PIPE:. As you write information to the pipe, another process can read the data in First In First Out (FIFO) order. Providing a name after PIPE: gives the pipe a name.

Data sent to PIPE: is buffered in memory. When another application reds the pipe it gets the data in the order it came in. The pipe stays in RAM until its contents are emptied by the reading processes or until the next reboot.

PIPE: uses at least a 4 KB buffer per pipe-name. When the maximum buffer capacity is reached, PIPE: stops accepting data until another process reads data out of the buffer. If a process is reading data, it waits until more data arrives in the buffer. Buffer size can only be specified on the first reference to a particular channel.

The following are the options for PIPE:PIPE:options.

{| class="wikitable"
| channel_name || A unique channel name. Must begin with a non-numeric character. The channel_name is optional; using PIPE: alone is possible if not using multiple pipes.
|-
| Buf_size || Size in bytes of the buffer to allocate. (The default size is 4 KB). The buf_size is optional.
|-
| max_buffers || Maximum number of buffers allowed. Suspends the output channel if exceeded. Max_buffers = 0 indicates there should be no fixed limit on the number of buffers allocated.
|}

PIPE: can be used from other programs, such as word processors or terminal programs. You can use any pipe-name. If the application reads the file sequentially, you can specify PIPE:<name> and it appears the same as an ordinary file to the application.

Information from one pipe can be copied to another. For example:

Shell window 1:
COPY Hugefile PIPE:a

Shell window 2:
COPY PIPE:a PIPE:b

Shell window 3:
COPY PIPE:b PIPE:c

Shell window 4:
COPY PIPE:b PIPE:d

Shell window 5:
COPY PIPE:d PIPE:e

Shell window 6:
TYPE PIPE:e ;Hugefile is TYPEd

The DOSDrivers mount file for PIPE: mount files:for PIPE:is as follows:

Handler = L:Queue Handler
Priority = 5
StackSize = 3000
GlobVec = -1

PIPE: is mounted by default during the standard Startup-sequence.

See Chapter 8 for additional PIPE: examples.

UserDoc:How AmigaOS Works

2015-05-29T06:44:08Z

Brian Deneen: /* Volumes */ Added reference to C: autodocs and corrected usage

As already mentioned, AmigaOS was a pioneer in the early days of personal computing in delivering sophistication that contemporary systems could only have dreamt of and pretended to offer. Today, AmigaOS continues to offer a straightforward elegance that seems to be overlooked in the development of other platforms. Thanks to the concepts behind AmigaOS, the system is easy to understand and to use by everyone.

In this page we will explore all these concepts of AmigaOS. Also you will learn here the naming of all parts of the system.

= Introduction =

AmigaOS is made of different components which are either mandatory (i.e., AmigaOS will not work without them) or components the user can choose to use or not. All these components can have one or mutiple interfaces a user or a developer can use to operate with the components and through them to control the operating system.

= The most important components =

== Exec, the AmigaOS kernel ==

Exec is the kernel of AmigaOS. It is the component that pilots all other components. It is responsible for running programs, dealing with computer memory and managing low-level resources that programs may need. In other words, it organises everything to make the operating system run.

It is made of different parts that cannot be moved outside the kernel: the scheduler, the memory pager and the 68k interpretive emulator.

== AmigaDOS: the underlying system ==

The word "DOS" was originally an acronym for "Disk Operating System". Some say it should be "Disk Based Operating System" as it does a lot more than operate a disk and that it was really an operating system based (stored) on disks. Some say it should be "Device Operating System".

The whole AmigaDOS system includes things such as:

* A set of commands that can be used in the Shell window and elsewhere.
* A system for saving data to disk and retrieving it from disk.
* A system for filing data on disks.
* An interface for peripherals such as keyboards, monitors, printers, etc.
* A method of running programs
* A multitasking system for running more than one program at a time.
* etc. etc. etc.

Read the [[AmigaDOS manual]] to understand and learn everything about AmigaDOS.

== The Graphics library ==

The Graphics library handles every low level graphic operation like designing pixels on the monitor, creating graphic elements (bobs, sprites) and also writing text output.

== Intuition ==

The Intuition library is responsible for every graphical object: windows, screens, gadgets, mouse pointers... It lies between any graphic program and the graphics library.

== The Workbench ==

The Workbench is the graphical place where you will manage your computer and all your files. The name was chosen because the user will use tools to create and work with the computer.

[[File:Wb.png|320px]]

== The Shell ==

While some people prefer to control the operating system using their mouse, others prefer using the keyboard. The shell is a text based window when you can type commands to execute actions in the operating system. In the shell the commands will display the results of their execution.

== ARexx - inter-program communication by scripting ==

The ARexx scripting language can be used to operate the Workbench and other Amiga applications from a script containing ARexx commands. This is extremely useful in performing repetitive tasks or doing what the controlled application was not even designed to do.
After a learning curve, everybody can use ARexx as it is built into the system. The scripts can be executed immediately like any other tool.

= How is my data stored? =
== Files ==
=== Executable files ===
Programs you can start are stored in executable files. They contain binary code directly understandable by the computer. They are files with an executable bit, a flag that shows AmigaOS that such file will do something when started.
An example is a music player. When you start this executable, the player opens and you can start playing music files.

AmigaOS can run two different kinds of executable files: the AmigaOS native programs made for the PowerPC processor and programs created for the Motorola 68k processors. The latter are executed inside an emulation that transcripts them into PowerPC code.

==== Scripts ====

Scripts are text files containing a list of commands. They are not strictly executables like ''binary code'' files but they can be executed by AmigaOS as if they were.
This is the case with AmigaDOS and ARexx scripts. These files need to have the executable bit, and the script bit.

=== Data files ===
Files that are not executable are data files. These contain data that will be manipulated by programs. Some examples are a music file, a video file or a text document.

== Directories/Drawers ==
In order to organise things, files are grouped together. We create "directories" which are like drawers of a cabinet to store different files of the same kind, for example.
Often the name ''directory'' is used when talking about a directory which is stored on a disk. The graphical interface of AmigaOS is called "Workbench," and directories are often called ''drawers''.

Note: directories are often called ''folders'' on other systems. The terms "directory," "drawer" and "folder" are synonymous.

== Disks, partitions and volumes ==
=== Disks ===
Disks are storage media you can purchase at a computer store. We use them to store our files. They can be internal hard disks, external hard drives, USB interface devices (i.e., SD cards, CF cards, "flash" drives, etc.), and floppy disk drives.

=== Partitions ===
A disk is often very big and many users prefer to make it more organised. This is done by virtually splitting the disk into several smaller parts. This operation is known as creating partitions on a disk.

[[File:Partitions.png|Small part of Media Toolbox showing different partitions on the harddisk]]

On this screenshot you can see one harddisk with many partitions. Each color corresponds to a different filesystem which defines how data is stored. Also, you can see a greyed area which is a blank area on the disk (i.e., no partition is defined at this position). Several different file systems can be used on the same Amiga drive. It's your choice.

=== Volumes ===
A partition is a physical area on a disk. To access it with AmigaOS we could read the physical data off the partition. To make it easier AmigaOS uses the concept of volumes. These are virtual representations of a partition. The volumes have a name so AmigaOS and therefore the user can access all files/directories stored on it in a very practical way: just by using its name.

Volume names can refer to either a physical or virtual named space. See the autodoc section for the ASSIGN command in the C: directory as well as the MOUNT command which provides more information on naming and the concept of volumes.

= How to identify files/directories =

== On the Workbench ==

The Workbench being graphical, a lot of things are understandable just by looking at them. That's why icons are often enough to understand what kind of object it represents: a file, a directory, a disk...

In case you have a doubt, just look at the information on an icon. The Workbench will tell you the type of the object. It is displayed next to its name.

== In a shell ==

In a shell the '''list''' command can be used to see if an object is a file or a directory.

[[File:Files-dirs-in-shell.png|The '''list''' command shows a file of 925678 bytes and two directories]]

A file will be displayed with its size, whereas a directory will be displayed with the text '''Dir''' next to it.

Also, as you can see on the screenshot, the list command displays other characteristics on these 3 items: the protection bits and the date they were updated the last time. The command also sums up what it just listed.

= All AmigaOS components =

AmigaOS is made of components that are needed as soon as the system starts or later when the user or the system needs them.

== Kickstart modules ==

These components are the heart of AmigaOS. Their duties is to do graphics, to handle discs or to handle all reads/writes to files. Also one of them is the AmigaOS kernel which is a kind of director handling the work of all other components.
These Kickstart modules are loaded at the beginning of the operating system boot process (read [[UserDoc:How_AmigaOS_Works#AmigaOS_boot_procedure|here]]). You can find all them in the '''Kickstart''' directory in the system volume. Here is a list:

=== Mandatory modules ===

The following modules are required in any AmigaOS system. Without one of these, the system will not start.

* kernel - The kernel works like a conductor in an orchestra. Its job is to make everything works together. It creates processes, handle memory usage, defines the way other components will access peripherals...etc. Note that the AmigaOS kernel is not based on any other kernel. It is a self made kernel that works since 1983.
* loader - this component handles the loading of all other kickstart modules
* battclock.resource.kmod - this module handles reading/writing the battery backed up clock which is used on all computers to keep the date and time
* bootimage - this is the boot picture. It is displayed during the start sequence of AmigaOS
* bootmenu.kmod - this component handles the Early Startup Menu the use can use to define some settings before starting AmigaOS
* con-handler.kmod - it directs the read and write requests to the console window, to a serial AUX: device or any other supported interface
* console.device.kmod - it opens a window and reads/writes text to and from that window
* diskboot.kmod - handles the booting of AmigaOS from a supported disk
* diskboot.config - this is a text file experienced users can modify to change the boot behaviour of AmigaOS
* dos.library.kmod - this module is a collection of functions that any program can use to perform actions on disks, files and directories
* elf.library.kmod - handles the loading of executable programs
* env-handler.kmod - handles the read/writes of environment variables
* FileSystem.resource.kmod - handles the use of the different filesystems
* gadtools.library.kmod - collection of functions used to create all graphic objects like gadgets, sliders, menus...
* gameport.device.kmod - handles the read/writes of game pads and joysticks
* graphics.library.kmod - collection of functions used to draw graphic elements on the monitor
* hunk.library.kmod - set of functions to read a data stream into memory
* input.device.kmod - handles of input events like keyboard events or mouse clicks
* intuition.library.kmod - collection of functions to create and handle all graphic elements (screens, windows, the mouse pointer...)
* layers.library.kmod - set of functions to be used to handle different layers in graphic operations
* keyboard.device.kmod - driver for the keyboard
* keymap.library.kmod - functions to handle different keymaps
* newlib.library.kmod - collection of functions to perform memory operations (allocating memory, copying memory areas... )
* nonvolatile.library.kmod - provides a simple means for an application developer to manage nonvolatile storage
* nvram.resource.kmod - handles the read/writes to the EEPROM chip present on many AmigaOS computers
* PCIGraphics.card - driver that supports the use of different graphic cards
* ram-handler.kmod - functions that handles the '''Ram disk:''' special disk
* ramdrive.device.kmod - device that allows the usage of the ramdrive device '''RAD:''' disk
* ramlib.kmod - loads disk based libraries and devices for exec.library
* rtg.library - library of functions to perform lowlevel graphic operations on graphic cards
* shell.kmod - the AmigaOS command line interface
* strap.kmod - module that handles booting on different disk devices
* timer.device.kmod - driver to give access to timing functions

=== Filesystem support ===

These kickstart modules can be loaded or left aside. If you want to use a particular filesystem on your disk partitions, you need to load the corresponding filesystem module.

* CDFileSystem - handles the CD-ROM disks with data stored in different formats: ISO9660, HFS...
* SmartFilesystem - allows the usage of partitions in SFS0 and SFS2 layouts
* JXFileSystem - allows the usage of partitions in JXFS layout
* FastFileSystem - allows the usage of partitions in FFS and FFS2 layouts
* diskcache.library.kmod - component required by the SmartFileSystem and JXFileSystem modules

=== Hardware drivers ===

==== Graphic cards drivers ====

* 3dfxVoodoo.chip
* 3DLabsPermedia2.chip
* ATIRadeon.chip
* RadeonHD.chip
* siliconmotion502.chip

==== Disk drivers ====

Each of these drivers allow the use of disks connected to a disk controller. These files are named with the name of the controller they support. As an example, the '''sii3114ide.device.kmod''' allows to use disks connected on a '''Silicon Image SiI3114''' controller chip.

* it8212ide.device.kmod
* lsi53c8xx.device.kmod
* sam460sata.device.kmod
* sii3112ide.device.kmod
* sii3512ide.device.kmod
* sii3114ide.device.kmod
* sii0680ide.device.kmod
* sii3132ide.device.kmod

==== USB drivers ====

* hub.usbfd
* usbsys.device
* usbresource.library
* ehci.usbhcd
* ohci.usbhcd
* uhci.usbhcd
* massstorage.usbfd

==== Other drivers ====

* bootkeyboard.usbfd - allows a USB keyboard to be used even before the USB stack is loaded
* bootmouse.usbfd - allows a USB mouse to be used even before the USB stack is loaded
* fpga.resource.kmod - allows to use the FPGA components which are present on some Amiga computers
* i2c.resource.kmod - allows to use the i2c interface present on some Amiga computers
* xena.resource.kmod - provides access to the Xena chip on the AmigaOne X1000

=== Misc modules ===

* petunia.library.kmod - this module contains the Just-In-Time emulator that allows AmigaOS to run programs made for the Motorola 68k processor

== System components ==

[[File:Workbench_directory_listing.png|frame|right|List of directories and files present at the root of any AmigaOS system]]

Beside the kickstart modules, AmigaOS uses many different components that can be loaded only when used. These files are stored in different directories in the system volume.
Here is described a default AmigaOS installation.

* C
This directory contains AmigaDOS '''C'''ommands
* Classes
contains different object elements easy to be used in any program: gadgets, requesters, graphic table, windows...
* Devs
contains definition for '''Dev'''ices
* Emulation
contains files used for the 68k emulation (though E-UAE)
* Fonts
contains various systems fonts
* Internet
contains a dialer to connect to Internet
* Kickstart
contains the kickstart modules
* L
contains hand'''l'''ers and filesystems
* Libs
contains dynamic '''Libr'''airies of functions
* Locale
contains all files used to localise the system (catalogs, keymaps...)
* MUI
contains the needed files for programs that use the MUI third party graphic interface
* [[Prefs]]
contains the preference programs used to customise AmigaOS
* S
contains the '''S'''cripts
* SObjs
contains .so shared object library files
* Storage
contains other optional files
* System
contains some programs used by the system itself (i.e. you don't need to run them yourself) or low-level programs like disk tools
* [[Utilities]]
contains several programs you can use to achieve some tasks on AmigaOS

= Motorola 680x0 Emulators =

For a long time Amigas have had the famous Motorola 680x0 processors as the central unit for execution. Unfortunately the time of the 680x0 series is passing in favor of other architectures. The new era of processors reached the Amiga some time ago, when expansion boards became available for extending the Classic systems with the raw power of a PowerPC processor.

In the old operating system (AmigaOS 3.x) it was not possible to gain the full advantage of the new processors. The system itself and most of the applications required the original Motorola 680x0 processor. There was no 680x0 emulation available for the PowerPCs, so the 680x0 could not be "switched off".

Thus the new processors remained as a powerful, but mostly unused adjunct to the main 680x0 processor. "Native" PowerPC programs were rare, and every time a PowerPC program called the system, a so called "context switch" occurred between the 680x0 and PowerPC code, often causing a large performance penalty.

The new Amiga platform is based on the PowerPC processor family, therefore the new version of the AmigaOS has to smooth the transition from the 680x0 series, which is achieved by emulating the old processor architecture. The operating system itself is written almost 100 percent for the PowerPC processors, but the 680x0 legacy applications require an emulated 680x0 processor.

== Two 680x0 Emulators ==

In version 4.0 of AmigaOS, two different emulators were implemented; one is the successor of BlackBox emulation, it is an interpretive emulator, thus the emulation speed is mediocre. On the other hand it has a very low "reaction time", and is ideal for time critical parts, such as interrupts.

The other is Petunia, the "JIT emulator". A fast, but less compatible way of emulation of the legacy Motorola processors. It is intended mainly for emulating applications, and therefore, when execution of the application leaves the bounds of the application's code segment, emulation falls back to the interpretive method, where it does its job and returns to the JIT emulation again.

Dynamic recompilation (also called just-in-time compilation or simply JIT compilation) is a technique of translating foreign processor machine code to native machine code, "on the fly".

This technique is common nowadays, commonly applied in JAVA virtual machines, and it is also used with success in several emulators. In dynamic recompilation there is the possibility of runtime optimization of the emulated code by collecting statistics of the execution process. Therefore (theoretically) the final executed code can be even faster than the original code on its original processor.

== Features ==

Emulated opcodes:
* all user and supervisor level opcodes of the Motorola 68040
* all FPU opcodes of the Motorola 68881/68882

AmigaOS claims only 68020/68881 compatibility to applications because this is the safest compatibility level, but both emulators are compatible with the machine code up to the level of 68040/060 processors.

At compile time, a low level flag and branch control analysis allows on-the-fly optimizations of compiled code.

== Removing the JIT Emulator ==

Using the dynamic translation requires a lot more memory than the interpretive emulation. The translated code needs to be stored somewhere, not to mention the data collection tables.

If speed is not as important as the memory consumption of the system, then the JIT emulator can be removed, leaving the job to the interpretive emulator.

Thanks to the modular design of AmigaOS kickstart, all you need to do is edit the "Sys:Kickstart/Kicklayout" file, simply put a semicolon (;) at the beginning of the module line of Petunia.library.kmod. After rebooting the system from cold, the JIT emulator will not be reloaded. Make sure that you alter the appropriate configuration in the Kicklayout file, there may be several alternative configurations, with different names like "DefaultJIT", or "DefaultNoJIT".

== Configuring the Emulators ==

Petunia cooperates with a so called "black list". By default Petunia emulates every 680x0 program or library that is loaded by DOS.library/LoadSeg function, but if an executable or library shows incompatibilities with Petunia, then it can be explicitly inhibited from the dynamic recompilation by specifying it in a list file.

If an executable needs to be added to the list, then it can be done by extending the file "DEVS:applications.dos" with the '''Compatibility''' preferences program from the Prefs drawer of the system. Adding a program name to the list and checking it will prevent Petunia from emulating that program, and it will be interpreted instead by the built-in interpreter.

Removing a program from the list or unchecking (thus allowing Petunia to emulate it again) can be done with the same preferences program.

Please note: some programs consist of multiple executables (shared libraries, plugins). If you want to fully disable the translation of such programs, then every part must be added to the list.

For example to disable UnArc fully, you would have to add all files from libs:xad and also xadmaster.library to the list.

= AmigaOS boot procedure =

Basically a computer with AmigaOS does the following when the power button is pushed:

* [[File:Uboot.jpg|200px]]
the BIOS ([[UserDoc:BIOS|Uboot]] or [[UserDoc:BIOS|CFE]]) of the computer initialises the hardware: graphic card, USB ports... At this point, the monitor wakes up and the first information are displayed. This allows to see if hardware is correctly recognised. As an example you can see if a hard drive is correctly connected into the machine and your BIOS is correctly setup to make this drive useable.
* depending on how you setup the BIOS it will look on the harddisk to find the Second Level Booter (SLB). This program is stored on the first sectors of the disk. Whereas the BIOS does not know about AmigaOS disk structure, the SLB will be able to ''understand'' the AmigaOS partitions and files. In other words, it is the link between the BIOS and the rest of the boot procedure. Its goal is also to give you the ability to start several configurations present on the same drive.
* [[File:SLB.png|200px]]
the SLB will analyses all Amiga partitions on the disk it is installed on. It will read each [[UserDoc:kickstart_configuration|system configuration]] it finds on the partitions. It will show all available configurations for the user to select one to load.
The user can define many different kickstart configurations to choose from. Also both AmigaOS and Linux can be selected for boot.
* [[File:Kmods loading.png|200px]]
the SLB loads the kickstart files of the selected configuration and executes the '''Loader''' module
* '''Loader''' executes the kickstart modules (Exec, devices, libraries...)
* AmigaOS becomes alive displaying the AmigaOS boot picture on the monitor
* the AmigaDOS library executes the [[UserDoc:System_Scripts#startup-sequence|startup-sequence]] script found on the system volume
* the Startup-sequence will be executed and all commands it contains are executed. It means that starting from here the boot procedure is easy to follow and understand.
* the Workbench is started

At this point the user can use his/her computer.

= How to make a Bootable USB Memory Stick for AmigaOS 4.1 =

By Julian Margetson ("Spectre660")

Prerequisites:
* USB memory stick of 2 GB or less in size.
* It is best to only have one USB mass storage device connected while you are creating your bootable USB memory stick.
* Plug the USB memory stick into a USB port on your machine.
* Note that the device will be formatted so make sure that you use an empty memory stick or one that does not contain any data that you need or backup the contents before you begin.

Procedure:
# You use Media Toolbox in the System: drawer to prepare the USB stick. On starting Media Toolbox select ''usbdisk.device'' as the device to use.
# Make certain that you have selected usbdisk.device and not any other device.
# Click on "Start"
# You will see the usb mass storage unit connected in a list.
# Make sure that the Unit type displayed for the USB memory stick is "Removable hard disk"
# Select that Unit by clicking on it.
# The first thing that you need to do is to install the RDB onto the USB Memory Stick.
# Click on the "Install" button.
# A window Labeled "RDB/disk geometry editing" comes up.
## Towards the bottom of the window is the "AmigaOne boot code (SLB)" section.
## Select the "Install" button .
## A file requester "Select AmigaOne Boot Code" now comes up with the Drawer choice defaulting to "l:"
## Select file "slb_v2".
## Select Ok.
## You are now returned to the "RDB/disk geometry editing window".
## Select "Ok-accept changes".
# You are now returned to the display showing the attached USB unit.
# Select "Edit partitions and Filesystems". You will now see the Window 'Editing partitions for disk"
# Select "Add partition"
# This defaults to using the whole device as a single partition.
# It is possible to use create more partitions but for this tutorial we will only use one.
# You now need to give the partition a unique name (e.g. USB0 or something that is different from any of the existing partitions on your hard drive). This is done by changing the default DH0 in the "Name" box.
# Now make sure that the Boxes "Automount" and "Bootable" are selected and show the "Tick mark".
# You need to set "Boot priority" to higher than the boot priority of your hard drive boot partition(s). This is done by increasing Boot priority by clicking on the "+" to the right of the "boot priority" box. Normally you can set the boot priority to 2 .
# Next it is time to select the file system to use.
# Select "Select filesystem/edit details".
# The Window "Editing details for partition 'USB0'" ,or whatever partition name you used, comes up.
## Select the file system that you are going to use by selecting the pull down menu under "Filesystem chooser".
## Only filesystems SFS/00 or SFS/02 will work for a bootable device.
## The option that gives the most flexibility at the moment is SFS/00 as a USB stick in this format can be read and written to using another compatible system in the event that you need to make modifications after it is created without a booting AmigaOS 4.1 machine.
## Next select Blocksize from the "Blocksize" pull down menu. 512 is the correct size to use.
## Now Select "Ok-accept changes".
## Your are now returned to the "Edit partitions for disk" window.
## Again select "Ok-accept changes"
# You are now returned to the window showing the USB mass storage unit list.
# Select "Save to disk"
# A requester pops up with the options "Yes, Save." or "No!"
# Select the "Yes, save." option.
# You now close Media Toolbox by clicking on the close icon (X) on the left of the Media Toolbox window.
# This will give you a requester advising that you need to reboot the machine for the changes to take effect. At this point you need to remove the USB memory stick for the machine. If you do not then the Machine will attempt boot from it before it is formatted and the required Kickstart and AmigaOS 4.1 files are copied to it.
# Select "Yes, reboot NOW!".
# Once you have rebooted connect your USB Memory Stick to a USB port.
# A disk icon "USB0:Uninitialized" (or whatever partition name you used) appears on Workbench.
# You now need to format the device.
# To format Select this Icon and go to the Workbench "Icons" menu .
# Select "Format Disk"
# You can give the USB Memory Stick a unique name and select whether you want a Trashcan or not.
# You can use either a full Format or a Quick Format. Full Format may take a few minutes.
# Once formatted the USB Memory Stick is ready for you to copy the required files from you hard drive or AmigaOS Install CD to it in order to boot AmigaOS 4.1 from it.

UserDoc:How AmigaOS Works

2015-05-29T06:30:28Z

Brian Deneen: /* Partitions */ corrected usage, added multiple file system comment.

As already mentioned, AmigaOS was a pioneer in the early days of personal computing in delivering sophistication that contemporary systems could only have dreamt of and pretended to offer. Today, AmigaOS continues to offer a straightforward elegance that seems to be overlooked in the development of other platforms. Thanks to the concepts behind AmigaOS, the system is easy to understand and to use by everyone.

In this page we will explore all these concepts of AmigaOS. Also you will learn here the naming of all parts of the system.

= Introduction =

AmigaOS is made of different components which are either mandatory (i.e., AmigaOS will not work without them) or components the user can choose to use or not. All these components can have one or mutiple interfaces a user or a developer can use to operate with the components and through them to control the operating system.

= The most important components =

== Exec, the AmigaOS kernel ==

Exec is the kernel of AmigaOS. It is the component that pilots all other components. It is responsible for running programs, dealing with computer memory and managing low-level resources that programs may need. In other words, it organises everything to make the operating system run.

It is made of different parts that cannot be moved outside the kernel: the scheduler, the memory pager and the 68k interpretive emulator.

== AmigaDOS: the underlying system ==

The word "DOS" was originally an acronym for "Disk Operating System". Some say it should be "Disk Based Operating System" as it does a lot more than operate a disk and that it was really an operating system based (stored) on disks. Some say it should be "Device Operating System".

The whole AmigaDOS system includes things such as:

* A set of commands that can be used in the Shell window and elsewhere.
* A system for saving data to disk and retrieving it from disk.
* A system for filing data on disks.
* An interface for peripherals such as keyboards, monitors, printers, etc.
* A method of running programs
* A multitasking system for running more than one program at a time.
* etc. etc. etc.

Read the [[AmigaDOS manual]] to understand and learn everything about AmigaDOS.

== The Graphics library ==

The Graphics library handles every low level graphic operation like designing pixels on the monitor, creating graphic elements (bobs, sprites) and also writing text output.

== Intuition ==

The Intuition library is responsible for every graphical object: windows, screens, gadgets, mouse pointers... It lies between any graphic program and the graphics library.

== The Workbench ==

The Workbench is the graphical place where you will manage your computer and all your files. The name was chosen because the user will use tools to create and work with the computer.

[[File:Wb.png|320px]]

== The Shell ==

While some people prefer to control the operating system using their mouse, others prefer using the keyboard. The shell is a text based window when you can type commands to execute actions in the operating system. In the shell the commands will display the results of their execution.

== ARexx - inter-program communication by scripting ==

The ARexx scripting language can be used to operate the Workbench and other Amiga applications from a script containing ARexx commands. This is extremely useful in performing repetitive tasks or doing what the controlled application was not even designed to do.
After a learning curve, everybody can use ARexx as it is built into the system. The scripts can be executed immediately like any other tool.

= How is my data stored? =
== Files ==
=== Executable files ===
Programs you can start are stored in executable files. They contain binary code directly understandable by the computer. They are files with an executable bit, a flag that shows AmigaOS that such file will do something when started.
An example is a music player. When you start this executable, the player opens and you can start playing music files.

AmigaOS can run two different kinds of executable files: the AmigaOS native programs made for the PowerPC processor and programs created for the Motorola 68k processors. The latter are executed inside an emulation that transcripts them into PowerPC code.

==== Scripts ====

Scripts are text files containing a list of commands. They are not strictly executables like ''binary code'' files but they can be executed by AmigaOS as if they were.
This is the case with AmigaDOS and ARexx scripts. These files need to have the executable bit, and the script bit.

=== Data files ===
Files that are not executable are data files. These contain data that will be manipulated by programs. Some examples are a music file, a video file or a text document.

== Directories/Drawers ==
In order to organise things, files are grouped together. We create "directories" which are like drawers of a cabinet to store different files of the same kind, for example.
Often the name ''directory'' is used when talking about a directory which is stored on a disk. The graphical interface of AmigaOS is called "Workbench," and directories are often called ''drawers''.

Note: directories are often called ''folders'' on other systems. The terms "directory," "drawer" and "folder" are synonymous.

== Disks, partitions and volumes ==
=== Disks ===
Disks are storage media you can purchase at a computer store. We use them to store our files. They can be internal hard disks, external hard drives, USB interface devices (i.e., SD cards, CF cards, "flash" drives, etc.), and floppy disk drives.

=== Partitions ===
A disk is often very big and many users prefer to make it more organised. This is done by virtually splitting the disk into several smaller parts. This operation is known as creating partitions on a disk.

[[File:Partitions.png|Small part of Media Toolbox showing different partitions on the harddisk]]

On this screenshot you can see one harddisk with many partitions. Each color corresponds to a different filesystem which defines how data is stored. Also, you can see a greyed area which is a blank area on the disk (i.e., no partition is defined at this position). Several different file systems can be used on the same Amiga drive. It's your choice.

=== Volumes ===
A partition is a physical area on a disk. To access it with AmigaOS we could read the physical data off the partition but it's not an easy way. To make it easier AmigaOS uses the concept of volumes. These are virtual representations of a partition. The volumes have a name so AmigaOS and therefore the user can access all files/directories stored on it in a very practical way: just by using its name.

= How to identify files/directories =

== On the Workbench ==

The Workbench being graphical, a lot of things are understandable just by looking at them. That's why icons are often enough to understand what kind of object it represents: a file, a directory, a disk...

In case you have a doubt, just look at the information on an icon. The Workbench will tell you the type of the object. It is displayed next to its name.

== In a shell ==

In a shell the '''list''' command can be used to see if an object is a file or a directory.

[[File:Files-dirs-in-shell.png|The '''list''' command shows a file of 925678 bytes and two directories]]

A file will be displayed with its size, whereas a directory will be displayed with the text '''Dir''' next to it.

Also, as you can see on the screenshot, the list command displays other characteristics on these 3 items: the protection bits and the date they were updated the last time. The command also sums up what it just listed.

= All AmigaOS components =

AmigaOS is made of components that are needed as soon as the system starts or later when the user or the system needs them.

== Kickstart modules ==

These components are the heart of AmigaOS. Their duties is to do graphics, to handle discs or to handle all reads/writes to files. Also one of them is the AmigaOS kernel which is a kind of director handling the work of all other components.
These Kickstart modules are loaded at the beginning of the operating system boot process (read [[UserDoc:How_AmigaOS_Works#AmigaOS_boot_procedure|here]]). You can find all them in the '''Kickstart''' directory in the system volume. Here is a list:

=== Mandatory modules ===

The following modules are required in any AmigaOS system. Without one of these, the system will not start.

* kernel - The kernel works like a conductor in an orchestra. Its job is to make everything works together. It creates processes, handle memory usage, defines the way other components will access peripherals...etc. Note that the AmigaOS kernel is not based on any other kernel. It is a self made kernel that works since 1983.
* loader - this component handles the loading of all other kickstart modules
* battclock.resource.kmod - this module handles reading/writing the battery backed up clock which is used on all computers to keep the date and time
* bootimage - this is the boot picture. It is displayed during the start sequence of AmigaOS
* bootmenu.kmod - this component handles the Early Startup Menu the use can use to define some settings before starting AmigaOS
* con-handler.kmod - it directs the read and write requests to the console window, to a serial AUX: device or any other supported interface
* console.device.kmod - it opens a window and reads/writes text to and from that window
* diskboot.kmod - handles the booting of AmigaOS from a supported disk
* diskboot.config - this is a text file experienced users can modify to change the boot behaviour of AmigaOS
* dos.library.kmod - this module is a collection of functions that any program can use to perform actions on disks, files and directories
* elf.library.kmod - handles the loading of executable programs
* env-handler.kmod - handles the read/writes of environment variables
* FileSystem.resource.kmod - handles the use of the different filesystems
* gadtools.library.kmod - collection of functions used to create all graphic objects like gadgets, sliders, menus...
* gameport.device.kmod - handles the read/writes of game pads and joysticks
* graphics.library.kmod - collection of functions used to draw graphic elements on the monitor
* hunk.library.kmod - set of functions to read a data stream into memory
* input.device.kmod - handles of input events like keyboard events or mouse clicks
* intuition.library.kmod - collection of functions to create and handle all graphic elements (screens, windows, the mouse pointer...)
* layers.library.kmod - set of functions to be used to handle different layers in graphic operations
* keyboard.device.kmod - driver for the keyboard
* keymap.library.kmod - functions to handle different keymaps
* newlib.library.kmod - collection of functions to perform memory operations (allocating memory, copying memory areas... )
* nonvolatile.library.kmod - provides a simple means for an application developer to manage nonvolatile storage
* nvram.resource.kmod - handles the read/writes to the EEPROM chip present on many AmigaOS computers
* PCIGraphics.card - driver that supports the use of different graphic cards
* ram-handler.kmod - functions that handles the '''Ram disk:''' special disk
* ramdrive.device.kmod - device that allows the usage of the ramdrive device '''RAD:''' disk
* ramlib.kmod - loads disk based libraries and devices for exec.library
* rtg.library - library of functions to perform lowlevel graphic operations on graphic cards
* shell.kmod - the AmigaOS command line interface
* strap.kmod - module that handles booting on different disk devices
* timer.device.kmod - driver to give access to timing functions

=== Filesystem support ===

These kickstart modules can be loaded or left aside. If you want to use a particular filesystem on your disk partitions, you need to load the corresponding filesystem module.

* CDFileSystem - handles the CD-ROM disks with data stored in different formats: ISO9660, HFS...
* SmartFilesystem - allows the usage of partitions in SFS0 and SFS2 layouts
* JXFileSystem - allows the usage of partitions in JXFS layout
* FastFileSystem - allows the usage of partitions in FFS and FFS2 layouts
* diskcache.library.kmod - component required by the SmartFileSystem and JXFileSystem modules

=== Hardware drivers ===

==== Graphic cards drivers ====

* 3dfxVoodoo.chip
* 3DLabsPermedia2.chip
* ATIRadeon.chip
* RadeonHD.chip
* siliconmotion502.chip

==== Disk drivers ====

Each of these drivers allow the use of disks connected to a disk controller. These files are named with the name of the controller they support. As an example, the '''sii3114ide.device.kmod''' allows to use disks connected on a '''Silicon Image SiI3114''' controller chip.

* it8212ide.device.kmod
* lsi53c8xx.device.kmod
* sam460sata.device.kmod
* sii3112ide.device.kmod
* sii3512ide.device.kmod
* sii3114ide.device.kmod
* sii0680ide.device.kmod
* sii3132ide.device.kmod

==== USB drivers ====

* hub.usbfd
* usbsys.device
* usbresource.library
* ehci.usbhcd
* ohci.usbhcd
* uhci.usbhcd
* massstorage.usbfd

==== Other drivers ====

* bootkeyboard.usbfd - allows a USB keyboard to be used even before the USB stack is loaded
* bootmouse.usbfd - allows a USB mouse to be used even before the USB stack is loaded
* fpga.resource.kmod - allows to use the FPGA components which are present on some Amiga computers
* i2c.resource.kmod - allows to use the i2c interface present on some Amiga computers
* xena.resource.kmod - provides access to the Xena chip on the AmigaOne X1000

=== Misc modules ===

* petunia.library.kmod - this module contains the Just-In-Time emulator that allows AmigaOS to run programs made for the Motorola 68k processor

== System components ==

[[File:Workbench_directory_listing.png|frame|right|List of directories and files present at the root of any AmigaOS system]]

Beside the kickstart modules, AmigaOS uses many different components that can be loaded only when used. These files are stored in different directories in the system volume.
Here is described a default AmigaOS installation.

* C
This directory contains AmigaDOS '''C'''ommands
* Classes
contains different object elements easy to be used in any program: gadgets, requesters, graphic table, windows...
* Devs
contains definition for '''Dev'''ices
* Emulation
contains files used for the 68k emulation (though E-UAE)
* Fonts
contains various systems fonts
* Internet
contains a dialer to connect to Internet
* Kickstart
contains the kickstart modules
* L
contains hand'''l'''ers and filesystems
* Libs
contains dynamic '''Libr'''airies of functions
* Locale
contains all files used to localise the system (catalogs, keymaps...)
* MUI
contains the needed files for programs that use the MUI third party graphic interface
* [[Prefs]]
contains the preference programs used to customise AmigaOS
* S
contains the '''S'''cripts
* SObjs
contains .so shared object library files
* Storage
contains other optional files
* System
contains some programs used by the system itself (i.e. you don't need to run them yourself) or low-level programs like disk tools
* [[Utilities]]
contains several programs you can use to achieve some tasks on AmigaOS

= Motorola 680x0 Emulators =

For a long time Amigas have had the famous Motorola 680x0 processors as the central unit for execution. Unfortunately the time of the 680x0 series is passing in favor of other architectures. The new era of processors reached the Amiga some time ago, when expansion boards became available for extending the Classic systems with the raw power of a PowerPC processor.

In the old operating system (AmigaOS 3.x) it was not possible to gain the full advantage of the new processors. The system itself and most of the applications required the original Motorola 680x0 processor. There was no 680x0 emulation available for the PowerPCs, so the 680x0 could not be "switched off".

Thus the new processors remained as a powerful, but mostly unused adjunct to the main 680x0 processor. "Native" PowerPC programs were rare, and every time a PowerPC program called the system, a so called "context switch" occurred between the 680x0 and PowerPC code, often causing a large performance penalty.

The new Amiga platform is based on the PowerPC processor family, therefore the new version of the AmigaOS has to smooth the transition from the 680x0 series, which is achieved by emulating the old processor architecture. The operating system itself is written almost 100 percent for the PowerPC processors, but the 680x0 legacy applications require an emulated 680x0 processor.

== Two 680x0 Emulators ==

In version 4.0 of AmigaOS, two different emulators were implemented; one is the successor of BlackBox emulation, it is an interpretive emulator, thus the emulation speed is mediocre. On the other hand it has a very low "reaction time", and is ideal for time critical parts, such as interrupts.

The other is Petunia, the "JIT emulator". A fast, but less compatible way of emulation of the legacy Motorola processors. It is intended mainly for emulating applications, and therefore, when execution of the application leaves the bounds of the application's code segment, emulation falls back to the interpretive method, where it does its job and returns to the JIT emulation again.

Dynamic recompilation (also called just-in-time compilation or simply JIT compilation) is a technique of translating foreign processor machine code to native machine code, "on the fly".

This technique is common nowadays, commonly applied in JAVA virtual machines, and it is also used with success in several emulators. In dynamic recompilation there is the possibility of runtime optimization of the emulated code by collecting statistics of the execution process. Therefore (theoretically) the final executed code can be even faster than the original code on its original processor.

== Features ==

Emulated opcodes:
* all user and supervisor level opcodes of the Motorola 68040
* all FPU opcodes of the Motorola 68881/68882

AmigaOS claims only 68020/68881 compatibility to applications because this is the safest compatibility level, but both emulators are compatible with the machine code up to the level of 68040/060 processors.

At compile time, a low level flag and branch control analysis allows on-the-fly optimizations of compiled code.

== Removing the JIT Emulator ==

Using the dynamic translation requires a lot more memory than the interpretive emulation. The translated code needs to be stored somewhere, not to mention the data collection tables.

If speed is not as important as the memory consumption of the system, then the JIT emulator can be removed, leaving the job to the interpretive emulator.

Thanks to the modular design of AmigaOS kickstart, all you need to do is edit the "Sys:Kickstart/Kicklayout" file, simply put a semicolon (;) at the beginning of the module line of Petunia.library.kmod. After rebooting the system from cold, the JIT emulator will not be reloaded. Make sure that you alter the appropriate configuration in the Kicklayout file, there may be several alternative configurations, with different names like "DefaultJIT", or "DefaultNoJIT".

== Configuring the Emulators ==

Petunia cooperates with a so called "black list". By default Petunia emulates every 680x0 program or library that is loaded by DOS.library/LoadSeg function, but if an executable or library shows incompatibilities with Petunia, then it can be explicitly inhibited from the dynamic recompilation by specifying it in a list file.

If an executable needs to be added to the list, then it can be done by extending the file "DEVS:applications.dos" with the '''Compatibility''' preferences program from the Prefs drawer of the system. Adding a program name to the list and checking it will prevent Petunia from emulating that program, and it will be interpreted instead by the built-in interpreter.

Removing a program from the list or unchecking (thus allowing Petunia to emulate it again) can be done with the same preferences program.

Please note: some programs consist of multiple executables (shared libraries, plugins). If you want to fully disable the translation of such programs, then every part must be added to the list.

For example to disable UnArc fully, you would have to add all files from libs:xad and also xadmaster.library to the list.

= AmigaOS boot procedure =

Basically a computer with AmigaOS does the following when the power button is pushed:

* [[File:Uboot.jpg|200px]]
the BIOS ([[UserDoc:BIOS|Uboot]] or [[UserDoc:BIOS|CFE]]) of the computer initialises the hardware: graphic card, USB ports... At this point, the monitor wakes up and the first information are displayed. This allows to see if hardware is correctly recognised. As an example you can see if a hard drive is correctly connected into the machine and your BIOS is correctly setup to make this drive useable.
* depending on how you setup the BIOS it will look on the harddisk to find the Second Level Booter (SLB). This program is stored on the first sectors of the disk. Whereas the BIOS does not know about AmigaOS disk structure, the SLB will be able to ''understand'' the AmigaOS partitions and files. In other words, it is the link between the BIOS and the rest of the boot procedure. Its goal is also to give you the ability to start several configurations present on the same drive.
* [[File:SLB.png|200px]]
the SLB will analyses all Amiga partitions on the disk it is installed on. It will read each [[UserDoc:kickstart_configuration|system configuration]] it finds on the partitions. It will show all available configurations for the user to select one to load.
The user can define many different kickstart configurations to choose from. Also both AmigaOS and Linux can be selected for boot.
* [[File:Kmods loading.png|200px]]
the SLB loads the kickstart files of the selected configuration and executes the '''Loader''' module
* '''Loader''' executes the kickstart modules (Exec, devices, libraries...)
* AmigaOS becomes alive displaying the AmigaOS boot picture on the monitor
* the AmigaDOS library executes the [[UserDoc:System_Scripts#startup-sequence|startup-sequence]] script found on the system volume
* the Startup-sequence will be executed and all commands it contains are executed. It means that starting from here the boot procedure is easy to follow and understand.
* the Workbench is started

At this point the user can use his/her computer.

= How to make a Bootable USB Memory Stick for AmigaOS 4.1 =

By Julian Margetson ("Spectre660")

Prerequisites:
* USB memory stick of 2 GB or less in size.
* It is best to only have one USB mass storage device connected while you are creating your bootable USB memory stick.
* Plug the USB memory stick into a USB port on your machine.
* Note that the device will be formatted so make sure that you use an empty memory stick or one that does not contain any data that you need or backup the contents before you begin.

Procedure:
# You use Media Toolbox in the System: drawer to prepare the USB stick. On starting Media Toolbox select ''usbdisk.device'' as the device to use.
# Make certain that you have selected usbdisk.device and not any other device.
# Click on "Start"
# You will see the usb mass storage unit connected in a list.
# Make sure that the Unit type displayed for the USB memory stick is "Removable hard disk"
# Select that Unit by clicking on it.
# The first thing that you need to do is to install the RDB onto the USB Memory Stick.
# Click on the "Install" button.
# A window Labeled "RDB/disk geometry editing" comes up.
## Towards the bottom of the window is the "AmigaOne boot code (SLB)" section.
## Select the "Install" button .
## A file requester "Select AmigaOne Boot Code" now comes up with the Drawer choice defaulting to "l:"
## Select file "slb_v2".
## Select Ok.
## You are now returned to the "RDB/disk geometry editing window".
## Select "Ok-accept changes".
# You are now returned to the display showing the attached USB unit.
# Select "Edit partitions and Filesystems". You will now see the Window 'Editing partitions for disk"
# Select "Add partition"
# This defaults to using the whole device as a single partition.
# It is possible to use create more partitions but for this tutorial we will only use one.
# You now need to give the partition a unique name (e.g. USB0 or something that is different from any of the existing partitions on your hard drive). This is done by changing the default DH0 in the "Name" box.
# Now make sure that the Boxes "Automount" and "Bootable" are selected and show the "Tick mark".
# You need to set "Boot priority" to higher than the boot priority of your hard drive boot partition(s). This is done by increasing Boot priority by clicking on the "+" to the right of the "boot priority" box. Normally you can set the boot priority to 2 .
# Next it is time to select the file system to use.
# Select "Select filesystem/edit details".
# The Window "Editing details for partition 'USB0'" ,or whatever partition name you used, comes up.
## Select the file system that you are going to use by selecting the pull down menu under "Filesystem chooser".
## Only filesystems SFS/00 or SFS/02 will work for a bootable device.
## The option that gives the most flexibility at the moment is SFS/00 as a USB stick in this format can be read and written to using another compatible system in the event that you need to make modifications after it is created without a booting AmigaOS 4.1 machine.
## Next select Blocksize from the "Blocksize" pull down menu. 512 is the correct size to use.
## Now Select "Ok-accept changes".
## Your are now returned to the "Edit partitions for disk" window.
## Again select "Ok-accept changes"
# You are now returned to the window showing the USB mass storage unit list.
# Select "Save to disk"
# A requester pops up with the options "Yes, Save." or "No!"
# Select the "Yes, save." option.
# You now close Media Toolbox by clicking on the close icon (X) on the left of the Media Toolbox window.
# This will give you a requester advising that you need to reboot the machine for the changes to take effect. At this point you need to remove the USB memory stick for the machine. If you do not then the Machine will attempt boot from it before it is formatted and the required Kickstart and AmigaOS 4.1 files are copied to it.
# Select "Yes, reboot NOW!".
# Once you have rebooted connect your USB Memory Stick to a USB port.
# A disk icon "USB0:Uninitialized" (or whatever partition name you used) appears on Workbench.
# You now need to format the device.
# To format Select this Icon and go to the Workbench "Icons" menu .
# Select "Format Disk"
# You can give the USB Memory Stick a unique name and select whether you want a Trashcan or not.
# You can use either a full Format or a Quick Format. Full Format may take a few minutes.
# Once formatted the USB Memory Stick is ready for you to copy the required files from you hard drive or AmigaOS Install CD to it in order to boot AmigaOS 4.1 from it.

UserDoc:How AmigaOS Works

2015-05-29T06:27:51Z

Brian Deneen: /* Disks */ corrected usage, added device names

As already mentioned, AmigaOS was a pioneer in the early days of personal computing in delivering sophistication that contemporary systems could only have dreamt of and pretended to offer. Today, AmigaOS continues to offer a straightforward elegance that seems to be overlooked in the development of other platforms. Thanks to the concepts behind AmigaOS, the system is easy to understand and to use by everyone.

In this page we will explore all these concepts of AmigaOS. Also you will learn here the naming of all parts of the system.

= Introduction =

AmigaOS is made of different components which are either mandatory (i.e., AmigaOS will not work without them) or components the user can choose to use or not. All these components can have one or mutiple interfaces a user or a developer can use to operate with the components and through them to control the operating system.

= The most important components =

== Exec, the AmigaOS kernel ==

Exec is the kernel of AmigaOS. It is the component that pilots all other components. It is responsible for running programs, dealing with computer memory and managing low-level resources that programs may need. In other words, it organises everything to make the operating system run.

It is made of different parts that cannot be moved outside the kernel: the scheduler, the memory pager and the 68k interpretive emulator.

== AmigaDOS: the underlying system ==

The word "DOS" was originally an acronym for "Disk Operating System". Some say it should be "Disk Based Operating System" as it does a lot more than operate a disk and that it was really an operating system based (stored) on disks. Some say it should be "Device Operating System".

The whole AmigaDOS system includes things such as:

* A set of commands that can be used in the Shell window and elsewhere.
* A system for saving data to disk and retrieving it from disk.
* A system for filing data on disks.
* An interface for peripherals such as keyboards, monitors, printers, etc.
* A method of running programs
* A multitasking system for running more than one program at a time.
* etc. etc. etc.

Read the [[AmigaDOS manual]] to understand and learn everything about AmigaDOS.

== The Graphics library ==

The Graphics library handles every low level graphic operation like designing pixels on the monitor, creating graphic elements (bobs, sprites) and also writing text output.

== Intuition ==

The Intuition library is responsible for every graphical object: windows, screens, gadgets, mouse pointers... It lies between any graphic program and the graphics library.

== The Workbench ==

The Workbench is the graphical place where you will manage your computer and all your files. The name was chosen because the user will use tools to create and work with the computer.

[[File:Wb.png|320px]]

== The Shell ==

While some people prefer to control the operating system using their mouse, others prefer using the keyboard. The shell is a text based window when you can type commands to execute actions in the operating system. In the shell the commands will display the results of their execution.

== ARexx - inter-program communication by scripting ==

The ARexx scripting language can be used to operate the Workbench and other Amiga applications from a script containing ARexx commands. This is extremely useful in performing repetitive tasks or doing what the controlled application was not even designed to do.
After a learning curve, everybody can use ARexx as it is built into the system. The scripts can be executed immediately like any other tool.

= How is my data stored? =
== Files ==
=== Executable files ===
Programs you can start are stored in executable files. They contain binary code directly understandable by the computer. They are files with an executable bit, a flag that shows AmigaOS that such file will do something when started.
An example is a music player. When you start this executable, the player opens and you can start playing music files.

AmigaOS can run two different kinds of executable files: the AmigaOS native programs made for the PowerPC processor and programs created for the Motorola 68k processors. The latter are executed inside an emulation that transcripts them into PowerPC code.

==== Scripts ====

Scripts are text files containing a list of commands. They are not strictly executables like ''binary code'' files but they can be executed by AmigaOS as if they were.
This is the case with AmigaDOS and ARexx scripts. These files need to have the executable bit, and the script bit.

=== Data files ===
Files that are not executable are data files. These contain data that will be manipulated by programs. Some examples are a music file, a video file or a text document.

== Directories/Drawers ==
In order to organise things, files are grouped together. We create "directories" which are like drawers of a cabinet to store different files of the same kind, for example.
Often the name ''directory'' is used when talking about a directory which is stored on a disk. The graphical interface of AmigaOS is called "Workbench," and directories are often called ''drawers''.

Note: directories are often called ''folders'' on other systems. The terms "directory," "drawer" and "folder" are synonymous.

== Disks, partitions and volumes ==
=== Disks ===
Disks are storage media you can purchase at a computer store. We use them to store our files. They can be internal hard disks, external hard drives, USB interface devices (i.e., SD cards, CF cards, "flash" drives, etc.), and floppy disk drives.

=== Partitions ===
A disk is often very big and many users prefer to make it more organised. This is done virtually splitting the disk into several smaller parts. This operation is known as creating partitions on a disk.

[[File:Partitions.png|Small part of Media Toolbox showing different partitions on the harddisk]]

On this screenshot you can see one harddisk with many partitions. Each color corresponds to a different filesystem which defines how data is stored. Also you can see a greyed area which is a blank area on the disk i.e. no partition is defined at this position.

=== Volumes ===
A partition is a physical area on a disk. To access it with AmigaOS we could read the physical data off the partition but it's not an easy way. To make it easier AmigaOS uses the concept of volumes. These are virtual representations of a partition. The volumes have a name so AmigaOS and therefore the user can access all files/directories stored on it in a very practical way: just by using its name.

= How to identify files/directories =

== On the Workbench ==

The Workbench being graphical, a lot of things are understandable just by looking at them. That's why icons are often enough to understand what kind of object it represents: a file, a directory, a disk...

In case you have a doubt, just look at the information on an icon. The Workbench will tell you the type of the object. It is displayed next to its name.

== In a shell ==

In a shell the '''list''' command can be used to see if an object is a file or a directory.

[[File:Files-dirs-in-shell.png|The '''list''' command shows a file of 925678 bytes and two directories]]

A file will be displayed with its size, whereas a directory will be displayed with the text '''Dir''' next to it.

Also, as you can see on the screenshot, the list command displays other characteristics on these 3 items: the protection bits and the date they were updated the last time. The command also sums up what it just listed.

= All AmigaOS components =

AmigaOS is made of components that are needed as soon as the system starts or later when the user or the system needs them.

== Kickstart modules ==

These components are the heart of AmigaOS. Their duties is to do graphics, to handle discs or to handle all reads/writes to files. Also one of them is the AmigaOS kernel which is a kind of director handling the work of all other components.
These Kickstart modules are loaded at the beginning of the operating system boot process (read [[UserDoc:How_AmigaOS_Works#AmigaOS_boot_procedure|here]]). You can find all them in the '''Kickstart''' directory in the system volume. Here is a list:

=== Mandatory modules ===

The following modules are required in any AmigaOS system. Without one of these, the system will not start.

* kernel - The kernel works like a conductor in an orchestra. Its job is to make everything works together. It creates processes, handle memory usage, defines the way other components will access peripherals...etc. Note that the AmigaOS kernel is not based on any other kernel. It is a self made kernel that works since 1983.
* loader - this component handles the loading of all other kickstart modules
* battclock.resource.kmod - this module handles reading/writing the battery backed up clock which is used on all computers to keep the date and time
* bootimage - this is the boot picture. It is displayed during the start sequence of AmigaOS
* bootmenu.kmod - this component handles the Early Startup Menu the use can use to define some settings before starting AmigaOS
* con-handler.kmod - it directs the read and write requests to the console window, to a serial AUX: device or any other supported interface
* console.device.kmod - it opens a window and reads/writes text to and from that window
* diskboot.kmod - handles the booting of AmigaOS from a supported disk
* diskboot.config - this is a text file experienced users can modify to change the boot behaviour of AmigaOS
* dos.library.kmod - this module is a collection of functions that any program can use to perform actions on disks, files and directories
* elf.library.kmod - handles the loading of executable programs
* env-handler.kmod - handles the read/writes of environment variables
* FileSystem.resource.kmod - handles the use of the different filesystems
* gadtools.library.kmod - collection of functions used to create all graphic objects like gadgets, sliders, menus...
* gameport.device.kmod - handles the read/writes of game pads and joysticks
* graphics.library.kmod - collection of functions used to draw graphic elements on the monitor
* hunk.library.kmod - set of functions to read a data stream into memory
* input.device.kmod - handles of input events like keyboard events or mouse clicks
* intuition.library.kmod - collection of functions to create and handle all graphic elements (screens, windows, the mouse pointer...)
* layers.library.kmod - set of functions to be used to handle different layers in graphic operations
* keyboard.device.kmod - driver for the keyboard
* keymap.library.kmod - functions to handle different keymaps
* newlib.library.kmod - collection of functions to perform memory operations (allocating memory, copying memory areas... )
* nonvolatile.library.kmod - provides a simple means for an application developer to manage nonvolatile storage
* nvram.resource.kmod - handles the read/writes to the EEPROM chip present on many AmigaOS computers
* PCIGraphics.card - driver that supports the use of different graphic cards
* ram-handler.kmod - functions that handles the '''Ram disk:''' special disk
* ramdrive.device.kmod - device that allows the usage of the ramdrive device '''RAD:''' disk
* ramlib.kmod - loads disk based libraries and devices for exec.library
* rtg.library - library of functions to perform lowlevel graphic operations on graphic cards
* shell.kmod - the AmigaOS command line interface
* strap.kmod - module that handles booting on different disk devices
* timer.device.kmod - driver to give access to timing functions

=== Filesystem support ===

These kickstart modules can be loaded or left aside. If you want to use a particular filesystem on your disk partitions, you need to load the corresponding filesystem module.

* CDFileSystem - handles the CD-ROM disks with data stored in different formats: ISO9660, HFS...
* SmartFilesystem - allows the usage of partitions in SFS0 and SFS2 layouts
* JXFileSystem - allows the usage of partitions in JXFS layout
* FastFileSystem - allows the usage of partitions in FFS and FFS2 layouts
* diskcache.library.kmod - component required by the SmartFileSystem and JXFileSystem modules

=== Hardware drivers ===

==== Graphic cards drivers ====

* 3dfxVoodoo.chip
* 3DLabsPermedia2.chip
* ATIRadeon.chip
* RadeonHD.chip
* siliconmotion502.chip

==== Disk drivers ====

Each of these drivers allow the use of disks connected to a disk controller. These files are named with the name of the controller they support. As an example, the '''sii3114ide.device.kmod''' allows to use disks connected on a '''Silicon Image SiI3114''' controller chip.

* it8212ide.device.kmod
* lsi53c8xx.device.kmod
* sam460sata.device.kmod
* sii3112ide.device.kmod
* sii3512ide.device.kmod
* sii3114ide.device.kmod
* sii0680ide.device.kmod
* sii3132ide.device.kmod

==== USB drivers ====

* hub.usbfd
* usbsys.device
* usbresource.library
* ehci.usbhcd
* ohci.usbhcd
* uhci.usbhcd
* massstorage.usbfd

==== Other drivers ====

* bootkeyboard.usbfd - allows a USB keyboard to be used even before the USB stack is loaded
* bootmouse.usbfd - allows a USB mouse to be used even before the USB stack is loaded
* fpga.resource.kmod - allows to use the FPGA components which are present on some Amiga computers
* i2c.resource.kmod - allows to use the i2c interface present on some Amiga computers
* xena.resource.kmod - provides access to the Xena chip on the AmigaOne X1000

=== Misc modules ===

* petunia.library.kmod - this module contains the Just-In-Time emulator that allows AmigaOS to run programs made for the Motorola 68k processor

== System components ==

[[File:Workbench_directory_listing.png|frame|right|List of directories and files present at the root of any AmigaOS system]]

Beside the kickstart modules, AmigaOS uses many different components that can be loaded only when used. These files are stored in different directories in the system volume.
Here is described a default AmigaOS installation.

* C
This directory contains AmigaDOS '''C'''ommands
* Classes
contains different object elements easy to be used in any program: gadgets, requesters, graphic table, windows...
* Devs
contains definition for '''Dev'''ices
* Emulation
contains files used for the 68k emulation (though E-UAE)
* Fonts
contains various systems fonts
* Internet
contains a dialer to connect to Internet
* Kickstart
contains the kickstart modules
* L
contains hand'''l'''ers and filesystems
* Libs
contains dynamic '''Libr'''airies of functions
* Locale
contains all files used to localise the system (catalogs, keymaps...)
* MUI
contains the needed files for programs that use the MUI third party graphic interface
* [[Prefs]]
contains the preference programs used to customise AmigaOS
* S
contains the '''S'''cripts
* SObjs
contains .so shared object library files
* Storage
contains other optional files
* System
contains some programs used by the system itself (i.e. you don't need to run them yourself) or low-level programs like disk tools
* [[Utilities]]
contains several programs you can use to achieve some tasks on AmigaOS

= Motorola 680x0 Emulators =

For a long time Amigas have had the famous Motorola 680x0 processors as the central unit for execution. Unfortunately the time of the 680x0 series is passing in favor of other architectures. The new era of processors reached the Amiga some time ago, when expansion boards became available for extending the Classic systems with the raw power of a PowerPC processor.

In the old operating system (AmigaOS 3.x) it was not possible to gain the full advantage of the new processors. The system itself and most of the applications required the original Motorola 680x0 processor. There was no 680x0 emulation available for the PowerPCs, so the 680x0 could not be "switched off".

Thus the new processors remained as a powerful, but mostly unused adjunct to the main 680x0 processor. "Native" PowerPC programs were rare, and every time a PowerPC program called the system, a so called "context switch" occurred between the 680x0 and PowerPC code, often causing a large performance penalty.

The new Amiga platform is based on the PowerPC processor family, therefore the new version of the AmigaOS has to smooth the transition from the 680x0 series, which is achieved by emulating the old processor architecture. The operating system itself is written almost 100 percent for the PowerPC processors, but the 680x0 legacy applications require an emulated 680x0 processor.

== Two 680x0 Emulators ==

In version 4.0 of AmigaOS, two different emulators were implemented; one is the successor of BlackBox emulation, it is an interpretive emulator, thus the emulation speed is mediocre. On the other hand it has a very low "reaction time", and is ideal for time critical parts, such as interrupts.

The other is Petunia, the "JIT emulator". A fast, but less compatible way of emulation of the legacy Motorola processors. It is intended mainly for emulating applications, and therefore, when execution of the application leaves the bounds of the application's code segment, emulation falls back to the interpretive method, where it does its job and returns to the JIT emulation again.

Dynamic recompilation (also called just-in-time compilation or simply JIT compilation) is a technique of translating foreign processor machine code to native machine code, "on the fly".

This technique is common nowadays, commonly applied in JAVA virtual machines, and it is also used with success in several emulators. In dynamic recompilation there is the possibility of runtime optimization of the emulated code by collecting statistics of the execution process. Therefore (theoretically) the final executed code can be even faster than the original code on its original processor.

== Features ==

Emulated opcodes:
* all user and supervisor level opcodes of the Motorola 68040
* all FPU opcodes of the Motorola 68881/68882

AmigaOS claims only 68020/68881 compatibility to applications because this is the safest compatibility level, but both emulators are compatible with the machine code up to the level of 68040/060 processors.

At compile time, a low level flag and branch control analysis allows on-the-fly optimizations of compiled code.

== Removing the JIT Emulator ==

Using the dynamic translation requires a lot more memory than the interpretive emulation. The translated code needs to be stored somewhere, not to mention the data collection tables.

If speed is not as important as the memory consumption of the system, then the JIT emulator can be removed, leaving the job to the interpretive emulator.

Thanks to the modular design of AmigaOS kickstart, all you need to do is edit the "Sys:Kickstart/Kicklayout" file, simply put a semicolon (;) at the beginning of the module line of Petunia.library.kmod. After rebooting the system from cold, the JIT emulator will not be reloaded. Make sure that you alter the appropriate configuration in the Kicklayout file, there may be several alternative configurations, with different names like "DefaultJIT", or "DefaultNoJIT".

== Configuring the Emulators ==

Petunia cooperates with a so called "black list". By default Petunia emulates every 680x0 program or library that is loaded by DOS.library/LoadSeg function, but if an executable or library shows incompatibilities with Petunia, then it can be explicitly inhibited from the dynamic recompilation by specifying it in a list file.

If an executable needs to be added to the list, then it can be done by extending the file "DEVS:applications.dos" with the '''Compatibility''' preferences program from the Prefs drawer of the system. Adding a program name to the list and checking it will prevent Petunia from emulating that program, and it will be interpreted instead by the built-in interpreter.

Removing a program from the list or unchecking (thus allowing Petunia to emulate it again) can be done with the same preferences program.

Please note: some programs consist of multiple executables (shared libraries, plugins). If you want to fully disable the translation of such programs, then every part must be added to the list.

For example to disable UnArc fully, you would have to add all files from libs:xad and also xadmaster.library to the list.

= AmigaOS boot procedure =

Basically a computer with AmigaOS does the following when the power button is pushed:

* [[File:Uboot.jpg|200px]]
the BIOS ([[UserDoc:BIOS|Uboot]] or [[UserDoc:BIOS|CFE]]) of the computer initialises the hardware: graphic card, USB ports... At this point, the monitor wakes up and the first information are displayed. This allows to see if hardware is correctly recognised. As an example you can see if a hard drive is correctly connected into the machine and your BIOS is correctly setup to make this drive useable.
* depending on how you setup the BIOS it will look on the harddisk to find the Second Level Booter (SLB). This program is stored on the first sectors of the disk. Whereas the BIOS does not know about AmigaOS disk structure, the SLB will be able to ''understand'' the AmigaOS partitions and files. In other words, it is the link between the BIOS and the rest of the boot procedure. Its goal is also to give you the ability to start several configurations present on the same drive.
* [[File:SLB.png|200px]]
the SLB will analyses all Amiga partitions on the disk it is installed on. It will read each [[UserDoc:kickstart_configuration|system configuration]] it finds on the partitions. It will show all available configurations for the user to select one to load.
The user can define many different kickstart configurations to choose from. Also both AmigaOS and Linux can be selected for boot.
* [[File:Kmods loading.png|200px]]
the SLB loads the kickstart files of the selected configuration and executes the '''Loader''' module
* '''Loader''' executes the kickstart modules (Exec, devices, libraries...)
* AmigaOS becomes alive displaying the AmigaOS boot picture on the monitor
* the AmigaDOS library executes the [[UserDoc:System_Scripts#startup-sequence|startup-sequence]] script found on the system volume
* the Startup-sequence will be executed and all commands it contains are executed. It means that starting from here the boot procedure is easy to follow and understand.
* the Workbench is started

At this point the user can use his/her computer.

= How to make a Bootable USB Memory Stick for AmigaOS 4.1 =

By Julian Margetson ("Spectre660")

Prerequisites:
* USB memory stick of 2 GB or less in size.
* It is best to only have one USB mass storage device connected while you are creating your bootable USB memory stick.
* Plug the USB memory stick into a USB port on your machine.
* Note that the device will be formatted so make sure that you use an empty memory stick or one that does not contain any data that you need or backup the contents before you begin.

Procedure:
# You use Media Toolbox in the System: drawer to prepare the USB stick. On starting Media Toolbox select ''usbdisk.device'' as the device to use.
# Make certain that you have selected usbdisk.device and not any other device.
# Click on "Start"
# You will see the usb mass storage unit connected in a list.
# Make sure that the Unit type displayed for the USB memory stick is "Removable hard disk"
# Select that Unit by clicking on it.
# The first thing that you need to do is to install the RDB onto the USB Memory Stick.
# Click on the "Install" button.
# A window Labeled "RDB/disk geometry editing" comes up.
## Towards the bottom of the window is the "AmigaOne boot code (SLB)" section.
## Select the "Install" button .
## A file requester "Select AmigaOne Boot Code" now comes up with the Drawer choice defaulting to "l:"
## Select file "slb_v2".
## Select Ok.
## You are now returned to the "RDB/disk geometry editing window".
## Select "Ok-accept changes".
# You are now returned to the display showing the attached USB unit.
# Select "Edit partitions and Filesystems". You will now see the Window 'Editing partitions for disk"
# Select "Add partition"
# This defaults to using the whole device as a single partition.
# It is possible to use create more partitions but for this tutorial we will only use one.
# You now need to give the partition a unique name (e.g. USB0 or something that is different from any of the existing partitions on your hard drive). This is done by changing the default DH0 in the "Name" box.
# Now make sure that the Boxes "Automount" and "Bootable" are selected and show the "Tick mark".
# You need to set "Boot priority" to higher than the boot priority of your hard drive boot partition(s). This is done by increasing Boot priority by clicking on the "+" to the right of the "boot priority" box. Normally you can set the boot priority to 2 .
# Next it is time to select the file system to use.
# Select "Select filesystem/edit details".
# The Window "Editing details for partition 'USB0'" ,or whatever partition name you used, comes up.
## Select the file system that you are going to use by selecting the pull down menu under "Filesystem chooser".
## Only filesystems SFS/00 or SFS/02 will work for a bootable device.
## The option that gives the most flexibility at the moment is SFS/00 as a USB stick in this format can be read and written to using another compatible system in the event that you need to make modifications after it is created without a booting AmigaOS 4.1 machine.
## Next select Blocksize from the "Blocksize" pull down menu. 512 is the correct size to use.
## Now Select "Ok-accept changes".
## Your are now returned to the "Edit partitions for disk" window.
## Again select "Ok-accept changes"
# You are now returned to the window showing the USB mass storage unit list.
# Select "Save to disk"
# A requester pops up with the options "Yes, Save." or "No!"
# Select the "Yes, save." option.
# You now close Media Toolbox by clicking on the close icon (X) on the left of the Media Toolbox window.
# This will give you a requester advising that you need to reboot the machine for the changes to take effect. At this point you need to remove the USB memory stick for the machine. If you do not then the Machine will attempt boot from it before it is formatted and the required Kickstart and AmigaOS 4.1 files are copied to it.
# Select "Yes, reboot NOW!".
# Once you have rebooted connect your USB Memory Stick to a USB port.
# A disk icon "USB0:Uninitialized" (or whatever partition name you used) appears on Workbench.
# You now need to format the device.
# To format Select this Icon and go to the Workbench "Icons" menu .
# Select "Format Disk"
# You can give the USB Memory Stick a unique name and select whether you want a Trashcan or not.
# You can use either a full Format or a Quick Format. Full Format may take a few minutes.
# Once formatted the USB Memory Stick is ready for you to copy the required files from you hard drive or AmigaOS Install CD to it in order to boot AmigaOS 4.1 from it.

UserDoc:How AmigaOS Works

2015-05-29T06:24:36Z

Brian Deneen: /* Directories/Drawers */ Added basic explanation

As already mentioned, AmigaOS was a pioneer in the early days of personal computing in delivering sophistication that contemporary systems could only have dreamt of and pretended to offer. Today, AmigaOS continues to offer a straightforward elegance that seems to be overlooked in the development of other platforms. Thanks to the concepts behind AmigaOS, the system is easy to understand and to use by everyone.

In this page we will explore all these concepts of AmigaOS. Also you will learn here the naming of all parts of the system.

= Introduction =

AmigaOS is made of different components which are either mandatory (i.e., AmigaOS will not work without them) or components the user can choose to use or not. All these components can have one or mutiple interfaces a user or a developer can use to operate with the components and through them to control the operating system.

= The most important components =

== Exec, the AmigaOS kernel ==

Exec is the kernel of AmigaOS. It is the component that pilots all other components. It is responsible for running programs, dealing with computer memory and managing low-level resources that programs may need. In other words, it organises everything to make the operating system run.

It is made of different parts that cannot be moved outside the kernel: the scheduler, the memory pager and the 68k interpretive emulator.

== AmigaDOS: the underlying system ==

The word "DOS" was originally an acronym for "Disk Operating System". Some say it should be "Disk Based Operating System" as it does a lot more than operate a disk and that it was really an operating system based (stored) on disks. Some say it should be "Device Operating System".

The whole AmigaDOS system includes things such as:

* A set of commands that can be used in the Shell window and elsewhere.
* A system for saving data to disk and retrieving it from disk.
* A system for filing data on disks.
* An interface for peripherals such as keyboards, monitors, printers, etc.
* A method of running programs
* A multitasking system for running more than one program at a time.
* etc. etc. etc.

Read the [[AmigaDOS manual]] to understand and learn everything about AmigaDOS.

== The Graphics library ==

The Graphics library handles every low level graphic operation like designing pixels on the monitor, creating graphic elements (bobs, sprites) and also writing text output.

== Intuition ==

The Intuition library is responsible for every graphical object: windows, screens, gadgets, mouse pointers... It lies between any graphic program and the graphics library.

== The Workbench ==

The Workbench is the graphical place where you will manage your computer and all your files. The name was chosen because the user will use tools to create and work with the computer.

[[File:Wb.png|320px]]

== The Shell ==

While some people prefer to control the operating system using their mouse, others prefer using the keyboard. The shell is a text based window when you can type commands to execute actions in the operating system. In the shell the commands will display the results of their execution.

== ARexx - inter-program communication by scripting ==

The ARexx scripting language can be used to operate the Workbench and other Amiga applications from a script containing ARexx commands. This is extremely useful in performing repetitive tasks or doing what the controlled application was not even designed to do.
After a learning curve, everybody can use ARexx as it is built into the system. The scripts can be executed immediately like any other tool.

= How is my data stored? =
== Files ==
=== Executable files ===
Programs you can start are stored in executable files. They contain binary code directly understandable by the computer. They are files with an executable bit, a flag that shows AmigaOS that such file will do something when started.
An example is a music player. When you start this executable, the player opens and you can start playing music files.

AmigaOS can run two different kinds of executable files: the AmigaOS native programs made for the PowerPC processor and programs created for the Motorola 68k processors. The latter are executed inside an emulation that transcripts them into PowerPC code.

==== Scripts ====

Scripts are text files containing a list of commands. They are not strictly executables like ''binary code'' files but they can be executed by AmigaOS as if they were.
This is the case with AmigaDOS and ARexx scripts. These files need to have the executable bit, and the script bit.

=== Data files ===
Files that are not executable are data files. These contain data that will be manipulated by programs. Some examples are a music file, a video file or a text document.

== Directories/Drawers ==
In order to organise things, files are grouped together. We create "directories" which are like drawers of a cabinet to store different files of the same kind, for example.
Often the name ''directory'' is used when talking about a directory which is stored on a disk. The graphical interface of AmigaOS is called "Workbench," and directories are often called ''drawers''.

Note: directories are often called ''folders'' on other systems. The terms "directory," "drawer" and "folder" are synonymous.

== Disks, partitions and volumes ==
=== Disks ===
Disks are storage medium you can purchase on a computer store. We use them to store our files. They can be internal hard disks, external ones or a USB disk drive.

=== Partitions ===
A disk is often very big and many users prefer to make it more organised. This is done virtually splitting the disk into several smaller parts. This operation is known as creating partitions on a disk.

[[File:Partitions.png|Small part of Media Toolbox showing different partitions on the harddisk]]

On this screenshot you can see one harddisk with many partitions. Each color corresponds to a different filesystem which defines how data is stored. Also you can see a greyed area which is a blank area on the disk i.e. no partition is defined at this position.

=== Volumes ===
A partition is a physical area on a disk. To access it with AmigaOS we could read the physical data off the partition but it's not an easy way. To make it easier AmigaOS uses the concept of volumes. These are virtual representations of a partition. The volumes have a name so AmigaOS and therefore the user can access all files/directories stored on it in a very practical way: just by using its name.

= How to identify files/directories =

== On the Workbench ==

The Workbench being graphical, a lot of things are understandable just by looking at them. That's why icons are often enough to understand what kind of object it represents: a file, a directory, a disk...

In case you have a doubt, just look at the information on an icon. The Workbench will tell you the type of the object. It is displayed next to its name.

== In a shell ==

In a shell the '''list''' command can be used to see if an object is a file or a directory.

[[File:Files-dirs-in-shell.png|The '''list''' command shows a file of 925678 bytes and two directories]]

A file will be displayed with its size, whereas a directory will be displayed with the text '''Dir''' next to it.

Also, as you can see on the screenshot, the list command displays other characteristics on these 3 items: the protection bits and the date they were updated the last time. The command also sums up what it just listed.

= All AmigaOS components =

AmigaOS is made of components that are needed as soon as the system starts or later when the user or the system needs them.

== Kickstart modules ==

These components are the heart of AmigaOS. Their duties is to do graphics, to handle discs or to handle all reads/writes to files. Also one of them is the AmigaOS kernel which is a kind of director handling the work of all other components.
These Kickstart modules are loaded at the beginning of the operating system boot process (read [[UserDoc:How_AmigaOS_Works#AmigaOS_boot_procedure|here]]). You can find all them in the '''Kickstart''' directory in the system volume. Here is a list:

=== Mandatory modules ===

The following modules are required in any AmigaOS system. Without one of these, the system will not start.

* kernel - The kernel works like a conductor in an orchestra. Its job is to make everything works together. It creates processes, handle memory usage, defines the way other components will access peripherals...etc. Note that the AmigaOS kernel is not based on any other kernel. It is a self made kernel that works since 1983.
* loader - this component handles the loading of all other kickstart modules
* battclock.resource.kmod - this module handles reading/writing the battery backed up clock which is used on all computers to keep the date and time
* bootimage - this is the boot picture. It is displayed during the start sequence of AmigaOS
* bootmenu.kmod - this component handles the Early Startup Menu the use can use to define some settings before starting AmigaOS
* con-handler.kmod - it directs the read and write requests to the console window, to a serial AUX: device or any other supported interface
* console.device.kmod - it opens a window and reads/writes text to and from that window
* diskboot.kmod - handles the booting of AmigaOS from a supported disk
* diskboot.config - this is a text file experienced users can modify to change the boot behaviour of AmigaOS
* dos.library.kmod - this module is a collection of functions that any program can use to perform actions on disks, files and directories
* elf.library.kmod - handles the loading of executable programs
* env-handler.kmod - handles the read/writes of environment variables
* FileSystem.resource.kmod - handles the use of the different filesystems
* gadtools.library.kmod - collection of functions used to create all graphic objects like gadgets, sliders, menus...
* gameport.device.kmod - handles the read/writes of game pads and joysticks
* graphics.library.kmod - collection of functions used to draw graphic elements on the monitor
* hunk.library.kmod - set of functions to read a data stream into memory
* input.device.kmod - handles of input events like keyboard events or mouse clicks
* intuition.library.kmod - collection of functions to create and handle all graphic elements (screens, windows, the mouse pointer...)
* layers.library.kmod - set of functions to be used to handle different layers in graphic operations
* keyboard.device.kmod - driver for the keyboard
* keymap.library.kmod - functions to handle different keymaps
* newlib.library.kmod - collection of functions to perform memory operations (allocating memory, copying memory areas... )
* nonvolatile.library.kmod - provides a simple means for an application developer to manage nonvolatile storage
* nvram.resource.kmod - handles the read/writes to the EEPROM chip present on many AmigaOS computers
* PCIGraphics.card - driver that supports the use of different graphic cards
* ram-handler.kmod - functions that handles the '''Ram disk:''' special disk
* ramdrive.device.kmod - device that allows the usage of the ramdrive device '''RAD:''' disk
* ramlib.kmod - loads disk based libraries and devices for exec.library
* rtg.library - library of functions to perform lowlevel graphic operations on graphic cards
* shell.kmod - the AmigaOS command line interface
* strap.kmod - module that handles booting on different disk devices
* timer.device.kmod - driver to give access to timing functions

=== Filesystem support ===

These kickstart modules can be loaded or left aside. If you want to use a particular filesystem on your disk partitions, you need to load the corresponding filesystem module.

* CDFileSystem - handles the CD-ROM disks with data stored in different formats: ISO9660, HFS...
* SmartFilesystem - allows the usage of partitions in SFS0 and SFS2 layouts
* JXFileSystem - allows the usage of partitions in JXFS layout
* FastFileSystem - allows the usage of partitions in FFS and FFS2 layouts
* diskcache.library.kmod - component required by the SmartFileSystem and JXFileSystem modules

=== Hardware drivers ===

==== Graphic cards drivers ====

* 3dfxVoodoo.chip
* 3DLabsPermedia2.chip
* ATIRadeon.chip
* RadeonHD.chip
* siliconmotion502.chip

==== Disk drivers ====

Each of these drivers allow the use of disks connected to a disk controller. These files are named with the name of the controller they support. As an example, the '''sii3114ide.device.kmod''' allows to use disks connected on a '''Silicon Image SiI3114''' controller chip.

* it8212ide.device.kmod
* lsi53c8xx.device.kmod
* sam460sata.device.kmod
* sii3112ide.device.kmod
* sii3512ide.device.kmod
* sii3114ide.device.kmod
* sii0680ide.device.kmod
* sii3132ide.device.kmod

==== USB drivers ====

* hub.usbfd
* usbsys.device
* usbresource.library
* ehci.usbhcd
* ohci.usbhcd
* uhci.usbhcd
* massstorage.usbfd

==== Other drivers ====

* bootkeyboard.usbfd - allows a USB keyboard to be used even before the USB stack is loaded
* bootmouse.usbfd - allows a USB mouse to be used even before the USB stack is loaded
* fpga.resource.kmod - allows to use the FPGA components which are present on some Amiga computers
* i2c.resource.kmod - allows to use the i2c interface present on some Amiga computers
* xena.resource.kmod - provides access to the Xena chip on the AmigaOne X1000

=== Misc modules ===

* petunia.library.kmod - this module contains the Just-In-Time emulator that allows AmigaOS to run programs made for the Motorola 68k processor

== System components ==

[[File:Workbench_directory_listing.png|frame|right|List of directories and files present at the root of any AmigaOS system]]

Beside the kickstart modules, AmigaOS uses many different components that can be loaded only when used. These files are stored in different directories in the system volume.
Here is described a default AmigaOS installation.

* C
This directory contains AmigaDOS '''C'''ommands
* Classes
contains different object elements easy to be used in any program: gadgets, requesters, graphic table, windows...
* Devs
contains definition for '''Dev'''ices
* Emulation
contains files used for the 68k emulation (though E-UAE)
* Fonts
contains various systems fonts
* Internet
contains a dialer to connect to Internet
* Kickstart
contains the kickstart modules
* L
contains hand'''l'''ers and filesystems
* Libs
contains dynamic '''Libr'''airies of functions
* Locale
contains all files used to localise the system (catalogs, keymaps...)
* MUI
contains the needed files for programs that use the MUI third party graphic interface
* [[Prefs]]
contains the preference programs used to customise AmigaOS
* S
contains the '''S'''cripts
* SObjs
contains .so shared object library files
* Storage
contains other optional files
* System
contains some programs used by the system itself (i.e. you don't need to run them yourself) or low-level programs like disk tools
* [[Utilities]]
contains several programs you can use to achieve some tasks on AmigaOS

= Motorola 680x0 Emulators =

For a long time Amigas have had the famous Motorola 680x0 processors as the central unit for execution. Unfortunately the time of the 680x0 series is passing in favor of other architectures. The new era of processors reached the Amiga some time ago, when expansion boards became available for extending the Classic systems with the raw power of a PowerPC processor.

In the old operating system (AmigaOS 3.x) it was not possible to gain the full advantage of the new processors. The system itself and most of the applications required the original Motorola 680x0 processor. There was no 680x0 emulation available for the PowerPCs, so the 680x0 could not be "switched off".

Thus the new processors remained as a powerful, but mostly unused adjunct to the main 680x0 processor. "Native" PowerPC programs were rare, and every time a PowerPC program called the system, a so called "context switch" occurred between the 680x0 and PowerPC code, often causing a large performance penalty.

The new Amiga platform is based on the PowerPC processor family, therefore the new version of the AmigaOS has to smooth the transition from the 680x0 series, which is achieved by emulating the old processor architecture. The operating system itself is written almost 100 percent for the PowerPC processors, but the 680x0 legacy applications require an emulated 680x0 processor.

== Two 680x0 Emulators ==

In version 4.0 of AmigaOS, two different emulators were implemented; one is the successor of BlackBox emulation, it is an interpretive emulator, thus the emulation speed is mediocre. On the other hand it has a very low "reaction time", and is ideal for time critical parts, such as interrupts.

The other is Petunia, the "JIT emulator". A fast, but less compatible way of emulation of the legacy Motorola processors. It is intended mainly for emulating applications, and therefore, when execution of the application leaves the bounds of the application's code segment, emulation falls back to the interpretive method, where it does its job and returns to the JIT emulation again.

Dynamic recompilation (also called just-in-time compilation or simply JIT compilation) is a technique of translating foreign processor machine code to native machine code, "on the fly".

This technique is common nowadays, commonly applied in JAVA virtual machines, and it is also used with success in several emulators. In dynamic recompilation there is the possibility of runtime optimization of the emulated code by collecting statistics of the execution process. Therefore (theoretically) the final executed code can be even faster than the original code on its original processor.

== Features ==

Emulated opcodes:
* all user and supervisor level opcodes of the Motorola 68040
* all FPU opcodes of the Motorola 68881/68882

AmigaOS claims only 68020/68881 compatibility to applications because this is the safest compatibility level, but both emulators are compatible with the machine code up to the level of 68040/060 processors.

At compile time, a low level flag and branch control analysis allows on-the-fly optimizations of compiled code.

== Removing the JIT Emulator ==

Using the dynamic translation requires a lot more memory than the interpretive emulation. The translated code needs to be stored somewhere, not to mention the data collection tables.

If speed is not as important as the memory consumption of the system, then the JIT emulator can be removed, leaving the job to the interpretive emulator.

Thanks to the modular design of AmigaOS kickstart, all you need to do is edit the "Sys:Kickstart/Kicklayout" file, simply put a semicolon (;) at the beginning of the module line of Petunia.library.kmod. After rebooting the system from cold, the JIT emulator will not be reloaded. Make sure that you alter the appropriate configuration in the Kicklayout file, there may be several alternative configurations, with different names like "DefaultJIT", or "DefaultNoJIT".

== Configuring the Emulators ==

Petunia cooperates with a so called "black list". By default Petunia emulates every 680x0 program or library that is loaded by DOS.library/LoadSeg function, but if an executable or library shows incompatibilities with Petunia, then it can be explicitly inhibited from the dynamic recompilation by specifying it in a list file.

If an executable needs to be added to the list, then it can be done by extending the file "DEVS:applications.dos" with the '''Compatibility''' preferences program from the Prefs drawer of the system. Adding a program name to the list and checking it will prevent Petunia from emulating that program, and it will be interpreted instead by the built-in interpreter.

Removing a program from the list or unchecking (thus allowing Petunia to emulate it again) can be done with the same preferences program.

Please note: some programs consist of multiple executables (shared libraries, plugins). If you want to fully disable the translation of such programs, then every part must be added to the list.

For example to disable UnArc fully, you would have to add all files from libs:xad and also xadmaster.library to the list.

= AmigaOS boot procedure =

Basically a computer with AmigaOS does the following when the power button is pushed:

* [[File:Uboot.jpg|200px]]
the BIOS ([[UserDoc:BIOS|Uboot]] or [[UserDoc:BIOS|CFE]]) of the computer initialises the hardware: graphic card, USB ports... At this point, the monitor wakes up and the first information are displayed. This allows to see if hardware is correctly recognised. As an example you can see if a hard drive is correctly connected into the machine and your BIOS is correctly setup to make this drive useable.
* depending on how you setup the BIOS it will look on the harddisk to find the Second Level Booter (SLB). This program is stored on the first sectors of the disk. Whereas the BIOS does not know about AmigaOS disk structure, the SLB will be able to ''understand'' the AmigaOS partitions and files. In other words, it is the link between the BIOS and the rest of the boot procedure. Its goal is also to give you the ability to start several configurations present on the same drive.
* [[File:SLB.png|200px]]
the SLB will analyses all Amiga partitions on the disk it is installed on. It will read each [[UserDoc:kickstart_configuration|system configuration]] it finds on the partitions. It will show all available configurations for the user to select one to load.
The user can define many different kickstart configurations to choose from. Also both AmigaOS and Linux can be selected for boot.
* [[File:Kmods loading.png|200px]]
the SLB loads the kickstart files of the selected configuration and executes the '''Loader''' module
* '''Loader''' executes the kickstart modules (Exec, devices, libraries...)
* AmigaOS becomes alive displaying the AmigaOS boot picture on the monitor
* the AmigaDOS library executes the [[UserDoc:System_Scripts#startup-sequence|startup-sequence]] script found on the system volume
* the Startup-sequence will be executed and all commands it contains are executed. It means that starting from here the boot procedure is easy to follow and understand.
* the Workbench is started

At this point the user can use his/her computer.

= How to make a Bootable USB Memory Stick for AmigaOS 4.1 =

By Julian Margetson ("Spectre660")

Prerequisites:
* USB memory stick of 2 GB or less in size.
* It is best to only have one USB mass storage device connected while you are creating your bootable USB memory stick.
* Plug the USB memory stick into a USB port on your machine.
* Note that the device will be formatted so make sure that you use an empty memory stick or one that does not contain any data that you need or backup the contents before you begin.

Procedure:
# You use Media Toolbox in the System: drawer to prepare the USB stick. On starting Media Toolbox select ''usbdisk.device'' as the device to use.
# Make certain that you have selected usbdisk.device and not any other device.
# Click on "Start"
# You will see the usb mass storage unit connected in a list.
# Make sure that the Unit type displayed for the USB memory stick is "Removable hard disk"
# Select that Unit by clicking on it.
# The first thing that you need to do is to install the RDB onto the USB Memory Stick.
# Click on the "Install" button.
# A window Labeled "RDB/disk geometry editing" comes up.
## Towards the bottom of the window is the "AmigaOne boot code (SLB)" section.
## Select the "Install" button .
## A file requester "Select AmigaOne Boot Code" now comes up with the Drawer choice defaulting to "l:"
## Select file "slb_v2".
## Select Ok.
## You are now returned to the "RDB/disk geometry editing window".
## Select "Ok-accept changes".
# You are now returned to the display showing the attached USB unit.
# Select "Edit partitions and Filesystems". You will now see the Window 'Editing partitions for disk"
# Select "Add partition"
# This defaults to using the whole device as a single partition.
# It is possible to use create more partitions but for this tutorial we will only use one.
# You now need to give the partition a unique name (e.g. USB0 or something that is different from any of the existing partitions on your hard drive). This is done by changing the default DH0 in the "Name" box.
# Now make sure that the Boxes "Automount" and "Bootable" are selected and show the "Tick mark".
# You need to set "Boot priority" to higher than the boot priority of your hard drive boot partition(s). This is done by increasing Boot priority by clicking on the "+" to the right of the "boot priority" box. Normally you can set the boot priority to 2 .
# Next it is time to select the file system to use.
# Select "Select filesystem/edit details".
# The Window "Editing details for partition 'USB0'" ,or whatever partition name you used, comes up.
## Select the file system that you are going to use by selecting the pull down menu under "Filesystem chooser".
## Only filesystems SFS/00 or SFS/02 will work for a bootable device.
## The option that gives the most flexibility at the moment is SFS/00 as a USB stick in this format can be read and written to using another compatible system in the event that you need to make modifications after it is created without a booting AmigaOS 4.1 machine.
## Next select Blocksize from the "Blocksize" pull down menu. 512 is the correct size to use.
## Now Select "Ok-accept changes".
## Your are now returned to the "Edit partitions for disk" window.
## Again select "Ok-accept changes"
# You are now returned to the window showing the USB mass storage unit list.
# Select "Save to disk"
# A requester pops up with the options "Yes, Save." or "No!"
# Select the "Yes, save." option.
# You now close Media Toolbox by clicking on the close icon (X) on the left of the Media Toolbox window.
# This will give you a requester advising that you need to reboot the machine for the changes to take effect. At this point you need to remove the USB memory stick for the machine. If you do not then the Machine will attempt boot from it before it is formatted and the required Kickstart and AmigaOS 4.1 files are copied to it.
# Select "Yes, reboot NOW!".
# Once you have rebooted connect your USB Memory Stick to a USB port.
# A disk icon "USB0:Uninitialized" (or whatever partition name you used) appears on Workbench.
# You now need to format the device.
# To format Select this Icon and go to the Workbench "Icons" menu .
# Select "Format Disk"
# You can give the USB Memory Stick a unique name and select whether you want a Trashcan or not.
# You can use either a full Format or a Quick Format. Full Format may take a few minutes.
# Once formatted the USB Memory Stick is ready for you to copy the required files from you hard drive or AmigaOS Install CD to it in order to boot AmigaOS 4.1 from it.

UserDoc:How AmigaOS Works

2015-05-29T06:22:39Z

Brian Deneen: /* Directories/Drawers */ usage

As already mentioned, AmigaOS was a pioneer in the early days of personal computing in delivering sophistication that contemporary systems could only have dreamt of and pretended to offer. Today, AmigaOS continues to offer a straightforward elegance that seems to be overlooked in the development of other platforms. Thanks to the concepts behind AmigaOS, the system is easy to understand and to use by everyone.

In this page we will explore all these concepts of AmigaOS. Also you will learn here the naming of all parts of the system.

= Introduction =

AmigaOS is made of different components which are either mandatory (i.e., AmigaOS will not work without them) or components the user can choose to use or not. All these components can have one or mutiple interfaces a user or a developer can use to operate with the components and through them to control the operating system.

= The most important components =

== Exec, the AmigaOS kernel ==

Exec is the kernel of AmigaOS. It is the component that pilots all other components. It is responsible for running programs, dealing with computer memory and managing low-level resources that programs may need. In other words, it organises everything to make the operating system run.

It is made of different parts that cannot be moved outside the kernel: the scheduler, the memory pager and the 68k interpretive emulator.

== AmigaDOS: the underlying system ==

The word "DOS" was originally an acronym for "Disk Operating System". Some say it should be "Disk Based Operating System" as it does a lot more than operate a disk and that it was really an operating system based (stored) on disks. Some say it should be "Device Operating System".

The whole AmigaDOS system includes things such as:

* A set of commands that can be used in the Shell window and elsewhere.
* A system for saving data to disk and retrieving it from disk.
* A system for filing data on disks.
* An interface for peripherals such as keyboards, monitors, printers, etc.
* A method of running programs
* A multitasking system for running more than one program at a time.
* etc. etc. etc.

Read the [[AmigaDOS manual]] to understand and learn everything about AmigaDOS.

== The Graphics library ==

The Graphics library handles every low level graphic operation like designing pixels on the monitor, creating graphic elements (bobs, sprites) and also writing text output.

== Intuition ==

The Intuition library is responsible for every graphical object: windows, screens, gadgets, mouse pointers... It lies between any graphic program and the graphics library.

== The Workbench ==

The Workbench is the graphical place where you will manage your computer and all your files. The name was chosen because the user will use tools to create and work with the computer.

[[File:Wb.png|320px]]

== The Shell ==

While some people prefer to control the operating system using their mouse, others prefer using the keyboard. The shell is a text based window when you can type commands to execute actions in the operating system. In the shell the commands will display the results of their execution.

== ARexx - inter-program communication by scripting ==

The ARexx scripting language can be used to operate the Workbench and other Amiga applications from a script containing ARexx commands. This is extremely useful in performing repetitive tasks or doing what the controlled application was not even designed to do.
After a learning curve, everybody can use ARexx as it is built into the system. The scripts can be executed immediately like any other tool.

= How is my data stored? =
== Files ==
=== Executable files ===
Programs you can start are stored in executable files. They contain binary code directly understandable by the computer. They are files with an executable bit, a flag that shows AmigaOS that such file will do something when started.
An example is a music player. When you start this executable, the player opens and you can start playing music files.

AmigaOS can run two different kinds of executable files: the AmigaOS native programs made for the PowerPC processor and programs created for the Motorola 68k processors. The latter are executed inside an emulation that transcripts them into PowerPC code.

==== Scripts ====

Scripts are text files containing a list of commands. They are not strictly executables like ''binary code'' files but they can be executed by AmigaOS as if they were.
This is the case with AmigaDOS and ARexx scripts. These files need to have the executable bit, and the script bit.

=== Data files ===
Files that are not executable are data files. These contain data that will be manipulated by programs. Some examples are a music file, a video file or a text document.

== Directories/Drawers ==
In order to organise things, files are grouped together. We create "directories" which are like drawers of a cabinet to store different files of the same kind, for example.
Often the name ''directory'' is used when talking about a directory which is stored on a disk. The graphical interface of AmigaOS is called "Workbench," and directories are often called ''drawers''.

Note: directories are often called ''folders'' on other systems.

== Disks, partitions and volumes ==
=== Disks ===
Disks are storage medium you can purchase on a computer store. We use them to store our files. They can be internal hard disks, external ones or a USB disk drive.

=== Partitions ===
A disk is often very big and many users prefer to make it more organised. This is done virtually splitting the disk into several smaller parts. This operation is known as creating partitions on a disk.

[[File:Partitions.png|Small part of Media Toolbox showing different partitions on the harddisk]]

On this screenshot you can see one harddisk with many partitions. Each color corresponds to a different filesystem which defines how data is stored. Also you can see a greyed area which is a blank area on the disk i.e. no partition is defined at this position.

=== Volumes ===
A partition is a physical area on a disk. To access it with AmigaOS we could read the physical data off the partition but it's not an easy way. To make it easier AmigaOS uses the concept of volumes. These are virtual representations of a partition. The volumes have a name so AmigaOS and therefore the user can access all files/directories stored on it in a very practical way: just by using its name.

= How to identify files/directories =

== On the Workbench ==

The Workbench being graphical, a lot of things are understandable just by looking at them. That's why icons are often enough to understand what kind of object it represents: a file, a directory, a disk...

In case you have a doubt, just look at the information on an icon. The Workbench will tell you the type of the object. It is displayed next to its name.

== In a shell ==

In a shell the '''list''' command can be used to see if an object is a file or a directory.

[[File:Files-dirs-in-shell.png|The '''list''' command shows a file of 925678 bytes and two directories]]

A file will be displayed with its size, whereas a directory will be displayed with the text '''Dir''' next to it.

Also, as you can see on the screenshot, the list command displays other characteristics on these 3 items: the protection bits and the date they were updated the last time. The command also sums up what it just listed.

= All AmigaOS components =

AmigaOS is made of components that are needed as soon as the system starts or later when the user or the system needs them.

== Kickstart modules ==

These components are the heart of AmigaOS. Their duties is to do graphics, to handle discs or to handle all reads/writes to files. Also one of them is the AmigaOS kernel which is a kind of director handling the work of all other components.
These Kickstart modules are loaded at the beginning of the operating system boot process (read [[UserDoc:How_AmigaOS_Works#AmigaOS_boot_procedure|here]]). You can find all them in the '''Kickstart''' directory in the system volume. Here is a list:

=== Mandatory modules ===

The following modules are required in any AmigaOS system. Without one of these, the system will not start.

* kernel - The kernel works like a conductor in an orchestra. Its job is to make everything works together. It creates processes, handle memory usage, defines the way other components will access peripherals...etc. Note that the AmigaOS kernel is not based on any other kernel. It is a self made kernel that works since 1983.
* loader - this component handles the loading of all other kickstart modules
* battclock.resource.kmod - this module handles reading/writing the battery backed up clock which is used on all computers to keep the date and time
* bootimage - this is the boot picture. It is displayed during the start sequence of AmigaOS
* bootmenu.kmod - this component handles the Early Startup Menu the use can use to define some settings before starting AmigaOS
* con-handler.kmod - it directs the read and write requests to the console window, to a serial AUX: device or any other supported interface
* console.device.kmod - it opens a window and reads/writes text to and from that window
* diskboot.kmod - handles the booting of AmigaOS from a supported disk
* diskboot.config - this is a text file experienced users can modify to change the boot behaviour of AmigaOS
* dos.library.kmod - this module is a collection of functions that any program can use to perform actions on disks, files and directories
* elf.library.kmod - handles the loading of executable programs
* env-handler.kmod - handles the read/writes of environment variables
* FileSystem.resource.kmod - handles the use of the different filesystems
* gadtools.library.kmod - collection of functions used to create all graphic objects like gadgets, sliders, menus...
* gameport.device.kmod - handles the read/writes of game pads and joysticks
* graphics.library.kmod - collection of functions used to draw graphic elements on the monitor
* hunk.library.kmod - set of functions to read a data stream into memory
* input.device.kmod - handles of input events like keyboard events or mouse clicks
* intuition.library.kmod - collection of functions to create and handle all graphic elements (screens, windows, the mouse pointer...)
* layers.library.kmod - set of functions to be used to handle different layers in graphic operations
* keyboard.device.kmod - driver for the keyboard
* keymap.library.kmod - functions to handle different keymaps
* newlib.library.kmod - collection of functions to perform memory operations (allocating memory, copying memory areas... )
* nonvolatile.library.kmod - provides a simple means for an application developer to manage nonvolatile storage
* nvram.resource.kmod - handles the read/writes to the EEPROM chip present on many AmigaOS computers
* PCIGraphics.card - driver that supports the use of different graphic cards
* ram-handler.kmod - functions that handles the '''Ram disk:''' special disk
* ramdrive.device.kmod - device that allows the usage of the ramdrive device '''RAD:''' disk
* ramlib.kmod - loads disk based libraries and devices for exec.library
* rtg.library - library of functions to perform lowlevel graphic operations on graphic cards
* shell.kmod - the AmigaOS command line interface
* strap.kmod - module that handles booting on different disk devices
* timer.device.kmod - driver to give access to timing functions

=== Filesystem support ===

These kickstart modules can be loaded or left aside. If you want to use a particular filesystem on your disk partitions, you need to load the corresponding filesystem module.

* CDFileSystem - handles the CD-ROM disks with data stored in different formats: ISO9660, HFS...
* SmartFilesystem - allows the usage of partitions in SFS0 and SFS2 layouts
* JXFileSystem - allows the usage of partitions in JXFS layout
* FastFileSystem - allows the usage of partitions in FFS and FFS2 layouts
* diskcache.library.kmod - component required by the SmartFileSystem and JXFileSystem modules

=== Hardware drivers ===

==== Graphic cards drivers ====

* 3dfxVoodoo.chip
* 3DLabsPermedia2.chip
* ATIRadeon.chip
* RadeonHD.chip
* siliconmotion502.chip

==== Disk drivers ====

Each of these drivers allow the use of disks connected to a disk controller. These files are named with the name of the controller they support. As an example, the '''sii3114ide.device.kmod''' allows to use disks connected on a '''Silicon Image SiI3114''' controller chip.

* it8212ide.device.kmod
* lsi53c8xx.device.kmod
* sam460sata.device.kmod
* sii3112ide.device.kmod
* sii3512ide.device.kmod
* sii3114ide.device.kmod
* sii0680ide.device.kmod
* sii3132ide.device.kmod

==== USB drivers ====

* hub.usbfd
* usbsys.device
* usbresource.library
* ehci.usbhcd
* ohci.usbhcd
* uhci.usbhcd
* massstorage.usbfd

==== Other drivers ====

* bootkeyboard.usbfd - allows a USB keyboard to be used even before the USB stack is loaded
* bootmouse.usbfd - allows a USB mouse to be used even before the USB stack is loaded
* fpga.resource.kmod - allows to use the FPGA components which are present on some Amiga computers
* i2c.resource.kmod - allows to use the i2c interface present on some Amiga computers
* xena.resource.kmod - provides access to the Xena chip on the AmigaOne X1000

=== Misc modules ===

* petunia.library.kmod - this module contains the Just-In-Time emulator that allows AmigaOS to run programs made for the Motorola 68k processor

== System components ==

[[File:Workbench_directory_listing.png|frame|right|List of directories and files present at the root of any AmigaOS system]]

Beside the kickstart modules, AmigaOS uses many different components that can be loaded only when used. These files are stored in different directories in the system volume.
Here is described a default AmigaOS installation.

* C
This directory contains AmigaDOS '''C'''ommands
* Classes
contains different object elements easy to be used in any program: gadgets, requesters, graphic table, windows...
* Devs
contains definition for '''Dev'''ices
* Emulation
contains files used for the 68k emulation (though E-UAE)
* Fonts
contains various systems fonts
* Internet
contains a dialer to connect to Internet
* Kickstart
contains the kickstart modules
* L
contains hand'''l'''ers and filesystems
* Libs
contains dynamic '''Libr'''airies of functions
* Locale
contains all files used to localise the system (catalogs, keymaps...)
* MUI
contains the needed files for programs that use the MUI third party graphic interface
* [[Prefs]]
contains the preference programs used to customise AmigaOS
* S
contains the '''S'''cripts
* SObjs
contains .so shared object library files
* Storage
contains other optional files
* System
contains some programs used by the system itself (i.e. you don't need to run them yourself) or low-level programs like disk tools
* [[Utilities]]
contains several programs you can use to achieve some tasks on AmigaOS

= Motorola 680x0 Emulators =

For a long time Amigas have had the famous Motorola 680x0 processors as the central unit for execution. Unfortunately the time of the 680x0 series is passing in favor of other architectures. The new era of processors reached the Amiga some time ago, when expansion boards became available for extending the Classic systems with the raw power of a PowerPC processor.

In the old operating system (AmigaOS 3.x) it was not possible to gain the full advantage of the new processors. The system itself and most of the applications required the original Motorola 680x0 processor. There was no 680x0 emulation available for the PowerPCs, so the 680x0 could not be "switched off".

Thus the new processors remained as a powerful, but mostly unused adjunct to the main 680x0 processor. "Native" PowerPC programs were rare, and every time a PowerPC program called the system, a so called "context switch" occurred between the 680x0 and PowerPC code, often causing a large performance penalty.

The new Amiga platform is based on the PowerPC processor family, therefore the new version of the AmigaOS has to smooth the transition from the 680x0 series, which is achieved by emulating the old processor architecture. The operating system itself is written almost 100 percent for the PowerPC processors, but the 680x0 legacy applications require an emulated 680x0 processor.

== Two 680x0 Emulators ==

In version 4.0 of AmigaOS, two different emulators were implemented; one is the successor of BlackBox emulation, it is an interpretive emulator, thus the emulation speed is mediocre. On the other hand it has a very low "reaction time", and is ideal for time critical parts, such as interrupts.

The other is Petunia, the "JIT emulator". A fast, but less compatible way of emulation of the legacy Motorola processors. It is intended mainly for emulating applications, and therefore, when execution of the application leaves the bounds of the application's code segment, emulation falls back to the interpretive method, where it does its job and returns to the JIT emulation again.

Dynamic recompilation (also called just-in-time compilation or simply JIT compilation) is a technique of translating foreign processor machine code to native machine code, "on the fly".

This technique is common nowadays, commonly applied in JAVA virtual machines, and it is also used with success in several emulators. In dynamic recompilation there is the possibility of runtime optimization of the emulated code by collecting statistics of the execution process. Therefore (theoretically) the final executed code can be even faster than the original code on its original processor.

== Features ==

Emulated opcodes:
* all user and supervisor level opcodes of the Motorola 68040
* all FPU opcodes of the Motorola 68881/68882

AmigaOS claims only 68020/68881 compatibility to applications because this is the safest compatibility level, but both emulators are compatible with the machine code up to the level of 68040/060 processors.

At compile time, a low level flag and branch control analysis allows on-the-fly optimizations of compiled code.

== Removing the JIT Emulator ==

Using the dynamic translation requires a lot more memory than the interpretive emulation. The translated code needs to be stored somewhere, not to mention the data collection tables.

If speed is not as important as the memory consumption of the system, then the JIT emulator can be removed, leaving the job to the interpretive emulator.

Thanks to the modular design of AmigaOS kickstart, all you need to do is edit the "Sys:Kickstart/Kicklayout" file, simply put a semicolon (;) at the beginning of the module line of Petunia.library.kmod. After rebooting the system from cold, the JIT emulator will not be reloaded. Make sure that you alter the appropriate configuration in the Kicklayout file, there may be several alternative configurations, with different names like "DefaultJIT", or "DefaultNoJIT".

== Configuring the Emulators ==

Petunia cooperates with a so called "black list". By default Petunia emulates every 680x0 program or library that is loaded by DOS.library/LoadSeg function, but if an executable or library shows incompatibilities with Petunia, then it can be explicitly inhibited from the dynamic recompilation by specifying it in a list file.

If an executable needs to be added to the list, then it can be done by extending the file "DEVS:applications.dos" with the '''Compatibility''' preferences program from the Prefs drawer of the system. Adding a program name to the list and checking it will prevent Petunia from emulating that program, and it will be interpreted instead by the built-in interpreter.

Removing a program from the list or unchecking (thus allowing Petunia to emulate it again) can be done with the same preferences program.

Please note: some programs consist of multiple executables (shared libraries, plugins). If you want to fully disable the translation of such programs, then every part must be added to the list.

For example to disable UnArc fully, you would have to add all files from libs:xad and also xadmaster.library to the list.

= AmigaOS boot procedure =

Basically a computer with AmigaOS does the following when the power button is pushed:

* [[File:Uboot.jpg|200px]]
the BIOS ([[UserDoc:BIOS|Uboot]] or [[UserDoc:BIOS|CFE]]) of the computer initialises the hardware: graphic card, USB ports... At this point, the monitor wakes up and the first information are displayed. This allows to see if hardware is correctly recognised. As an example you can see if a hard drive is correctly connected into the machine and your BIOS is correctly setup to make this drive useable.
* depending on how you setup the BIOS it will look on the harddisk to find the Second Level Booter (SLB). This program is stored on the first sectors of the disk. Whereas the BIOS does not know about AmigaOS disk structure, the SLB will be able to ''understand'' the AmigaOS partitions and files. In other words, it is the link between the BIOS and the rest of the boot procedure. Its goal is also to give you the ability to start several configurations present on the same drive.
* [[File:SLB.png|200px]]
the SLB will analyses all Amiga partitions on the disk it is installed on. It will read each [[UserDoc:kickstart_configuration|system configuration]] it finds on the partitions. It will show all available configurations for the user to select one to load.
The user can define many different kickstart configurations to choose from. Also both AmigaOS and Linux can be selected for boot.
* [[File:Kmods loading.png|200px]]
the SLB loads the kickstart files of the selected configuration and executes the '''Loader''' module
* '''Loader''' executes the kickstart modules (Exec, devices, libraries...)
* AmigaOS becomes alive displaying the AmigaOS boot picture on the monitor
* the AmigaDOS library executes the [[UserDoc:System_Scripts#startup-sequence|startup-sequence]] script found on the system volume
* the Startup-sequence will be executed and all commands it contains are executed. It means that starting from here the boot procedure is easy to follow and understand.
* the Workbench is started

At this point the user can use his/her computer.

= How to make a Bootable USB Memory Stick for AmigaOS 4.1 =

By Julian Margetson ("Spectre660")

Prerequisites:
* USB memory stick of 2 GB or less in size.
* It is best to only have one USB mass storage device connected while you are creating your bootable USB memory stick.
* Plug the USB memory stick into a USB port on your machine.
* Note that the device will be formatted so make sure that you use an empty memory stick or one that does not contain any data that you need or backup the contents before you begin.

Procedure:
# You use Media Toolbox in the System: drawer to prepare the USB stick. On starting Media Toolbox select ''usbdisk.device'' as the device to use.
# Make certain that you have selected usbdisk.device and not any other device.
# Click on "Start"
# You will see the usb mass storage unit connected in a list.
# Make sure that the Unit type displayed for the USB memory stick is "Removable hard disk"
# Select that Unit by clicking on it.
# The first thing that you need to do is to install the RDB onto the USB Memory Stick.
# Click on the "Install" button.
# A window Labeled "RDB/disk geometry editing" comes up.
## Towards the bottom of the window is the "AmigaOne boot code (SLB)" section.
## Select the "Install" button .
## A file requester "Select AmigaOne Boot Code" now comes up with the Drawer choice defaulting to "l:"
## Select file "slb_v2".
## Select Ok.
## You are now returned to the "RDB/disk geometry editing window".
## Select "Ok-accept changes".
# You are now returned to the display showing the attached USB unit.
# Select "Edit partitions and Filesystems". You will now see the Window 'Editing partitions for disk"
# Select "Add partition"
# This defaults to using the whole device as a single partition.
# It is possible to use create more partitions but for this tutorial we will only use one.
# You now need to give the partition a unique name (e.g. USB0 or something that is different from any of the existing partitions on your hard drive). This is done by changing the default DH0 in the "Name" box.
# Now make sure that the Boxes "Automount" and "Bootable" are selected and show the "Tick mark".
# You need to set "Boot priority" to higher than the boot priority of your hard drive boot partition(s). This is done by increasing Boot priority by clicking on the "+" to the right of the "boot priority" box. Normally you can set the boot priority to 2 .
# Next it is time to select the file system to use.
# Select "Select filesystem/edit details".
# The Window "Editing details for partition 'USB0'" ,or whatever partition name you used, comes up.
## Select the file system that you are going to use by selecting the pull down menu under "Filesystem chooser".
## Only filesystems SFS/00 or SFS/02 will work for a bootable device.
## The option that gives the most flexibility at the moment is SFS/00 as a USB stick in this format can be read and written to using another compatible system in the event that you need to make modifications after it is created without a booting AmigaOS 4.1 machine.
## Next select Blocksize from the "Blocksize" pull down menu. 512 is the correct size to use.
## Now Select "Ok-accept changes".
## Your are now returned to the "Edit partitions for disk" window.
## Again select "Ok-accept changes"
# You are now returned to the window showing the USB mass storage unit list.
# Select "Save to disk"
# A requester pops up with the options "Yes, Save." or "No!"
# Select the "Yes, save." option.
# You now close Media Toolbox by clicking on the close icon (X) on the left of the Media Toolbox window.
# This will give you a requester advising that you need to reboot the machine for the changes to take effect. At this point you need to remove the USB memory stick for the machine. If you do not then the Machine will attempt boot from it before it is formatted and the required Kickstart and AmigaOS 4.1 files are copied to it.
# Select "Yes, reboot NOW!".
# Once you have rebooted connect your USB Memory Stick to a USB port.
# A disk icon "USB0:Uninitialized" (or whatever partition name you used) appears on Workbench.
# You now need to format the device.
# To format Select this Icon and go to the Workbench "Icons" menu .
# Select "Format Disk"
# You can give the USB Memory Stick a unique name and select whether you want a Trashcan or not.
# You can use either a full Format or a Quick Format. Full Format may take a few minutes.
# Once formatted the USB Memory Stick is ready for you to copy the required files from you hard drive or AmigaOS Install CD to it in order to boot AmigaOS 4.1 from it.

UserDoc:How AmigaOS Works

2015-05-29T06:17:57Z

Brian Deneen: /* Data files */ usage

As already mentioned, AmigaOS was a pioneer in the early days of personal computing in delivering sophistication that contemporary systems could only have dreamt of and pretended to offer. Today, AmigaOS continues to offer a straightforward elegance that seems to be overlooked in the development of other platforms. Thanks to the concepts behind AmigaOS, the system is easy to understand and to use by everyone.

In this page we will explore all these concepts of AmigaOS. Also you will learn here the naming of all parts of the system.

= Introduction =

AmigaOS is made of different components which are either mandatory (i.e., AmigaOS will not work without them) or components the user can choose to use or not. All these components can have one or mutiple interfaces a user or a developer can use to operate with the components and through them to control the operating system.

= The most important components =

== Exec, the AmigaOS kernel ==

Exec is the kernel of AmigaOS. It is the component that pilots all other components. It is responsible for running programs, dealing with computer memory and managing low-level resources that programs may need. In other words, it organises everything to make the operating system run.

It is made of different parts that cannot be moved outside the kernel: the scheduler, the memory pager and the 68k interpretive emulator.

== AmigaDOS: the underlying system ==

The word "DOS" was originally an acronym for "Disk Operating System". Some say it should be "Disk Based Operating System" as it does a lot more than operate a disk and that it was really an operating system based (stored) on disks. Some say it should be "Device Operating System".

The whole AmigaDOS system includes things such as:

* A set of commands that can be used in the Shell window and elsewhere.
* A system for saving data to disk and retrieving it from disk.
* A system for filing data on disks.
* An interface for peripherals such as keyboards, monitors, printers, etc.
* A method of running programs
* A multitasking system for running more than one program at a time.
* etc. etc. etc.

Read the [[AmigaDOS manual]] to understand and learn everything about AmigaDOS.

== The Graphics library ==

The Graphics library handles every low level graphic operation like designing pixels on the monitor, creating graphic elements (bobs, sprites) and also writing text output.

== Intuition ==

The Intuition library is responsible for every graphical object: windows, screens, gadgets, mouse pointers... It lies between any graphic program and the graphics library.

== The Workbench ==

The Workbench is the graphical place where you will manage your computer and all your files. The name was chosen because the user will use tools to create and work with the computer.

[[File:Wb.png|320px]]

== The Shell ==

While some people prefer to control the operating system using their mouse, others prefer using the keyboard. The shell is a text based window when you can type commands to execute actions in the operating system. In the shell the commands will display the results of their execution.

== ARexx - inter-program communication by scripting ==

The ARexx scripting language can be used to operate the Workbench and other Amiga applications from a script containing ARexx commands. This is extremely useful in performing repetitive tasks or doing what the controlled application was not even designed to do.
After a learning curve, everybody can use ARexx as it is built into the system. The scripts can be executed immediately like any other tool.

= How is my data stored? =
== Files ==
=== Executable files ===
Programs you can start are stored in executable files. They contain binary code directly understandable by the computer. They are files with an executable bit, a flag that shows AmigaOS that such file will do something when started.
An example is a music player. When you start this executable, the player opens and you can start playing music files.

AmigaOS can run two different kinds of executable files: the AmigaOS native programs made for the PowerPC processor and programs created for the Motorola 68k processors. The latter are executed inside an emulation that transcripts them into PowerPC code.

==== Scripts ====

Scripts are text files containing a list of commands. They are not strictly executables like ''binary code'' files but they can be executed by AmigaOS as if they were.
This is the case with AmigaDOS and ARexx scripts. These files need to have the executable bit, and the script bit.

=== Data files ===
Files that are not executable are data files. These contain data that will be manipulated by programs. Some examples are a music file, a video file or a text document.

== Directories/Drawers ==
In order to organise things a bit, files are not all of them in the same place. We create directories which like drawers of a cabinet will store different files of the same kind.
Often the name ''directory'' is used when talking about the directory which is stored on a disk. The graphical interface of AmigaOS being called the Workbench, directories are often called ''drawers''.

Note: directories are often called ''folders'' on other systems.

== Disks, partitions and volumes ==
=== Disks ===
Disks are storage medium you can purchase on a computer store. We use them to store our files. They can be internal hard disks, external ones or a USB disk drive.

=== Partitions ===
A disk is often very big and many users prefer to make it more organised. This is done virtually splitting the disk into several smaller parts. This operation is known as creating partitions on a disk.

[[File:Partitions.png|Small part of Media Toolbox showing different partitions on the harddisk]]

On this screenshot you can see one harddisk with many partitions. Each color corresponds to a different filesystem which defines how data is stored. Also you can see a greyed area which is a blank area on the disk i.e. no partition is defined at this position.

=== Volumes ===
A partition is a physical area on a disk. To access it with AmigaOS we could read the physical data off the partition but it's not an easy way. To make it easier AmigaOS uses the concept of volumes. These are virtual representations of a partition. The volumes have a name so AmigaOS and therefore the user can access all files/directories stored on it in a very practical way: just by using its name.

= How to identify files/directories =

== On the Workbench ==

The Workbench being graphical, a lot of things are understandable just by looking at them. That's why icons are often enough to understand what kind of object it represents: a file, a directory, a disk...

In case you have a doubt, just look at the information on an icon. The Workbench will tell you the type of the object. It is displayed next to its name.

== In a shell ==

In a shell the '''list''' command can be used to see if an object is a file or a directory.

[[File:Files-dirs-in-shell.png|The '''list''' command shows a file of 925678 bytes and two directories]]

A file will be displayed with its size, whereas a directory will be displayed with the text '''Dir''' next to it.

Also, as you can see on the screenshot, the list command displays other characteristics on these 3 items: the protection bits and the date they were updated the last time. The command also sums up what it just listed.

= All AmigaOS components =

AmigaOS is made of components that are needed as soon as the system starts or later when the user or the system needs them.

== Kickstart modules ==

These components are the heart of AmigaOS. Their duties is to do graphics, to handle discs or to handle all reads/writes to files. Also one of them is the AmigaOS kernel which is a kind of director handling the work of all other components.
These Kickstart modules are loaded at the beginning of the operating system boot process (read [[UserDoc:How_AmigaOS_Works#AmigaOS_boot_procedure|here]]). You can find all them in the '''Kickstart''' directory in the system volume. Here is a list:

=== Mandatory modules ===

The following modules are required in any AmigaOS system. Without one of these, the system will not start.

* kernel - The kernel works like a conductor in an orchestra. Its job is to make everything works together. It creates processes, handle memory usage, defines the way other components will access peripherals...etc. Note that the AmigaOS kernel is not based on any other kernel. It is a self made kernel that works since 1983.
* loader - this component handles the loading of all other kickstart modules
* battclock.resource.kmod - this module handles reading/writing the battery backed up clock which is used on all computers to keep the date and time
* bootimage - this is the boot picture. It is displayed during the start sequence of AmigaOS
* bootmenu.kmod - this component handles the Early Startup Menu the use can use to define some settings before starting AmigaOS
* con-handler.kmod - it directs the read and write requests to the console window, to a serial AUX: device or any other supported interface
* console.device.kmod - it opens a window and reads/writes text to and from that window
* diskboot.kmod - handles the booting of AmigaOS from a supported disk
* diskboot.config - this is a text file experienced users can modify to change the boot behaviour of AmigaOS
* dos.library.kmod - this module is a collection of functions that any program can use to perform actions on disks, files and directories
* elf.library.kmod - handles the loading of executable programs
* env-handler.kmod - handles the read/writes of environment variables
* FileSystem.resource.kmod - handles the use of the different filesystems
* gadtools.library.kmod - collection of functions used to create all graphic objects like gadgets, sliders, menus...
* gameport.device.kmod - handles the read/writes of game pads and joysticks
* graphics.library.kmod - collection of functions used to draw graphic elements on the monitor
* hunk.library.kmod - set of functions to read a data stream into memory
* input.device.kmod - handles of input events like keyboard events or mouse clicks
* intuition.library.kmod - collection of functions to create and handle all graphic elements (screens, windows, the mouse pointer...)
* layers.library.kmod - set of functions to be used to handle different layers in graphic operations
* keyboard.device.kmod - driver for the keyboard
* keymap.library.kmod - functions to handle different keymaps
* newlib.library.kmod - collection of functions to perform memory operations (allocating memory, copying memory areas... )
* nonvolatile.library.kmod - provides a simple means for an application developer to manage nonvolatile storage
* nvram.resource.kmod - handles the read/writes to the EEPROM chip present on many AmigaOS computers
* PCIGraphics.card - driver that supports the use of different graphic cards
* ram-handler.kmod - functions that handles the '''Ram disk:''' special disk
* ramdrive.device.kmod - device that allows the usage of the ramdrive device '''RAD:''' disk
* ramlib.kmod - loads disk based libraries and devices for exec.library
* rtg.library - library of functions to perform lowlevel graphic operations on graphic cards
* shell.kmod - the AmigaOS command line interface
* strap.kmod - module that handles booting on different disk devices
* timer.device.kmod - driver to give access to timing functions

=== Filesystem support ===

These kickstart modules can be loaded or left aside. If you want to use a particular filesystem on your disk partitions, you need to load the corresponding filesystem module.

* CDFileSystem - handles the CD-ROM disks with data stored in different formats: ISO9660, HFS...
* SmartFilesystem - allows the usage of partitions in SFS0 and SFS2 layouts
* JXFileSystem - allows the usage of partitions in JXFS layout
* FastFileSystem - allows the usage of partitions in FFS and FFS2 layouts
* diskcache.library.kmod - component required by the SmartFileSystem and JXFileSystem modules

=== Hardware drivers ===

==== Graphic cards drivers ====

* 3dfxVoodoo.chip
* 3DLabsPermedia2.chip
* ATIRadeon.chip
* RadeonHD.chip
* siliconmotion502.chip

==== Disk drivers ====

Each of these drivers allow the use of disks connected to a disk controller. These files are named with the name of the controller they support. As an example, the '''sii3114ide.device.kmod''' allows to use disks connected on a '''Silicon Image SiI3114''' controller chip.

* it8212ide.device.kmod
* lsi53c8xx.device.kmod
* sam460sata.device.kmod
* sii3112ide.device.kmod
* sii3512ide.device.kmod
* sii3114ide.device.kmod
* sii0680ide.device.kmod
* sii3132ide.device.kmod

==== USB drivers ====

* hub.usbfd
* usbsys.device
* usbresource.library
* ehci.usbhcd
* ohci.usbhcd
* uhci.usbhcd
* massstorage.usbfd

==== Other drivers ====

* bootkeyboard.usbfd - allows a USB keyboard to be used even before the USB stack is loaded
* bootmouse.usbfd - allows a USB mouse to be used even before the USB stack is loaded
* fpga.resource.kmod - allows to use the FPGA components which are present on some Amiga computers
* i2c.resource.kmod - allows to use the i2c interface present on some Amiga computers
* xena.resource.kmod - provides access to the Xena chip on the AmigaOne X1000

=== Misc modules ===

* petunia.library.kmod - this module contains the Just-In-Time emulator that allows AmigaOS to run programs made for the Motorola 68k processor

== System components ==

[[File:Workbench_directory_listing.png|frame|right|List of directories and files present at the root of any AmigaOS system]]

Beside the kickstart modules, AmigaOS uses many different components that can be loaded only when used. These files are stored in different directories in the system volume.
Here is described a default AmigaOS installation.

* C
This directory contains AmigaDOS '''C'''ommands
* Classes
contains different object elements easy to be used in any program: gadgets, requesters, graphic table, windows...
* Devs
contains definition for '''Dev'''ices
* Emulation
contains files used for the 68k emulation (though E-UAE)
* Fonts
contains various systems fonts
* Internet
contains a dialer to connect to Internet
* Kickstart
contains the kickstart modules
* L
contains hand'''l'''ers and filesystems
* Libs
contains dynamic '''Libr'''airies of functions
* Locale
contains all files used to localise the system (catalogs, keymaps...)
* MUI
contains the needed files for programs that use the MUI third party graphic interface
* [[Prefs]]
contains the preference programs used to customise AmigaOS
* S
contains the '''S'''cripts
* SObjs
contains .so shared object library files
* Storage
contains other optional files
* System
contains some programs used by the system itself (i.e. you don't need to run them yourself) or low-level programs like disk tools
* [[Utilities]]
contains several programs you can use to achieve some tasks on AmigaOS

= Motorola 680x0 Emulators =

For a long time Amigas have had the famous Motorola 680x0 processors as the central unit for execution. Unfortunately the time of the 680x0 series is passing in favor of other architectures. The new era of processors reached the Amiga some time ago, when expansion boards became available for extending the Classic systems with the raw power of a PowerPC processor.

In the old operating system (AmigaOS 3.x) it was not possible to gain the full advantage of the new processors. The system itself and most of the applications required the original Motorola 680x0 processor. There was no 680x0 emulation available for the PowerPCs, so the 680x0 could not be "switched off".

Thus the new processors remained as a powerful, but mostly unused adjunct to the main 680x0 processor. "Native" PowerPC programs were rare, and every time a PowerPC program called the system, a so called "context switch" occurred between the 680x0 and PowerPC code, often causing a large performance penalty.

The new Amiga platform is based on the PowerPC processor family, therefore the new version of the AmigaOS has to smooth the transition from the 680x0 series, which is achieved by emulating the old processor architecture. The operating system itself is written almost 100 percent for the PowerPC processors, but the 680x0 legacy applications require an emulated 680x0 processor.

== Two 680x0 Emulators ==

In version 4.0 of AmigaOS, two different emulators were implemented; one is the successor of BlackBox emulation, it is an interpretive emulator, thus the emulation speed is mediocre. On the other hand it has a very low "reaction time", and is ideal for time critical parts, such as interrupts.

The other is Petunia, the "JIT emulator". A fast, but less compatible way of emulation of the legacy Motorola processors. It is intended mainly for emulating applications, and therefore, when execution of the application leaves the bounds of the application's code segment, emulation falls back to the interpretive method, where it does its job and returns to the JIT emulation again.

Dynamic recompilation (also called just-in-time compilation or simply JIT compilation) is a technique of translating foreign processor machine code to native machine code, "on the fly".

This technique is common nowadays, commonly applied in JAVA virtual machines, and it is also used with success in several emulators. In dynamic recompilation there is the possibility of runtime optimization of the emulated code by collecting statistics of the execution process. Therefore (theoretically) the final executed code can be even faster than the original code on its original processor.

== Features ==

Emulated opcodes:
* all user and supervisor level opcodes of the Motorola 68040
* all FPU opcodes of the Motorola 68881/68882

AmigaOS claims only 68020/68881 compatibility to applications because this is the safest compatibility level, but both emulators are compatible with the machine code up to the level of 68040/060 processors.

At compile time, a low level flag and branch control analysis allows on-the-fly optimizations of compiled code.

== Removing the JIT Emulator ==

Using the dynamic translation requires a lot more memory than the interpretive emulation. The translated code needs to be stored somewhere, not to mention the data collection tables.

If speed is not as important as the memory consumption of the system, then the JIT emulator can be removed, leaving the job to the interpretive emulator.

Thanks to the modular design of AmigaOS kickstart, all you need to do is edit the "Sys:Kickstart/Kicklayout" file, simply put a semicolon (;) at the beginning of the module line of Petunia.library.kmod. After rebooting the system from cold, the JIT emulator will not be reloaded. Make sure that you alter the appropriate configuration in the Kicklayout file, there may be several alternative configurations, with different names like "DefaultJIT", or "DefaultNoJIT".

== Configuring the Emulators ==

Petunia cooperates with a so called "black list". By default Petunia emulates every 680x0 program or library that is loaded by DOS.library/LoadSeg function, but if an executable or library shows incompatibilities with Petunia, then it can be explicitly inhibited from the dynamic recompilation by specifying it in a list file.

If an executable needs to be added to the list, then it can be done by extending the file "DEVS:applications.dos" with the '''Compatibility''' preferences program from the Prefs drawer of the system. Adding a program name to the list and checking it will prevent Petunia from emulating that program, and it will be interpreted instead by the built-in interpreter.

Removing a program from the list or unchecking (thus allowing Petunia to emulate it again) can be done with the same preferences program.

Please note: some programs consist of multiple executables (shared libraries, plugins). If you want to fully disable the translation of such programs, then every part must be added to the list.

For example to disable UnArc fully, you would have to add all files from libs:xad and also xadmaster.library to the list.

= AmigaOS boot procedure =

Basically a computer with AmigaOS does the following when the power button is pushed:

* [[File:Uboot.jpg|200px]]
the BIOS ([[UserDoc:BIOS|Uboot]] or [[UserDoc:BIOS|CFE]]) of the computer initialises the hardware: graphic card, USB ports... At this point, the monitor wakes up and the first information are displayed. This allows to see if hardware is correctly recognised. As an example you can see if a hard drive is correctly connected into the machine and your BIOS is correctly setup to make this drive useable.
* depending on how you setup the BIOS it will look on the harddisk to find the Second Level Booter (SLB). This program is stored on the first sectors of the disk. Whereas the BIOS does not know about AmigaOS disk structure, the SLB will be able to ''understand'' the AmigaOS partitions and files. In other words, it is the link between the BIOS and the rest of the boot procedure. Its goal is also to give you the ability to start several configurations present on the same drive.
* [[File:SLB.png|200px]]
the SLB will analyses all Amiga partitions on the disk it is installed on. It will read each [[UserDoc:kickstart_configuration|system configuration]] it finds on the partitions. It will show all available configurations for the user to select one to load.
The user can define many different kickstart configurations to choose from. Also both AmigaOS and Linux can be selected for boot.
* [[File:Kmods loading.png|200px]]
the SLB loads the kickstart files of the selected configuration and executes the '''Loader''' module
* '''Loader''' executes the kickstart modules (Exec, devices, libraries...)
* AmigaOS becomes alive displaying the AmigaOS boot picture on the monitor
* the AmigaDOS library executes the [[UserDoc:System_Scripts#startup-sequence|startup-sequence]] script found on the system volume
* the Startup-sequence will be executed and all commands it contains are executed. It means that starting from here the boot procedure is easy to follow and understand.
* the Workbench is started

At this point the user can use his/her computer.

= How to make a Bootable USB Memory Stick for AmigaOS 4.1 =

By Julian Margetson ("Spectre660")

Prerequisites:
* USB memory stick of 2 GB or less in size.
* It is best to only have one USB mass storage device connected while you are creating your bootable USB memory stick.
* Plug the USB memory stick into a USB port on your machine.
* Note that the device will be formatted so make sure that you use an empty memory stick or one that does not contain any data that you need or backup the contents before you begin.

Procedure:
# You use Media Toolbox in the System: drawer to prepare the USB stick. On starting Media Toolbox select ''usbdisk.device'' as the device to use.
# Make certain that you have selected usbdisk.device and not any other device.
# Click on "Start"
# You will see the usb mass storage unit connected in a list.
# Make sure that the Unit type displayed for the USB memory stick is "Removable hard disk"
# Select that Unit by clicking on it.
# The first thing that you need to do is to install the RDB onto the USB Memory Stick.
# Click on the "Install" button.
# A window Labeled "RDB/disk geometry editing" comes up.
## Towards the bottom of the window is the "AmigaOne boot code (SLB)" section.
## Select the "Install" button .
## A file requester "Select AmigaOne Boot Code" now comes up with the Drawer choice defaulting to "l:"
## Select file "slb_v2".
## Select Ok.
## You are now returned to the "RDB/disk geometry editing window".
## Select "Ok-accept changes".
# You are now returned to the display showing the attached USB unit.
# Select "Edit partitions and Filesystems". You will now see the Window 'Editing partitions for disk"
# Select "Add partition"
# This defaults to using the whole device as a single partition.
# It is possible to use create more partitions but for this tutorial we will only use one.
# You now need to give the partition a unique name (e.g. USB0 or something that is different from any of the existing partitions on your hard drive). This is done by changing the default DH0 in the "Name" box.
# Now make sure that the Boxes "Automount" and "Bootable" are selected and show the "Tick mark".
# You need to set "Boot priority" to higher than the boot priority of your hard drive boot partition(s). This is done by increasing Boot priority by clicking on the "+" to the right of the "boot priority" box. Normally you can set the boot priority to 2 .
# Next it is time to select the file system to use.
# Select "Select filesystem/edit details".
# The Window "Editing details for partition 'USB0'" ,or whatever partition name you used, comes up.
## Select the file system that you are going to use by selecting the pull down menu under "Filesystem chooser".
## Only filesystems SFS/00 or SFS/02 will work for a bootable device.
## The option that gives the most flexibility at the moment is SFS/00 as a USB stick in this format can be read and written to using another compatible system in the event that you need to make modifications after it is created without a booting AmigaOS 4.1 machine.
## Next select Blocksize from the "Blocksize" pull down menu. 512 is the correct size to use.
## Now Select "Ok-accept changes".
## Your are now returned to the "Edit partitions for disk" window.
## Again select "Ok-accept changes"
# You are now returned to the window showing the USB mass storage unit list.
# Select "Save to disk"
# A requester pops up with the options "Yes, Save." or "No!"
# Select the "Yes, save." option.
# You now close Media Toolbox by clicking on the close icon (X) on the left of the Media Toolbox window.
# This will give you a requester advising that you need to reboot the machine for the changes to take effect. At this point you need to remove the USB memory stick for the machine. If you do not then the Machine will attempt boot from it before it is formatted and the required Kickstart and AmigaOS 4.1 files are copied to it.
# Select "Yes, reboot NOW!".
# Once you have rebooted connect your USB Memory Stick to a USB port.
# A disk icon "USB0:Uninitialized" (or whatever partition name you used) appears on Workbench.
# You now need to format the device.
# To format Select this Icon and go to the Workbench "Icons" menu .
# Select "Format Disk"
# You can give the USB Memory Stick a unique name and select whether you want a Trashcan or not.
# You can use either a full Format or a Quick Format. Full Format may take a few minutes.
# Once formatted the USB Memory Stick is ready for you to copy the required files from you hard drive or AmigaOS Install CD to it in order to boot AmigaOS 4.1 from it.

UserDoc:How AmigaOS Works

2015-05-29T06:17:19Z

Brian Deneen: /* Executable files */ grammar

As already mentioned, AmigaOS was a pioneer in the early days of personal computing in delivering sophistication that contemporary systems could only have dreamt of and pretended to offer. Today, AmigaOS continues to offer a straightforward elegance that seems to be overlooked in the development of other platforms. Thanks to the concepts behind AmigaOS, the system is easy to understand and to use by everyone.

In this page we will explore all these concepts of AmigaOS. Also you will learn here the naming of all parts of the system.

= Introduction =

AmigaOS is made of different components which are either mandatory (i.e., AmigaOS will not work without them) or components the user can choose to use or not. All these components can have one or mutiple interfaces a user or a developer can use to operate with the components and through them to control the operating system.

= The most important components =

== Exec, the AmigaOS kernel ==

Exec is the kernel of AmigaOS. It is the component that pilots all other components. It is responsible for running programs, dealing with computer memory and managing low-level resources that programs may need. In other words, it organises everything to make the operating system run.

It is made of different parts that cannot be moved outside the kernel: the scheduler, the memory pager and the 68k interpretive emulator.

== AmigaDOS: the underlying system ==

The word "DOS" was originally an acronym for "Disk Operating System". Some say it should be "Disk Based Operating System" as it does a lot more than operate a disk and that it was really an operating system based (stored) on disks. Some say it should be "Device Operating System".

The whole AmigaDOS system includes things such as:

* A set of commands that can be used in the Shell window and elsewhere.
* A system for saving data to disk and retrieving it from disk.
* A system for filing data on disks.
* An interface for peripherals such as keyboards, monitors, printers, etc.
* A method of running programs
* A multitasking system for running more than one program at a time.
* etc. etc. etc.

Read the [[AmigaDOS manual]] to understand and learn everything about AmigaDOS.

== The Graphics library ==

The Graphics library handles every low level graphic operation like designing pixels on the monitor, creating graphic elements (bobs, sprites) and also writing text output.

== Intuition ==

The Intuition library is responsible for every graphical object: windows, screens, gadgets, mouse pointers... It lies between any graphic program and the graphics library.

== The Workbench ==

The Workbench is the graphical place where you will manage your computer and all your files. The name was chosen because the user will use tools to create and work with the computer.

[[File:Wb.png|320px]]

== The Shell ==

While some people prefer to control the operating system using their mouse, others prefer using the keyboard. The shell is a text based window when you can type commands to execute actions in the operating system. In the shell the commands will display the results of their execution.

== ARexx - inter-program communication by scripting ==

The ARexx scripting language can be used to operate the Workbench and other Amiga applications from a script containing ARexx commands. This is extremely useful in performing repetitive tasks or doing what the controlled application was not even designed to do.
After a learning curve, everybody can use ARexx as it is built into the system. The scripts can be executed immediately like any other tool.

= How is my data stored? =
== Files ==
=== Executable files ===
Programs you can start are stored in executable files. They contain binary code directly understandable by the computer. They are files with an executable bit, a flag that shows AmigaOS that such file will do something when started.
An example is a music player. When you start this executable, the player opens and you can start playing music files.

AmigaOS can run two different kinds of executable files: the AmigaOS native programs made for the PowerPC processor and programs created for the Motorola 68k processors. The latter are executed inside an emulation that transcripts them into PowerPC code.

==== Scripts ====

Scripts are text files containing a list of commands. They are not strictly executables like ''binary code'' files but they can be executed by AmigaOS as if they were.
This is the case with AmigaDOS and ARexx scripts. These files need to have the executable bit, and the script bit.

=== Data files ===
Files that are not executable are data files. These contain some data that will be manipulated by programs. Some examples are a music file, a video file or a text document.

== Directories/Drawers ==
In order to organise things a bit, files are not all of them in the same place. We create directories which like drawers of a cabinet will store different files of the same kind.
Often the name ''directory'' is used when talking about the directory which is stored on a disk. The graphical interface of AmigaOS being called the Workbench, directories are often called ''drawers''.

Note: directories are often called ''folders'' on other systems.

== Disks, partitions and volumes ==
=== Disks ===
Disks are storage medium you can purchase on a computer store. We use them to store our files. They can be internal hard disks, external ones or a USB disk drive.

=== Partitions ===
A disk is often very big and many users prefer to make it more organised. This is done virtually splitting the disk into several smaller parts. This operation is known as creating partitions on a disk.

[[File:Partitions.png|Small part of Media Toolbox showing different partitions on the harddisk]]

On this screenshot you can see one harddisk with many partitions. Each color corresponds to a different filesystem which defines how data is stored. Also you can see a greyed area which is a blank area on the disk i.e. no partition is defined at this position.

=== Volumes ===
A partition is a physical area on a disk. To access it with AmigaOS we could read the physical data off the partition but it's not an easy way. To make it easier AmigaOS uses the concept of volumes. These are virtual representations of a partition. The volumes have a name so AmigaOS and therefore the user can access all files/directories stored on it in a very practical way: just by using its name.

= How to identify files/directories =

== On the Workbench ==

The Workbench being graphical, a lot of things are understandable just by looking at them. That's why icons are often enough to understand what kind of object it represents: a file, a directory, a disk...

In case you have a doubt, just look at the information on an icon. The Workbench will tell you the type of the object. It is displayed next to its name.

== In a shell ==

In a shell the '''list''' command can be used to see if an object is a file or a directory.

[[File:Files-dirs-in-shell.png|The '''list''' command shows a file of 925678 bytes and two directories]]

A file will be displayed with its size, whereas a directory will be displayed with the text '''Dir''' next to it.

Also, as you can see on the screenshot, the list command displays other characteristics on these 3 items: the protection bits and the date they were updated the last time. The command also sums up what it just listed.

= All AmigaOS components =

AmigaOS is made of components that are needed as soon as the system starts or later when the user or the system needs them.

== Kickstart modules ==

These components are the heart of AmigaOS. Their duties is to do graphics, to handle discs or to handle all reads/writes to files. Also one of them is the AmigaOS kernel which is a kind of director handling the work of all other components.
These Kickstart modules are loaded at the beginning of the operating system boot process (read [[UserDoc:How_AmigaOS_Works#AmigaOS_boot_procedure|here]]). You can find all them in the '''Kickstart''' directory in the system volume. Here is a list:

=== Mandatory modules ===

The following modules are required in any AmigaOS system. Without one of these, the system will not start.

* kernel - The kernel works like a conductor in an orchestra. Its job is to make everything works together. It creates processes, handle memory usage, defines the way other components will access peripherals...etc. Note that the AmigaOS kernel is not based on any other kernel. It is a self made kernel that works since 1983.
* loader - this component handles the loading of all other kickstart modules
* battclock.resource.kmod - this module handles reading/writing the battery backed up clock which is used on all computers to keep the date and time
* bootimage - this is the boot picture. It is displayed during the start sequence of AmigaOS
* bootmenu.kmod - this component handles the Early Startup Menu the use can use to define some settings before starting AmigaOS
* con-handler.kmod - it directs the read and write requests to the console window, to a serial AUX: device or any other supported interface
* console.device.kmod - it opens a window and reads/writes text to and from that window
* diskboot.kmod - handles the booting of AmigaOS from a supported disk
* diskboot.config - this is a text file experienced users can modify to change the boot behaviour of AmigaOS
* dos.library.kmod - this module is a collection of functions that any program can use to perform actions on disks, files and directories
* elf.library.kmod - handles the loading of executable programs
* env-handler.kmod - handles the read/writes of environment variables
* FileSystem.resource.kmod - handles the use of the different filesystems
* gadtools.library.kmod - collection of functions used to create all graphic objects like gadgets, sliders, menus...
* gameport.device.kmod - handles the read/writes of game pads and joysticks
* graphics.library.kmod - collection of functions used to draw graphic elements on the monitor
* hunk.library.kmod - set of functions to read a data stream into memory
* input.device.kmod - handles of input events like keyboard events or mouse clicks
* intuition.library.kmod - collection of functions to create and handle all graphic elements (screens, windows, the mouse pointer...)
* layers.library.kmod - set of functions to be used to handle different layers in graphic operations
* keyboard.device.kmod - driver for the keyboard
* keymap.library.kmod - functions to handle different keymaps
* newlib.library.kmod - collection of functions to perform memory operations (allocating memory, copying memory areas... )
* nonvolatile.library.kmod - provides a simple means for an application developer to manage nonvolatile storage
* nvram.resource.kmod - handles the read/writes to the EEPROM chip present on many AmigaOS computers
* PCIGraphics.card - driver that supports the use of different graphic cards
* ram-handler.kmod - functions that handles the '''Ram disk:''' special disk
* ramdrive.device.kmod - device that allows the usage of the ramdrive device '''RAD:''' disk
* ramlib.kmod - loads disk based libraries and devices for exec.library
* rtg.library - library of functions to perform lowlevel graphic operations on graphic cards
* shell.kmod - the AmigaOS command line interface
* strap.kmod - module that handles booting on different disk devices
* timer.device.kmod - driver to give access to timing functions

=== Filesystem support ===

These kickstart modules can be loaded or left aside. If you want to use a particular filesystem on your disk partitions, you need to load the corresponding filesystem module.

* CDFileSystem - handles the CD-ROM disks with data stored in different formats: ISO9660, HFS...
* SmartFilesystem - allows the usage of partitions in SFS0 and SFS2 layouts
* JXFileSystem - allows the usage of partitions in JXFS layout
* FastFileSystem - allows the usage of partitions in FFS and FFS2 layouts
* diskcache.library.kmod - component required by the SmartFileSystem and JXFileSystem modules

=== Hardware drivers ===

==== Graphic cards drivers ====

* 3dfxVoodoo.chip
* 3DLabsPermedia2.chip
* ATIRadeon.chip
* RadeonHD.chip
* siliconmotion502.chip

==== Disk drivers ====

Each of these drivers allow the use of disks connected to a disk controller. These files are named with the name of the controller they support. As an example, the '''sii3114ide.device.kmod''' allows to use disks connected on a '''Silicon Image SiI3114''' controller chip.

* it8212ide.device.kmod
* lsi53c8xx.device.kmod
* sam460sata.device.kmod
* sii3112ide.device.kmod
* sii3512ide.device.kmod
* sii3114ide.device.kmod
* sii0680ide.device.kmod
* sii3132ide.device.kmod

==== USB drivers ====

* hub.usbfd
* usbsys.device
* usbresource.library
* ehci.usbhcd
* ohci.usbhcd
* uhci.usbhcd
* massstorage.usbfd

==== Other drivers ====

* bootkeyboard.usbfd - allows a USB keyboard to be used even before the USB stack is loaded
* bootmouse.usbfd - allows a USB mouse to be used even before the USB stack is loaded
* fpga.resource.kmod - allows to use the FPGA components which are present on some Amiga computers
* i2c.resource.kmod - allows to use the i2c interface present on some Amiga computers
* xena.resource.kmod - provides access to the Xena chip on the AmigaOne X1000

=== Misc modules ===

* petunia.library.kmod - this module contains the Just-In-Time emulator that allows AmigaOS to run programs made for the Motorola 68k processor

== System components ==

[[File:Workbench_directory_listing.png|frame|right|List of directories and files present at the root of any AmigaOS system]]

Beside the kickstart modules, AmigaOS uses many different components that can be loaded only when used. These files are stored in different directories in the system volume.
Here is described a default AmigaOS installation.

* C
This directory contains AmigaDOS '''C'''ommands
* Classes
contains different object elements easy to be used in any program: gadgets, requesters, graphic table, windows...
* Devs
contains definition for '''Dev'''ices
* Emulation
contains files used for the 68k emulation (though E-UAE)
* Fonts
contains various systems fonts
* Internet
contains a dialer to connect to Internet
* Kickstart
contains the kickstart modules
* L
contains hand'''l'''ers and filesystems
* Libs
contains dynamic '''Libr'''airies of functions
* Locale
contains all files used to localise the system (catalogs, keymaps...)
* MUI
contains the needed files for programs that use the MUI third party graphic interface
* [[Prefs]]
contains the preference programs used to customise AmigaOS
* S
contains the '''S'''cripts
* SObjs
contains .so shared object library files
* Storage
contains other optional files
* System
contains some programs used by the system itself (i.e. you don't need to run them yourself) or low-level programs like disk tools
* [[Utilities]]
contains several programs you can use to achieve some tasks on AmigaOS

= Motorola 680x0 Emulators =

For a long time Amigas have had the famous Motorola 680x0 processors as the central unit for execution. Unfortunately the time of the 680x0 series is passing in favor of other architectures. The new era of processors reached the Amiga some time ago, when expansion boards became available for extending the Classic systems with the raw power of a PowerPC processor.

In the old operating system (AmigaOS 3.x) it was not possible to gain the full advantage of the new processors. The system itself and most of the applications required the original Motorola 680x0 processor. There was no 680x0 emulation available for the PowerPCs, so the 680x0 could not be "switched off".

Thus the new processors remained as a powerful, but mostly unused adjunct to the main 680x0 processor. "Native" PowerPC programs were rare, and every time a PowerPC program called the system, a so called "context switch" occurred between the 680x0 and PowerPC code, often causing a large performance penalty.

The new Amiga platform is based on the PowerPC processor family, therefore the new version of the AmigaOS has to smooth the transition from the 680x0 series, which is achieved by emulating the old processor architecture. The operating system itself is written almost 100 percent for the PowerPC processors, but the 680x0 legacy applications require an emulated 680x0 processor.

== Two 680x0 Emulators ==

In version 4.0 of AmigaOS, two different emulators were implemented; one is the successor of BlackBox emulation, it is an interpretive emulator, thus the emulation speed is mediocre. On the other hand it has a very low "reaction time", and is ideal for time critical parts, such as interrupts.

The other is Petunia, the "JIT emulator". A fast, but less compatible way of emulation of the legacy Motorola processors. It is intended mainly for emulating applications, and therefore, when execution of the application leaves the bounds of the application's code segment, emulation falls back to the interpretive method, where it does its job and returns to the JIT emulation again.

Dynamic recompilation (also called just-in-time compilation or simply JIT compilation) is a technique of translating foreign processor machine code to native machine code, "on the fly".

This technique is common nowadays, commonly applied in JAVA virtual machines, and it is also used with success in several emulators. In dynamic recompilation there is the possibility of runtime optimization of the emulated code by collecting statistics of the execution process. Therefore (theoretically) the final executed code can be even faster than the original code on its original processor.

== Features ==

Emulated opcodes:
* all user and supervisor level opcodes of the Motorola 68040
* all FPU opcodes of the Motorola 68881/68882

AmigaOS claims only 68020/68881 compatibility to applications because this is the safest compatibility level, but both emulators are compatible with the machine code up to the level of 68040/060 processors.

At compile time, a low level flag and branch control analysis allows on-the-fly optimizations of compiled code.

== Removing the JIT Emulator ==

Using the dynamic translation requires a lot more memory than the interpretive emulation. The translated code needs to be stored somewhere, not to mention the data collection tables.

If speed is not as important as the memory consumption of the system, then the JIT emulator can be removed, leaving the job to the interpretive emulator.

Thanks to the modular design of AmigaOS kickstart, all you need to do is edit the "Sys:Kickstart/Kicklayout" file, simply put a semicolon (;) at the beginning of the module line of Petunia.library.kmod. After rebooting the system from cold, the JIT emulator will not be reloaded. Make sure that you alter the appropriate configuration in the Kicklayout file, there may be several alternative configurations, with different names like "DefaultJIT", or "DefaultNoJIT".

== Configuring the Emulators ==

Petunia cooperates with a so called "black list". By default Petunia emulates every 680x0 program or library that is loaded by DOS.library/LoadSeg function, but if an executable or library shows incompatibilities with Petunia, then it can be explicitly inhibited from the dynamic recompilation by specifying it in a list file.

If an executable needs to be added to the list, then it can be done by extending the file "DEVS:applications.dos" with the '''Compatibility''' preferences program from the Prefs drawer of the system. Adding a program name to the list and checking it will prevent Petunia from emulating that program, and it will be interpreted instead by the built-in interpreter.

Removing a program from the list or unchecking (thus allowing Petunia to emulate it again) can be done with the same preferences program.

Please note: some programs consist of multiple executables (shared libraries, plugins). If you want to fully disable the translation of such programs, then every part must be added to the list.

For example to disable UnArc fully, you would have to add all files from libs:xad and also xadmaster.library to the list.

= AmigaOS boot procedure =

Basically a computer with AmigaOS does the following when the power button is pushed:

* [[File:Uboot.jpg|200px]]
the BIOS ([[UserDoc:BIOS|Uboot]] or [[UserDoc:BIOS|CFE]]) of the computer initialises the hardware: graphic card, USB ports... At this point, the monitor wakes up and the first information are displayed. This allows to see if hardware is correctly recognised. As an example you can see if a hard drive is correctly connected into the machine and your BIOS is correctly setup to make this drive useable.
* depending on how you setup the BIOS it will look on the harddisk to find the Second Level Booter (SLB). This program is stored on the first sectors of the disk. Whereas the BIOS does not know about AmigaOS disk structure, the SLB will be able to ''understand'' the AmigaOS partitions and files. In other words, it is the link between the BIOS and the rest of the boot procedure. Its goal is also to give you the ability to start several configurations present on the same drive.
* [[File:SLB.png|200px]]
the SLB will analyses all Amiga partitions on the disk it is installed on. It will read each [[UserDoc:kickstart_configuration|system configuration]] it finds on the partitions. It will show all available configurations for the user to select one to load.
The user can define many different kickstart configurations to choose from. Also both AmigaOS and Linux can be selected for boot.
* [[File:Kmods loading.png|200px]]
the SLB loads the kickstart files of the selected configuration and executes the '''Loader''' module
* '''Loader''' executes the kickstart modules (Exec, devices, libraries...)
* AmigaOS becomes alive displaying the AmigaOS boot picture on the monitor
* the AmigaDOS library executes the [[UserDoc:System_Scripts#startup-sequence|startup-sequence]] script found on the system volume
* the Startup-sequence will be executed and all commands it contains are executed. It means that starting from here the boot procedure is easy to follow and understand.
* the Workbench is started

At this point the user can use his/her computer.

= How to make a Bootable USB Memory Stick for AmigaOS 4.1 =

By Julian Margetson ("Spectre660")

Prerequisites:
* USB memory stick of 2 GB or less in size.
* It is best to only have one USB mass storage device connected while you are creating your bootable USB memory stick.
* Plug the USB memory stick into a USB port on your machine.
* Note that the device will be formatted so make sure that you use an empty memory stick or one that does not contain any data that you need or backup the contents before you begin.

Procedure:
# You use Media Toolbox in the System: drawer to prepare the USB stick. On starting Media Toolbox select ''usbdisk.device'' as the device to use.
# Make certain that you have selected usbdisk.device and not any other device.
# Click on "Start"
# You will see the usb mass storage unit connected in a list.
# Make sure that the Unit type displayed for the USB memory stick is "Removable hard disk"
# Select that Unit by clicking on it.
# The first thing that you need to do is to install the RDB onto the USB Memory Stick.
# Click on the "Install" button.
# A window Labeled "RDB/disk geometry editing" comes up.
## Towards the bottom of the window is the "AmigaOne boot code (SLB)" section.
## Select the "Install" button .
## A file requester "Select AmigaOne Boot Code" now comes up with the Drawer choice defaulting to "l:"
## Select file "slb_v2".
## Select Ok.
## You are now returned to the "RDB/disk geometry editing window".
## Select "Ok-accept changes".
# You are now returned to the display showing the attached USB unit.
# Select "Edit partitions and Filesystems". You will now see the Window 'Editing partitions for disk"
# Select "Add partition"
# This defaults to using the whole device as a single partition.
# It is possible to use create more partitions but for this tutorial we will only use one.
# You now need to give the partition a unique name (e.g. USB0 or something that is different from any of the existing partitions on your hard drive). This is done by changing the default DH0 in the "Name" box.
# Now make sure that the Boxes "Automount" and "Bootable" are selected and show the "Tick mark".
# You need to set "Boot priority" to higher than the boot priority of your hard drive boot partition(s). This is done by increasing Boot priority by clicking on the "+" to the right of the "boot priority" box. Normally you can set the boot priority to 2 .
# Next it is time to select the file system to use.
# Select "Select filesystem/edit details".
# The Window "Editing details for partition 'USB0'" ,or whatever partition name you used, comes up.
## Select the file system that you are going to use by selecting the pull down menu under "Filesystem chooser".
## Only filesystems SFS/00 or SFS/02 will work for a bootable device.
## The option that gives the most flexibility at the moment is SFS/00 as a USB stick in this format can be read and written to using another compatible system in the event that you need to make modifications after it is created without a booting AmigaOS 4.1 machine.
## Next select Blocksize from the "Blocksize" pull down menu. 512 is the correct size to use.
## Now Select "Ok-accept changes".
## Your are now returned to the "Edit partitions for disk" window.
## Again select "Ok-accept changes"
# You are now returned to the window showing the USB mass storage unit list.
# Select "Save to disk"
# A requester pops up with the options "Yes, Save." or "No!"
# Select the "Yes, save." option.
# You now close Media Toolbox by clicking on the close icon (X) on the left of the Media Toolbox window.
# This will give you a requester advising that you need to reboot the machine for the changes to take effect. At this point you need to remove the USB memory stick for the machine. If you do not then the Machine will attempt boot from it before it is formatted and the required Kickstart and AmigaOS 4.1 files are copied to it.
# Select "Yes, reboot NOW!".
# Once you have rebooted connect your USB Memory Stick to a USB port.
# A disk icon "USB0:Uninitialized" (or whatever partition name you used) appears on Workbench.
# You now need to format the device.
# To format Select this Icon and go to the Workbench "Icons" menu .
# Select "Format Disk"
# You can give the USB Memory Stick a unique name and select whether you want a Trashcan or not.
# You can use either a full Format or a Quick Format. Full Format may take a few minutes.
# Once formatted the USB Memory Stick is ready for you to copy the required files from you hard drive or AmigaOS Install CD to it in order to boot AmigaOS 4.1 from it.

UserDoc:How AmigaOS Works

2015-05-29T06:15:23Z

Brian Deneen: /* ARexx - inter-program communication by scripting */ grammar

As already mentioned, AmigaOS was a pioneer in the early days of personal computing in delivering sophistication that contemporary systems could only have dreamt of and pretended to offer. Today, AmigaOS continues to offer a straightforward elegance that seems to be overlooked in the development of other platforms. Thanks to the concepts behind AmigaOS, the system is easy to understand and to use by everyone.

In this page we will explore all these concepts of AmigaOS. Also you will learn here the naming of all parts of the system.

= Introduction =

AmigaOS is made of different components which are either mandatory (i.e., AmigaOS will not work without them) or components the user can choose to use or not. All these components can have one or mutiple interfaces a user or a developer can use to operate with the components and through them to control the operating system.

= The most important components =

== Exec, the AmigaOS kernel ==

Exec is the kernel of AmigaOS. It is the component that pilots all other components. It is responsible for running programs, dealing with computer memory and managing low-level resources that programs may need. In other words, it organises everything to make the operating system run.

It is made of different parts that cannot be moved outside the kernel: the scheduler, the memory pager and the 68k interpretive emulator.

== AmigaDOS: the underlying system ==

The word "DOS" was originally an acronym for "Disk Operating System". Some say it should be "Disk Based Operating System" as it does a lot more than operate a disk and that it was really an operating system based (stored) on disks. Some say it should be "Device Operating System".

The whole AmigaDOS system includes things such as:

* A set of commands that can be used in the Shell window and elsewhere.
* A system for saving data to disk and retrieving it from disk.
* A system for filing data on disks.
* An interface for peripherals such as keyboards, monitors, printers, etc.
* A method of running programs
* A multitasking system for running more than one program at a time.
* etc. etc. etc.

Read the [[AmigaDOS manual]] to understand and learn everything about AmigaDOS.

== The Graphics library ==

The Graphics library handles every low level graphic operation like designing pixels on the monitor, creating graphic elements (bobs, sprites) and also writing text output.

== Intuition ==

The Intuition library is responsible for every graphical object: windows, screens, gadgets, mouse pointers... It lies between any graphic program and the graphics library.

== The Workbench ==

The Workbench is the graphical place where you will manage your computer and all your files. The name was chosen because the user will use tools to create and work with the computer.

[[File:Wb.png|320px]]

== The Shell ==

While some people prefer to control the operating system using their mouse, others prefer using the keyboard. The shell is a text based window when you can type commands to execute actions in the operating system. In the shell the commands will display the results of their execution.

== ARexx - inter-program communication by scripting ==

The ARexx scripting language can be used to operate the Workbench and other Amiga applications from a script containing ARexx commands. This is extremely useful in performing repetitive tasks or doing what the controlled application was not even designed to do.
After a learning curve, everybody can use ARexx as it is built into the system. The scripts can be executed immediately like any other tool.

= How is my data stored? =
== Files ==
=== Executable files ===
Programs you can start are stored in executable files. They contain binary code directly understandable by the computer. They are files with an executable bit, a flag that shows AmigaOS that such file will do something when started.
An example is a music player. When you start this executable, the player opens and you can start playing music files.

AmigaOS can run two different kinds of executable files: the AmigaOS native programs made for the PowerPC processor and programs created for the Motorola 68k processors. The laters are executed inside an emulation that transcripts them into PowerPC code.

==== Scripts ====

Scripts are text files containing a list of commands. So they are not strictly executables like ''binary code'' files but they can be executed by AmigaOS like if they were.
This is the case with AmigaDOS and ARexx scripts. These files need to have the executable bit, and the script bit.

=== Data files ===
Files that are not executable are data files. These contain some data that will be manipulated by programs. Some examples are a music file, a video file or a text document.

== Directories/Drawers ==
In order to organise things a bit, files are not all of them in the same place. We create directories which like drawers of a cabinet will store different files of the same kind.
Often the name ''directory'' is used when talking about the directory which is stored on a disk. The graphical interface of AmigaOS being called the Workbench, directories are often called ''drawers''.

Note: directories are often called ''folders'' on other systems.

== Disks, partitions and volumes ==
=== Disks ===
Disks are storage medium you can purchase on a computer store. We use them to store our files. They can be internal hard disks, external ones or a USB disk drive.

=== Partitions ===
A disk is often very big and many users prefer to make it more organised. This is done virtually splitting the disk into several smaller parts. This operation is known as creating partitions on a disk.

[[File:Partitions.png|Small part of Media Toolbox showing different partitions on the harddisk]]

On this screenshot you can see one harddisk with many partitions. Each color corresponds to a different filesystem which defines how data is stored. Also you can see a greyed area which is a blank area on the disk i.e. no partition is defined at this position.

=== Volumes ===
A partition is a physical area on a disk. To access it with AmigaOS we could read the physical data off the partition but it's not an easy way. To make it easier AmigaOS uses the concept of volumes. These are virtual representations of a partition. The volumes have a name so AmigaOS and therefore the user can access all files/directories stored on it in a very practical way: just by using its name.

= How to identify files/directories =

== On the Workbench ==

The Workbench being graphical, a lot of things are understandable just by looking at them. That's why icons are often enough to understand what kind of object it represents: a file, a directory, a disk...

In case you have a doubt, just look at the information on an icon. The Workbench will tell you the type of the object. It is displayed next to its name.

== In a shell ==

In a shell the '''list''' command can be used to see if an object is a file or a directory.

[[File:Files-dirs-in-shell.png|The '''list''' command shows a file of 925678 bytes and two directories]]

A file will be displayed with its size, whereas a directory will be displayed with the text '''Dir''' next to it.

Also, as you can see on the screenshot, the list command displays other characteristics on these 3 items: the protection bits and the date they were updated the last time. The command also sums up what it just listed.

= All AmigaOS components =

AmigaOS is made of components that are needed as soon as the system starts or later when the user or the system needs them.

== Kickstart modules ==

These components are the heart of AmigaOS. Their duties is to do graphics, to handle discs or to handle all reads/writes to files. Also one of them is the AmigaOS kernel which is a kind of director handling the work of all other components.
These Kickstart modules are loaded at the beginning of the operating system boot process (read [[UserDoc:How_AmigaOS_Works#AmigaOS_boot_procedure|here]]). You can find all them in the '''Kickstart''' directory in the system volume. Here is a list:

=== Mandatory modules ===

The following modules are required in any AmigaOS system. Without one of these, the system will not start.

* kernel - The kernel works like a conductor in an orchestra. Its job is to make everything works together. It creates processes, handle memory usage, defines the way other components will access peripherals...etc. Note that the AmigaOS kernel is not based on any other kernel. It is a self made kernel that works since 1983.
* loader - this component handles the loading of all other kickstart modules
* battclock.resource.kmod - this module handles reading/writing the battery backed up clock which is used on all computers to keep the date and time
* bootimage - this is the boot picture. It is displayed during the start sequence of AmigaOS
* bootmenu.kmod - this component handles the Early Startup Menu the use can use to define some settings before starting AmigaOS
* con-handler.kmod - it directs the read and write requests to the console window, to a serial AUX: device or any other supported interface
* console.device.kmod - it opens a window and reads/writes text to and from that window
* diskboot.kmod - handles the booting of AmigaOS from a supported disk
* diskboot.config - this is a text file experienced users can modify to change the boot behaviour of AmigaOS
* dos.library.kmod - this module is a collection of functions that any program can use to perform actions on disks, files and directories
* elf.library.kmod - handles the loading of executable programs
* env-handler.kmod - handles the read/writes of environment variables
* FileSystem.resource.kmod - handles the use of the different filesystems
* gadtools.library.kmod - collection of functions used to create all graphic objects like gadgets, sliders, menus...
* gameport.device.kmod - handles the read/writes of game pads and joysticks
* graphics.library.kmod - collection of functions used to draw graphic elements on the monitor
* hunk.library.kmod - set of functions to read a data stream into memory
* input.device.kmod - handles of input events like keyboard events or mouse clicks
* intuition.library.kmod - collection of functions to create and handle all graphic elements (screens, windows, the mouse pointer...)
* layers.library.kmod - set of functions to be used to handle different layers in graphic operations
* keyboard.device.kmod - driver for the keyboard
* keymap.library.kmod - functions to handle different keymaps
* newlib.library.kmod - collection of functions to perform memory operations (allocating memory, copying memory areas... )
* nonvolatile.library.kmod - provides a simple means for an application developer to manage nonvolatile storage
* nvram.resource.kmod - handles the read/writes to the EEPROM chip present on many AmigaOS computers
* PCIGraphics.card - driver that supports the use of different graphic cards
* ram-handler.kmod - functions that handles the '''Ram disk:''' special disk
* ramdrive.device.kmod - device that allows the usage of the ramdrive device '''RAD:''' disk
* ramlib.kmod - loads disk based libraries and devices for exec.library
* rtg.library - library of functions to perform lowlevel graphic operations on graphic cards
* shell.kmod - the AmigaOS command line interface
* strap.kmod - module that handles booting on different disk devices
* timer.device.kmod - driver to give access to timing functions

=== Filesystem support ===

These kickstart modules can be loaded or left aside. If you want to use a particular filesystem on your disk partitions, you need to load the corresponding filesystem module.

* CDFileSystem - handles the CD-ROM disks with data stored in different formats: ISO9660, HFS...
* SmartFilesystem - allows the usage of partitions in SFS0 and SFS2 layouts
* JXFileSystem - allows the usage of partitions in JXFS layout
* FastFileSystem - allows the usage of partitions in FFS and FFS2 layouts
* diskcache.library.kmod - component required by the SmartFileSystem and JXFileSystem modules

=== Hardware drivers ===

==== Graphic cards drivers ====

* 3dfxVoodoo.chip
* 3DLabsPermedia2.chip
* ATIRadeon.chip
* RadeonHD.chip
* siliconmotion502.chip

==== Disk drivers ====

Each of these drivers allow the use of disks connected to a disk controller. These files are named with the name of the controller they support. As an example, the '''sii3114ide.device.kmod''' allows to use disks connected on a '''Silicon Image SiI3114''' controller chip.

* it8212ide.device.kmod
* lsi53c8xx.device.kmod
* sam460sata.device.kmod
* sii3112ide.device.kmod
* sii3512ide.device.kmod
* sii3114ide.device.kmod
* sii0680ide.device.kmod
* sii3132ide.device.kmod

==== USB drivers ====

* hub.usbfd
* usbsys.device
* usbresource.library
* ehci.usbhcd
* ohci.usbhcd
* uhci.usbhcd
* massstorage.usbfd

==== Other drivers ====

* bootkeyboard.usbfd - allows a USB keyboard to be used even before the USB stack is loaded
* bootmouse.usbfd - allows a USB mouse to be used even before the USB stack is loaded
* fpga.resource.kmod - allows to use the FPGA components which are present on some Amiga computers
* i2c.resource.kmod - allows to use the i2c interface present on some Amiga computers
* xena.resource.kmod - provides access to the Xena chip on the AmigaOne X1000

=== Misc modules ===

* petunia.library.kmod - this module contains the Just-In-Time emulator that allows AmigaOS to run programs made for the Motorola 68k processor

== System components ==

[[File:Workbench_directory_listing.png|frame|right|List of directories and files present at the root of any AmigaOS system]]

Beside the kickstart modules, AmigaOS uses many different components that can be loaded only when used. These files are stored in different directories in the system volume.
Here is described a default AmigaOS installation.

* C
This directory contains AmigaDOS '''C'''ommands
* Classes
contains different object elements easy to be used in any program: gadgets, requesters, graphic table, windows...
* Devs
contains definition for '''Dev'''ices
* Emulation
contains files used for the 68k emulation (though E-UAE)
* Fonts
contains various systems fonts
* Internet
contains a dialer to connect to Internet
* Kickstart
contains the kickstart modules
* L
contains hand'''l'''ers and filesystems
* Libs
contains dynamic '''Libr'''airies of functions
* Locale
contains all files used to localise the system (catalogs, keymaps...)
* MUI
contains the needed files for programs that use the MUI third party graphic interface
* [[Prefs]]
contains the preference programs used to customise AmigaOS
* S
contains the '''S'''cripts
* SObjs
contains .so shared object library files
* Storage
contains other optional files
* System
contains some programs used by the system itself (i.e. you don't need to run them yourself) or low-level programs like disk tools
* [[Utilities]]
contains several programs you can use to achieve some tasks on AmigaOS

= Motorola 680x0 Emulators =

For a long time Amigas have had the famous Motorola 680x0 processors as the central unit for execution. Unfortunately the time of the 680x0 series is passing in favor of other architectures. The new era of processors reached the Amiga some time ago, when expansion boards became available for extending the Classic systems with the raw power of a PowerPC processor.

In the old operating system (AmigaOS 3.x) it was not possible to gain the full advantage of the new processors. The system itself and most of the applications required the original Motorola 680x0 processor. There was no 680x0 emulation available for the PowerPCs, so the 680x0 could not be "switched off".

Thus the new processors remained as a powerful, but mostly unused adjunct to the main 680x0 processor. "Native" PowerPC programs were rare, and every time a PowerPC program called the system, a so called "context switch" occurred between the 680x0 and PowerPC code, often causing a large performance penalty.

The new Amiga platform is based on the PowerPC processor family, therefore the new version of the AmigaOS has to smooth the transition from the 680x0 series, which is achieved by emulating the old processor architecture. The operating system itself is written almost 100 percent for the PowerPC processors, but the 680x0 legacy applications require an emulated 680x0 processor.

== Two 680x0 Emulators ==

In version 4.0 of AmigaOS, two different emulators were implemented; one is the successor of BlackBox emulation, it is an interpretive emulator, thus the emulation speed is mediocre. On the other hand it has a very low "reaction time", and is ideal for time critical parts, such as interrupts.

The other is Petunia, the "JIT emulator". A fast, but less compatible way of emulation of the legacy Motorola processors. It is intended mainly for emulating applications, and therefore, when execution of the application leaves the bounds of the application's code segment, emulation falls back to the interpretive method, where it does its job and returns to the JIT emulation again.

Dynamic recompilation (also called just-in-time compilation or simply JIT compilation) is a technique of translating foreign processor machine code to native machine code, "on the fly".

This technique is common nowadays, commonly applied in JAVA virtual machines, and it is also used with success in several emulators. In dynamic recompilation there is the possibility of runtime optimization of the emulated code by collecting statistics of the execution process. Therefore (theoretically) the final executed code can be even faster than the original code on its original processor.

== Features ==

Emulated opcodes:
* all user and supervisor level opcodes of the Motorola 68040
* all FPU opcodes of the Motorola 68881/68882

AmigaOS claims only 68020/68881 compatibility to applications because this is the safest compatibility level, but both emulators are compatible with the machine code up to the level of 68040/060 processors.

At compile time, a low level flag and branch control analysis allows on-the-fly optimizations of compiled code.

== Removing the JIT Emulator ==

Using the dynamic translation requires a lot more memory than the interpretive emulation. The translated code needs to be stored somewhere, not to mention the data collection tables.

If speed is not as important as the memory consumption of the system, then the JIT emulator can be removed, leaving the job to the interpretive emulator.

Thanks to the modular design of AmigaOS kickstart, all you need to do is edit the "Sys:Kickstart/Kicklayout" file, simply put a semicolon (;) at the beginning of the module line of Petunia.library.kmod. After rebooting the system from cold, the JIT emulator will not be reloaded. Make sure that you alter the appropriate configuration in the Kicklayout file, there may be several alternative configurations, with different names like "DefaultJIT", or "DefaultNoJIT".

== Configuring the Emulators ==

Petunia cooperates with a so called "black list". By default Petunia emulates every 680x0 program or library that is loaded by DOS.library/LoadSeg function, but if an executable or library shows incompatibilities with Petunia, then it can be explicitly inhibited from the dynamic recompilation by specifying it in a list file.

If an executable needs to be added to the list, then it can be done by extending the file "DEVS:applications.dos" with the '''Compatibility''' preferences program from the Prefs drawer of the system. Adding a program name to the list and checking it will prevent Petunia from emulating that program, and it will be interpreted instead by the built-in interpreter.

Removing a program from the list or unchecking (thus allowing Petunia to emulate it again) can be done with the same preferences program.

Please note: some programs consist of multiple executables (shared libraries, plugins). If you want to fully disable the translation of such programs, then every part must be added to the list.

For example to disable UnArc fully, you would have to add all files from libs:xad and also xadmaster.library to the list.

= AmigaOS boot procedure =

Basically a computer with AmigaOS does the following when the power button is pushed:

* [[File:Uboot.jpg|200px]]
the BIOS ([[UserDoc:BIOS|Uboot]] or [[UserDoc:BIOS|CFE]]) of the computer initialises the hardware: graphic card, USB ports... At this point, the monitor wakes up and the first information are displayed. This allows to see if hardware is correctly recognised. As an example you can see if a hard drive is correctly connected into the machine and your BIOS is correctly setup to make this drive useable.
* depending on how you setup the BIOS it will look on the harddisk to find the Second Level Booter (SLB). This program is stored on the first sectors of the disk. Whereas the BIOS does not know about AmigaOS disk structure, the SLB will be able to ''understand'' the AmigaOS partitions and files. In other words, it is the link between the BIOS and the rest of the boot procedure. Its goal is also to give you the ability to start several configurations present on the same drive.
* [[File:SLB.png|200px]]
the SLB will analyses all Amiga partitions on the disk it is installed on. It will read each [[UserDoc:kickstart_configuration|system configuration]] it finds on the partitions. It will show all available configurations for the user to select one to load.
The user can define many different kickstart configurations to choose from. Also both AmigaOS and Linux can be selected for boot.
* [[File:Kmods loading.png|200px]]
the SLB loads the kickstart files of the selected configuration and executes the '''Loader''' module
* '''Loader''' executes the kickstart modules (Exec, devices, libraries...)
* AmigaOS becomes alive displaying the AmigaOS boot picture on the monitor
* the AmigaDOS library executes the [[UserDoc:System_Scripts#startup-sequence|startup-sequence]] script found on the system volume
* the Startup-sequence will be executed and all commands it contains are executed. It means that starting from here the boot procedure is easy to follow and understand.
* the Workbench is started

At this point the user can use his/her computer.

= How to make a Bootable USB Memory Stick for AmigaOS 4.1 =

By Julian Margetson ("Spectre660")

Prerequisites:
* USB memory stick of 2 GB or less in size.
* It is best to only have one USB mass storage device connected while you are creating your bootable USB memory stick.
* Plug the USB memory stick into a USB port on your machine.
* Note that the device will be formatted so make sure that you use an empty memory stick or one that does not contain any data that you need or backup the contents before you begin.

Procedure:
# You use Media Toolbox in the System: drawer to prepare the USB stick. On starting Media Toolbox select ''usbdisk.device'' as the device to use.
# Make certain that you have selected usbdisk.device and not any other device.
# Click on "Start"
# You will see the usb mass storage unit connected in a list.
# Make sure that the Unit type displayed for the USB memory stick is "Removable hard disk"
# Select that Unit by clicking on it.
# The first thing that you need to do is to install the RDB onto the USB Memory Stick.
# Click on the "Install" button.
# A window Labeled "RDB/disk geometry editing" comes up.
## Towards the bottom of the window is the "AmigaOne boot code (SLB)" section.
## Select the "Install" button .
## A file requester "Select AmigaOne Boot Code" now comes up with the Drawer choice defaulting to "l:"
## Select file "slb_v2".
## Select Ok.
## You are now returned to the "RDB/disk geometry editing window".
## Select "Ok-accept changes".
# You are now returned to the display showing the attached USB unit.
# Select "Edit partitions and Filesystems". You will now see the Window 'Editing partitions for disk"
# Select "Add partition"
# This defaults to using the whole device as a single partition.
# It is possible to use create more partitions but for this tutorial we will only use one.
# You now need to give the partition a unique name (e.g. USB0 or something that is different from any of the existing partitions on your hard drive). This is done by changing the default DH0 in the "Name" box.
# Now make sure that the Boxes "Automount" and "Bootable" are selected and show the "Tick mark".
# You need to set "Boot priority" to higher than the boot priority of your hard drive boot partition(s). This is done by increasing Boot priority by clicking on the "+" to the right of the "boot priority" box. Normally you can set the boot priority to 2 .
# Next it is time to select the file system to use.
# Select "Select filesystem/edit details".
# The Window "Editing details for partition 'USB0'" ,or whatever partition name you used, comes up.
## Select the file system that you are going to use by selecting the pull down menu under "Filesystem chooser".
## Only filesystems SFS/00 or SFS/02 will work for a bootable device.
## The option that gives the most flexibility at the moment is SFS/00 as a USB stick in this format can be read and written to using another compatible system in the event that you need to make modifications after it is created without a booting AmigaOS 4.1 machine.
## Next select Blocksize from the "Blocksize" pull down menu. 512 is the correct size to use.
## Now Select "Ok-accept changes".
## Your are now returned to the "Edit partitions for disk" window.
## Again select "Ok-accept changes"
# You are now returned to the window showing the USB mass storage unit list.
# Select "Save to disk"
# A requester pops up with the options "Yes, Save." or "No!"
# Select the "Yes, save." option.
# You now close Media Toolbox by clicking on the close icon (X) on the left of the Media Toolbox window.
# This will give you a requester advising that you need to reboot the machine for the changes to take effect. At this point you need to remove the USB memory stick for the machine. If you do not then the Machine will attempt boot from it before it is formatted and the required Kickstart and AmigaOS 4.1 files are copied to it.
# Select "Yes, reboot NOW!".
# Once you have rebooted connect your USB Memory Stick to a USB port.
# A disk icon "USB0:Uninitialized" (or whatever partition name you used) appears on Workbench.
# You now need to format the device.
# To format Select this Icon and go to the Workbench "Icons" menu .
# Select "Format Disk"
# You can give the USB Memory Stick a unique name and select whether you want a Trashcan or not.
# You can use either a full Format or a Quick Format. Full Format may take a few minutes.
# Once formatted the USB Memory Stick is ready for you to copy the required files from you hard drive or AmigaOS Install CD to it in order to boot AmigaOS 4.1 from it.

UserDoc:How AmigaOS Works

2015-05-29T06:14:21Z

Brian Deneen: /* ARexx - inter-program communication by scripting */ grammar

As already mentioned, AmigaOS was a pioneer in the early days of personal computing in delivering sophistication that contemporary systems could only have dreamt of and pretended to offer. Today, AmigaOS continues to offer a straightforward elegance that seems to be overlooked in the development of other platforms. Thanks to the concepts behind AmigaOS, the system is easy to understand and to use by everyone.

In this page we will explore all these concepts of AmigaOS. Also you will learn here the naming of all parts of the system.

= Introduction =

AmigaOS is made of different components which are either mandatory (i.e., AmigaOS will not work without them) or components the user can choose to use or not. All these components can have one or mutiple interfaces a user or a developer can use to operate with the components and through them to control the operating system.

= The most important components =

== Exec, the AmigaOS kernel ==

Exec is the kernel of AmigaOS. It is the component that pilots all other components. It is responsible for running programs, dealing with computer memory and managing low-level resources that programs may need. In other words, it organises everything to make the operating system run.

It is made of different parts that cannot be moved outside the kernel: the scheduler, the memory pager and the 68k interpretive emulator.

== AmigaDOS: the underlying system ==

The word "DOS" was originally an acronym for "Disk Operating System". Some say it should be "Disk Based Operating System" as it does a lot more than operate a disk and that it was really an operating system based (stored) on disks. Some say it should be "Device Operating System".

The whole AmigaDOS system includes things such as:

* A set of commands that can be used in the Shell window and elsewhere.
* A system for saving data to disk and retrieving it from disk.
* A system for filing data on disks.
* An interface for peripherals such as keyboards, monitors, printers, etc.
* A method of running programs
* A multitasking system for running more than one program at a time.
* etc. etc. etc.

Read the [[AmigaDOS manual]] to understand and learn everything about AmigaDOS.

== The Graphics library ==

The Graphics library handles every low level graphic operation like designing pixels on the monitor, creating graphic elements (bobs, sprites) and also writing text output.

== Intuition ==

The Intuition library is responsible for every graphical object: windows, screens, gadgets, mouse pointers... It lies between any graphic program and the graphics library.

== The Workbench ==

The Workbench is the graphical place where you will manage your computer and all your files. The name was chosen because the user will use tools to create and work with the computer.

[[File:Wb.png|320px]]

== The Shell ==

While some people prefer to control the operating system using their mouse, others prefer using the keyboard. The shell is a text based window when you can type commands to execute actions in the operating system. In the shell the commands will display the results of their execution.

== ARexx - inter-program communication by scripting ==

The ARexx scripting language can be used to operate the Workbench and other Amiga applications from a script containing ARexx commands. This is extremely useful in performing repetitive tasks or doing what the controlled application was not even designed to do.
After a learning curve, everybody can use ARexx as it is built in the system. The scripts can be executed immediately like any other tool.

= How is my data stored? =
== Files ==
=== Executable files ===
Programs you can start are stored in executable files. They contain binary code directly understandable by the computer. They are files with an executable bit, a flag that shows AmigaOS that such file will do something when started.
An example is a music player. When you start this executable, the player opens and you can start playing music files.

AmigaOS can run two different kinds of executable files: the AmigaOS native programs made for the PowerPC processor and programs created for the Motorola 68k processors. The laters are executed inside an emulation that transcripts them into PowerPC code.

==== Scripts ====

Scripts are text files containing a list of commands. So they are not strictly executables like ''binary code'' files but they can be executed by AmigaOS like if they were.
This is the case with AmigaDOS and ARexx scripts. These files need to have the executable bit, and the script bit.

=== Data files ===
Files that are not executable are data files. These contain some data that will be manipulated by programs. Some examples are a music file, a video file or a text document.

== Directories/Drawers ==
In order to organise things a bit, files are not all of them in the same place. We create directories which like drawers of a cabinet will store different files of the same kind.
Often the name ''directory'' is used when talking about the directory which is stored on a disk. The graphical interface of AmigaOS being called the Workbench, directories are often called ''drawers''.

Note: directories are often called ''folders'' on other systems.

== Disks, partitions and volumes ==
=== Disks ===
Disks are storage medium you can purchase on a computer store. We use them to store our files. They can be internal hard disks, external ones or a USB disk drive.

=== Partitions ===
A disk is often very big and many users prefer to make it more organised. This is done virtually splitting the disk into several smaller parts. This operation is known as creating partitions on a disk.

[[File:Partitions.png|Small part of Media Toolbox showing different partitions on the harddisk]]

On this screenshot you can see one harddisk with many partitions. Each color corresponds to a different filesystem which defines how data is stored. Also you can see a greyed area which is a blank area on the disk i.e. no partition is defined at this position.

=== Volumes ===
A partition is a physical area on a disk. To access it with AmigaOS we could read the physical data off the partition but it's not an easy way. To make it easier AmigaOS uses the concept of volumes. These are virtual representations of a partition. The volumes have a name so AmigaOS and therefore the user can access all files/directories stored on it in a very practical way: just by using its name.

= How to identify files/directories =

== On the Workbench ==

The Workbench being graphical, a lot of things are understandable just by looking at them. That's why icons are often enough to understand what kind of object it represents: a file, a directory, a disk...

In case you have a doubt, just look at the information on an icon. The Workbench will tell you the type of the object. It is displayed next to its name.

== In a shell ==

In a shell the '''list''' command can be used to see if an object is a file or a directory.

[[File:Files-dirs-in-shell.png|The '''list''' command shows a file of 925678 bytes and two directories]]

A file will be displayed with its size, whereas a directory will be displayed with the text '''Dir''' next to it.

Also, as you can see on the screenshot, the list command displays other characteristics on these 3 items: the protection bits and the date they were updated the last time. The command also sums up what it just listed.

= All AmigaOS components =

AmigaOS is made of components that are needed as soon as the system starts or later when the user or the system needs them.

== Kickstart modules ==

These components are the heart of AmigaOS. Their duties is to do graphics, to handle discs or to handle all reads/writes to files. Also one of them is the AmigaOS kernel which is a kind of director handling the work of all other components.
These Kickstart modules are loaded at the beginning of the operating system boot process (read [[UserDoc:How_AmigaOS_Works#AmigaOS_boot_procedure|here]]). You can find all them in the '''Kickstart''' directory in the system volume. Here is a list:

=== Mandatory modules ===

The following modules are required in any AmigaOS system. Without one of these, the system will not start.

* kernel - The kernel works like a conductor in an orchestra. Its job is to make everything works together. It creates processes, handle memory usage, defines the way other components will access peripherals...etc. Note that the AmigaOS kernel is not based on any other kernel. It is a self made kernel that works since 1983.
* loader - this component handles the loading of all other kickstart modules
* battclock.resource.kmod - this module handles reading/writing the battery backed up clock which is used on all computers to keep the date and time
* bootimage - this is the boot picture. It is displayed during the start sequence of AmigaOS
* bootmenu.kmod - this component handles the Early Startup Menu the use can use to define some settings before starting AmigaOS
* con-handler.kmod - it directs the read and write requests to the console window, to a serial AUX: device or any other supported interface
* console.device.kmod - it opens a window and reads/writes text to and from that window
* diskboot.kmod - handles the booting of AmigaOS from a supported disk
* diskboot.config - this is a text file experienced users can modify to change the boot behaviour of AmigaOS
* dos.library.kmod - this module is a collection of functions that any program can use to perform actions on disks, files and directories
* elf.library.kmod - handles the loading of executable programs
* env-handler.kmod - handles the read/writes of environment variables
* FileSystem.resource.kmod - handles the use of the different filesystems
* gadtools.library.kmod - collection of functions used to create all graphic objects like gadgets, sliders, menus...
* gameport.device.kmod - handles the read/writes of game pads and joysticks
* graphics.library.kmod - collection of functions used to draw graphic elements on the monitor
* hunk.library.kmod - set of functions to read a data stream into memory
* input.device.kmod - handles of input events like keyboard events or mouse clicks
* intuition.library.kmod - collection of functions to create and handle all graphic elements (screens, windows, the mouse pointer...)
* layers.library.kmod - set of functions to be used to handle different layers in graphic operations
* keyboard.device.kmod - driver for the keyboard
* keymap.library.kmod - functions to handle different keymaps
* newlib.library.kmod - collection of functions to perform memory operations (allocating memory, copying memory areas... )
* nonvolatile.library.kmod - provides a simple means for an application developer to manage nonvolatile storage
* nvram.resource.kmod - handles the read/writes to the EEPROM chip present on many AmigaOS computers
* PCIGraphics.card - driver that supports the use of different graphic cards
* ram-handler.kmod - functions that handles the '''Ram disk:''' special disk
* ramdrive.device.kmod - device that allows the usage of the ramdrive device '''RAD:''' disk
* ramlib.kmod - loads disk based libraries and devices for exec.library
* rtg.library - library of functions to perform lowlevel graphic operations on graphic cards
* shell.kmod - the AmigaOS command line interface
* strap.kmod - module that handles booting on different disk devices
* timer.device.kmod - driver to give access to timing functions

=== Filesystem support ===

These kickstart modules can be loaded or left aside. If you want to use a particular filesystem on your disk partitions, you need to load the corresponding filesystem module.

* CDFileSystem - handles the CD-ROM disks with data stored in different formats: ISO9660, HFS...
* SmartFilesystem - allows the usage of partitions in SFS0 and SFS2 layouts
* JXFileSystem - allows the usage of partitions in JXFS layout
* FastFileSystem - allows the usage of partitions in FFS and FFS2 layouts
* diskcache.library.kmod - component required by the SmartFileSystem and JXFileSystem modules

=== Hardware drivers ===

==== Graphic cards drivers ====

* 3dfxVoodoo.chip
* 3DLabsPermedia2.chip
* ATIRadeon.chip
* RadeonHD.chip
* siliconmotion502.chip

==== Disk drivers ====

Each of these drivers allow the use of disks connected to a disk controller. These files are named with the name of the controller they support. As an example, the '''sii3114ide.device.kmod''' allows to use disks connected on a '''Silicon Image SiI3114''' controller chip.

* it8212ide.device.kmod
* lsi53c8xx.device.kmod
* sam460sata.device.kmod
* sii3112ide.device.kmod
* sii3512ide.device.kmod
* sii3114ide.device.kmod
* sii0680ide.device.kmod
* sii3132ide.device.kmod

==== USB drivers ====

* hub.usbfd
* usbsys.device
* usbresource.library
* ehci.usbhcd
* ohci.usbhcd
* uhci.usbhcd
* massstorage.usbfd

==== Other drivers ====

* bootkeyboard.usbfd - allows a USB keyboard to be used even before the USB stack is loaded
* bootmouse.usbfd - allows a USB mouse to be used even before the USB stack is loaded
* fpga.resource.kmod - allows to use the FPGA components which are present on some Amiga computers
* i2c.resource.kmod - allows to use the i2c interface present on some Amiga computers
* xena.resource.kmod - provides access to the Xena chip on the AmigaOne X1000

=== Misc modules ===

* petunia.library.kmod - this module contains the Just-In-Time emulator that allows AmigaOS to run programs made for the Motorola 68k processor

== System components ==

[[File:Workbench_directory_listing.png|frame|right|List of directories and files present at the root of any AmigaOS system]]

Beside the kickstart modules, AmigaOS uses many different components that can be loaded only when used. These files are stored in different directories in the system volume.
Here is described a default AmigaOS installation.

* C
This directory contains AmigaDOS '''C'''ommands
* Classes
contains different object elements easy to be used in any program: gadgets, requesters, graphic table, windows...
* Devs
contains definition for '''Dev'''ices
* Emulation
contains files used for the 68k emulation (though E-UAE)
* Fonts
contains various systems fonts
* Internet
contains a dialer to connect to Internet
* Kickstart
contains the kickstart modules
* L
contains hand'''l'''ers and filesystems
* Libs
contains dynamic '''Libr'''airies of functions
* Locale
contains all files used to localise the system (catalogs, keymaps...)
* MUI
contains the needed files for programs that use the MUI third party graphic interface
* [[Prefs]]
contains the preference programs used to customise AmigaOS
* S
contains the '''S'''cripts
* SObjs
contains .so shared object library files
* Storage
contains other optional files
* System
contains some programs used by the system itself (i.e. you don't need to run them yourself) or low-level programs like disk tools
* [[Utilities]]
contains several programs you can use to achieve some tasks on AmigaOS

= Motorola 680x0 Emulators =

For a long time Amigas have had the famous Motorola 680x0 processors as the central unit for execution. Unfortunately the time of the 680x0 series is passing in favor of other architectures. The new era of processors reached the Amiga some time ago, when expansion boards became available for extending the Classic systems with the raw power of a PowerPC processor.

In the old operating system (AmigaOS 3.x) it was not possible to gain the full advantage of the new processors. The system itself and most of the applications required the original Motorola 680x0 processor. There was no 680x0 emulation available for the PowerPCs, so the 680x0 could not be "switched off".

Thus the new processors remained as a powerful, but mostly unused adjunct to the main 680x0 processor. "Native" PowerPC programs were rare, and every time a PowerPC program called the system, a so called "context switch" occurred between the 680x0 and PowerPC code, often causing a large performance penalty.

The new Amiga platform is based on the PowerPC processor family, therefore the new version of the AmigaOS has to smooth the transition from the 680x0 series, which is achieved by emulating the old processor architecture. The operating system itself is written almost 100 percent for the PowerPC processors, but the 680x0 legacy applications require an emulated 680x0 processor.

== Two 680x0 Emulators ==

In version 4.0 of AmigaOS, two different emulators were implemented; one is the successor of BlackBox emulation, it is an interpretive emulator, thus the emulation speed is mediocre. On the other hand it has a very low "reaction time", and is ideal for time critical parts, such as interrupts.

The other is Petunia, the "JIT emulator". A fast, but less compatible way of emulation of the legacy Motorola processors. It is intended mainly for emulating applications, and therefore, when execution of the application leaves the bounds of the application's code segment, emulation falls back to the interpretive method, where it does its job and returns to the JIT emulation again.

Dynamic recompilation (also called just-in-time compilation or simply JIT compilation) is a technique of translating foreign processor machine code to native machine code, "on the fly".

This technique is common nowadays, commonly applied in JAVA virtual machines, and it is also used with success in several emulators. In dynamic recompilation there is the possibility of runtime optimization of the emulated code by collecting statistics of the execution process. Therefore (theoretically) the final executed code can be even faster than the original code on its original processor.

== Features ==

Emulated opcodes:
* all user and supervisor level opcodes of the Motorola 68040
* all FPU opcodes of the Motorola 68881/68882

AmigaOS claims only 68020/68881 compatibility to applications because this is the safest compatibility level, but both emulators are compatible with the machine code up to the level of 68040/060 processors.

At compile time, a low level flag and branch control analysis allows on-the-fly optimizations of compiled code.

== Removing the JIT Emulator ==

Using the dynamic translation requires a lot more memory than the interpretive emulation. The translated code needs to be stored somewhere, not to mention the data collection tables.

If speed is not as important as the memory consumption of the system, then the JIT emulator can be removed, leaving the job to the interpretive emulator.

Thanks to the modular design of AmigaOS kickstart, all you need to do is edit the "Sys:Kickstart/Kicklayout" file, simply put a semicolon (;) at the beginning of the module line of Petunia.library.kmod. After rebooting the system from cold, the JIT emulator will not be reloaded. Make sure that you alter the appropriate configuration in the Kicklayout file, there may be several alternative configurations, with different names like "DefaultJIT", or "DefaultNoJIT".

== Configuring the Emulators ==

Petunia cooperates with a so called "black list". By default Petunia emulates every 680x0 program or library that is loaded by DOS.library/LoadSeg function, but if an executable or library shows incompatibilities with Petunia, then it can be explicitly inhibited from the dynamic recompilation by specifying it in a list file.

If an executable needs to be added to the list, then it can be done by extending the file "DEVS:applications.dos" with the '''Compatibility''' preferences program from the Prefs drawer of the system. Adding a program name to the list and checking it will prevent Petunia from emulating that program, and it will be interpreted instead by the built-in interpreter.

Removing a program from the list or unchecking (thus allowing Petunia to emulate it again) can be done with the same preferences program.

Please note: some programs consist of multiple executables (shared libraries, plugins). If you want to fully disable the translation of such programs, then every part must be added to the list.

For example to disable UnArc fully, you would have to add all files from libs:xad and also xadmaster.library to the list.

= AmigaOS boot procedure =

Basically a computer with AmigaOS does the following when the power button is pushed:

* [[File:Uboot.jpg|200px]]
the BIOS ([[UserDoc:BIOS|Uboot]] or [[UserDoc:BIOS|CFE]]) of the computer initialises the hardware: graphic card, USB ports... At this point, the monitor wakes up and the first information are displayed. This allows to see if hardware is correctly recognised. As an example you can see if a hard drive is correctly connected into the machine and your BIOS is correctly setup to make this drive useable.
* depending on how you setup the BIOS it will look on the harddisk to find the Second Level Booter (SLB). This program is stored on the first sectors of the disk. Whereas the BIOS does not know about AmigaOS disk structure, the SLB will be able to ''understand'' the AmigaOS partitions and files. In other words, it is the link between the BIOS and the rest of the boot procedure. Its goal is also to give you the ability to start several configurations present on the same drive.
* [[File:SLB.png|200px]]
the SLB will analyses all Amiga partitions on the disk it is installed on. It will read each [[UserDoc:kickstart_configuration|system configuration]] it finds on the partitions. It will show all available configurations for the user to select one to load.
The user can define many different kickstart configurations to choose from. Also both AmigaOS and Linux can be selected for boot.
* [[File:Kmods loading.png|200px]]
the SLB loads the kickstart files of the selected configuration and executes the '''Loader''' module
* '''Loader''' executes the kickstart modules (Exec, devices, libraries...)
* AmigaOS becomes alive displaying the AmigaOS boot picture on the monitor
* the AmigaDOS library executes the [[UserDoc:System_Scripts#startup-sequence|startup-sequence]] script found on the system volume
* the Startup-sequence will be executed and all commands it contains are executed. It means that starting from here the boot procedure is easy to follow and understand.
* the Workbench is started

At this point the user can use his/her computer.

= How to make a Bootable USB Memory Stick for AmigaOS 4.1 =

By Julian Margetson ("Spectre660")

Prerequisites:
* USB memory stick of 2 GB or less in size.
* It is best to only have one USB mass storage device connected while you are creating your bootable USB memory stick.
* Plug the USB memory stick into a USB port on your machine.
* Note that the device will be formatted so make sure that you use an empty memory stick or one that does not contain any data that you need or backup the contents before you begin.

Procedure:
# You use Media Toolbox in the System: drawer to prepare the USB stick. On starting Media Toolbox select ''usbdisk.device'' as the device to use.
# Make certain that you have selected usbdisk.device and not any other device.
# Click on "Start"
# You will see the usb mass storage unit connected in a list.
# Make sure that the Unit type displayed for the USB memory stick is "Removable hard disk"
# Select that Unit by clicking on it.
# The first thing that you need to do is to install the RDB onto the USB Memory Stick.
# Click on the "Install" button.
# A window Labeled "RDB/disk geometry editing" comes up.
## Towards the bottom of the window is the "AmigaOne boot code (SLB)" section.
## Select the "Install" button .
## A file requester "Select AmigaOne Boot Code" now comes up with the Drawer choice defaulting to "l:"
## Select file "slb_v2".
## Select Ok.
## You are now returned to the "RDB/disk geometry editing window".
## Select "Ok-accept changes".
# You are now returned to the display showing the attached USB unit.
# Select "Edit partitions and Filesystems". You will now see the Window 'Editing partitions for disk"
# Select "Add partition"
# This defaults to using the whole device as a single partition.
# It is possible to use create more partitions but for this tutorial we will only use one.
# You now need to give the partition a unique name (e.g. USB0 or something that is different from any of the existing partitions on your hard drive). This is done by changing the default DH0 in the "Name" box.
# Now make sure that the Boxes "Automount" and "Bootable" are selected and show the "Tick mark".
# You need to set "Boot priority" to higher than the boot priority of your hard drive boot partition(s). This is done by increasing Boot priority by clicking on the "+" to the right of the "boot priority" box. Normally you can set the boot priority to 2 .
# Next it is time to select the file system to use.
# Select "Select filesystem/edit details".
# The Window "Editing details for partition 'USB0'" ,or whatever partition name you used, comes up.
## Select the file system that you are going to use by selecting the pull down menu under "Filesystem chooser".
## Only filesystems SFS/00 or SFS/02 will work for a bootable device.
## The option that gives the most flexibility at the moment is SFS/00 as a USB stick in this format can be read and written to using another compatible system in the event that you need to make modifications after it is created without a booting AmigaOS 4.1 machine.
## Next select Blocksize from the "Blocksize" pull down menu. 512 is the correct size to use.
## Now Select "Ok-accept changes".
## Your are now returned to the "Edit partitions for disk" window.
## Again select "Ok-accept changes"
# You are now returned to the window showing the USB mass storage unit list.
# Select "Save to disk"
# A requester pops up with the options "Yes, Save." or "No!"
# Select the "Yes, save." option.
# You now close Media Toolbox by clicking on the close icon (X) on the left of the Media Toolbox window.
# This will give you a requester advising that you need to reboot the machine for the changes to take effect. At this point you need to remove the USB memory stick for the machine. If you do not then the Machine will attempt boot from it before it is formatted and the required Kickstart and AmigaOS 4.1 files are copied to it.
# Select "Yes, reboot NOW!".
# Once you have rebooted connect your USB Memory Stick to a USB port.
# A disk icon "USB0:Uninitialized" (or whatever partition name you used) appears on Workbench.
# You now need to format the device.
# To format Select this Icon and go to the Workbench "Icons" menu .
# Select "Format Disk"
# You can give the USB Memory Stick a unique name and select whether you want a Trashcan or not.
# You can use either a full Format or a Quick Format. Full Format may take a few minutes.
# Once formatted the USB Memory Stick is ready for you to copy the required files from you hard drive or AmigaOS Install CD to it in order to boot AmigaOS 4.1 from it.

UserDoc:How AmigaOS Works

2015-05-29T06:11:48Z

Brian Deneen: /* Intuition */ grammar

As already mentioned, AmigaOS was a pioneer in the early days of personal computing in delivering sophistication that contemporary systems could only have dreamt of and pretended to offer. Today, AmigaOS continues to offer a straightforward elegance that seems to be overlooked in the development of other platforms. Thanks to the concepts behind AmigaOS, the system is easy to understand and to use by everyone.

In this page we will explore all these concepts of AmigaOS. Also you will learn here the naming of all parts of the system.

= Introduction =

AmigaOS is made of different components which are either mandatory (i.e., AmigaOS will not work without them) or components the user can choose to use or not. All these components can have one or mutiple interfaces a user or a developer can use to operate with the components and through them to control the operating system.

= The most important components =

== Exec, the AmigaOS kernel ==

Exec is the kernel of AmigaOS. It is the component that pilots all other components. It is responsible for running programs, dealing with computer memory and managing low-level resources that programs may need. In other words, it organises everything to make the operating system run.

It is made of different parts that cannot be moved outside the kernel: the scheduler, the memory pager and the 68k interpretive emulator.

== AmigaDOS: the underlying system ==

The word "DOS" was originally an acronym for "Disk Operating System". Some say it should be "Disk Based Operating System" as it does a lot more than operate a disk and that it was really an operating system based (stored) on disks. Some say it should be "Device Operating System".

The whole AmigaDOS system includes things such as:

* A set of commands that can be used in the Shell window and elsewhere.
* A system for saving data to disk and retrieving it from disk.
* A system for filing data on disks.
* An interface for peripherals such as keyboards, monitors, printers, etc.
* A method of running programs
* A multitasking system for running more than one program at a time.
* etc. etc. etc.

Read the [[AmigaDOS manual]] to understand and learn everything about AmigaDOS.

== The Graphics library ==

The Graphics library handles every low level graphic operation like designing pixels on the monitor, creating graphic elements (bobs, sprites) and also writing text output.

== Intuition ==

The Intuition library is responsible for every graphical object: windows, screens, gadgets, mouse pointers... It lies between any graphic program and the graphics library.

== The Workbench ==

The Workbench is the graphical place where you will manage your computer and all your files. The name was chosen because the user will use tools to create and work with the computer.

[[File:Wb.png|320px]]

== The Shell ==

While some people prefer to control the operating system using their mouse, others prefer using the keyboard. The shell is a text based window when you can type commands to execute actions in the operating system. In the shell the commands will display the results of their execution.

== ARexx - inter-program communication by scripting ==

The ARexx scripting language can be used to operate the Workbench and the most important Amiga applications from a script containing ARexx commands. This is extremely useful to perform repetitive tasks or to do what the controlled application was not even design to do.
After a learning curve, everybody can use ARexx as it is built in the system and the scripts can be executed immediately like any other tool.

= How is my data stored? =
== Files ==
=== Executable files ===
Programs you can start are stored in executable files. They contain binary code directly understandable by the computer. They are files with an executable bit, a flag that shows AmigaOS that such file will do something when started.
An example is a music player. When you start this executable, the player opens and you can start playing music files.

AmigaOS can run two different kinds of executable files: the AmigaOS native programs made for the PowerPC processor and programs created for the Motorola 68k processors. The laters are executed inside an emulation that transcripts them into PowerPC code.

==== Scripts ====

Scripts are text files containing a list of commands. So they are not strictly executables like ''binary code'' files but they can be executed by AmigaOS like if they were.
This is the case with AmigaDOS and ARexx scripts. These files need to have the executable bit, and the script bit.

=== Data files ===
Files that are not executable are data files. These contain some data that will be manipulated by programs. Some examples are a music file, a video file or a text document.

== Directories/Drawers ==
In order to organise things a bit, files are not all of them in the same place. We create directories which like drawers of a cabinet will store different files of the same kind.
Often the name ''directory'' is used when talking about the directory which is stored on a disk. The graphical interface of AmigaOS being called the Workbench, directories are often called ''drawers''.

Note: directories are often called ''folders'' on other systems.

== Disks, partitions and volumes ==
=== Disks ===
Disks are storage medium you can purchase on a computer store. We use them to store our files. They can be internal hard disks, external ones or a USB disk drive.

=== Partitions ===
A disk is often very big and many users prefer to make it more organised. This is done virtually splitting the disk into several smaller parts. This operation is known as creating partitions on a disk.

[[File:Partitions.png|Small part of Media Toolbox showing different partitions on the harddisk]]

On this screenshot you can see one harddisk with many partitions. Each color corresponds to a different filesystem which defines how data is stored. Also you can see a greyed area which is a blank area on the disk i.e. no partition is defined at this position.

=== Volumes ===
A partition is a physical area on a disk. To access it with AmigaOS we could read the physical data off the partition but it's not an easy way. To make it easier AmigaOS uses the concept of volumes. These are virtual representations of a partition. The volumes have a name so AmigaOS and therefore the user can access all files/directories stored on it in a very practical way: just by using its name.

= How to identify files/directories =

== On the Workbench ==

The Workbench being graphical, a lot of things are understandable just by looking at them. That's why icons are often enough to understand what kind of object it represents: a file, a directory, a disk...

In case you have a doubt, just look at the information on an icon. The Workbench will tell you the type of the object. It is displayed next to its name.

== In a shell ==

In a shell the '''list''' command can be used to see if an object is a file or a directory.

[[File:Files-dirs-in-shell.png|The '''list''' command shows a file of 925678 bytes and two directories]]

A file will be displayed with its size, whereas a directory will be displayed with the text '''Dir''' next to it.

Also, as you can see on the screenshot, the list command displays other characteristics on these 3 items: the protection bits and the date they were updated the last time. The command also sums up what it just listed.

= All AmigaOS components =

AmigaOS is made of components that are needed as soon as the system starts or later when the user or the system needs them.

== Kickstart modules ==

These components are the heart of AmigaOS. Their duties is to do graphics, to handle discs or to handle all reads/writes to files. Also one of them is the AmigaOS kernel which is a kind of director handling the work of all other components.
These Kickstart modules are loaded at the beginning of the operating system boot process (read [[UserDoc:How_AmigaOS_Works#AmigaOS_boot_procedure|here]]). You can find all them in the '''Kickstart''' directory in the system volume. Here is a list:

=== Mandatory modules ===

The following modules are required in any AmigaOS system. Without one of these, the system will not start.

* kernel - The kernel works like a conductor in an orchestra. Its job is to make everything works together. It creates processes, handle memory usage, defines the way other components will access peripherals...etc. Note that the AmigaOS kernel is not based on any other kernel. It is a self made kernel that works since 1983.
* loader - this component handles the loading of all other kickstart modules
* battclock.resource.kmod - this module handles reading/writing the battery backed up clock which is used on all computers to keep the date and time
* bootimage - this is the boot picture. It is displayed during the start sequence of AmigaOS
* bootmenu.kmod - this component handles the Early Startup Menu the use can use to define some settings before starting AmigaOS
* con-handler.kmod - it directs the read and write requests to the console window, to a serial AUX: device or any other supported interface
* console.device.kmod - it opens a window and reads/writes text to and from that window
* diskboot.kmod - handles the booting of AmigaOS from a supported disk
* diskboot.config - this is a text file experienced users can modify to change the boot behaviour of AmigaOS
* dos.library.kmod - this module is a collection of functions that any program can use to perform actions on disks, files and directories
* elf.library.kmod - handles the loading of executable programs
* env-handler.kmod - handles the read/writes of environment variables
* FileSystem.resource.kmod - handles the use of the different filesystems
* gadtools.library.kmod - collection of functions used to create all graphic objects like gadgets, sliders, menus...
* gameport.device.kmod - handles the read/writes of game pads and joysticks
* graphics.library.kmod - collection of functions used to draw graphic elements on the monitor
* hunk.library.kmod - set of functions to read a data stream into memory
* input.device.kmod - handles of input events like keyboard events or mouse clicks
* intuition.library.kmod - collection of functions to create and handle all graphic elements (screens, windows, the mouse pointer...)
* layers.library.kmod - set of functions to be used to handle different layers in graphic operations
* keyboard.device.kmod - driver for the keyboard
* keymap.library.kmod - functions to handle different keymaps
* newlib.library.kmod - collection of functions to perform memory operations (allocating memory, copying memory areas... )
* nonvolatile.library.kmod - provides a simple means for an application developer to manage nonvolatile storage
* nvram.resource.kmod - handles the read/writes to the EEPROM chip present on many AmigaOS computers
* PCIGraphics.card - driver that supports the use of different graphic cards
* ram-handler.kmod - functions that handles the '''Ram disk:''' special disk
* ramdrive.device.kmod - device that allows the usage of the ramdrive device '''RAD:''' disk
* ramlib.kmod - loads disk based libraries and devices for exec.library
* rtg.library - library of functions to perform lowlevel graphic operations on graphic cards
* shell.kmod - the AmigaOS command line interface
* strap.kmod - module that handles booting on different disk devices
* timer.device.kmod - driver to give access to timing functions

=== Filesystem support ===

These kickstart modules can be loaded or left aside. If you want to use a particular filesystem on your disk partitions, you need to load the corresponding filesystem module.

* CDFileSystem - handles the CD-ROM disks with data stored in different formats: ISO9660, HFS...
* SmartFilesystem - allows the usage of partitions in SFS0 and SFS2 layouts
* JXFileSystem - allows the usage of partitions in JXFS layout
* FastFileSystem - allows the usage of partitions in FFS and FFS2 layouts
* diskcache.library.kmod - component required by the SmartFileSystem and JXFileSystem modules

=== Hardware drivers ===

==== Graphic cards drivers ====

* 3dfxVoodoo.chip
* 3DLabsPermedia2.chip
* ATIRadeon.chip
* RadeonHD.chip
* siliconmotion502.chip

==== Disk drivers ====

Each of these drivers allow the use of disks connected to a disk controller. These files are named with the name of the controller they support. As an example, the '''sii3114ide.device.kmod''' allows to use disks connected on a '''Silicon Image SiI3114''' controller chip.

* it8212ide.device.kmod
* lsi53c8xx.device.kmod
* sam460sata.device.kmod
* sii3112ide.device.kmod
* sii3512ide.device.kmod
* sii3114ide.device.kmod
* sii0680ide.device.kmod
* sii3132ide.device.kmod

==== USB drivers ====

* hub.usbfd
* usbsys.device
* usbresource.library
* ehci.usbhcd
* ohci.usbhcd
* uhci.usbhcd
* massstorage.usbfd

==== Other drivers ====

* bootkeyboard.usbfd - allows a USB keyboard to be used even before the USB stack is loaded
* bootmouse.usbfd - allows a USB mouse to be used even before the USB stack is loaded
* fpga.resource.kmod - allows to use the FPGA components which are present on some Amiga computers
* i2c.resource.kmod - allows to use the i2c interface present on some Amiga computers
* xena.resource.kmod - provides access to the Xena chip on the AmigaOne X1000

=== Misc modules ===

* petunia.library.kmod - this module contains the Just-In-Time emulator that allows AmigaOS to run programs made for the Motorola 68k processor

== System components ==

[[File:Workbench_directory_listing.png|frame|right|List of directories and files present at the root of any AmigaOS system]]

Beside the kickstart modules, AmigaOS uses many different components that can be loaded only when used. These files are stored in different directories in the system volume.
Here is described a default AmigaOS installation.

* C
This directory contains AmigaDOS '''C'''ommands
* Classes
contains different object elements easy to be used in any program: gadgets, requesters, graphic table, windows...
* Devs
contains definition for '''Dev'''ices
* Emulation
contains files used for the 68k emulation (though E-UAE)
* Fonts
contains various systems fonts
* Internet
contains a dialer to connect to Internet
* Kickstart
contains the kickstart modules
* L
contains hand'''l'''ers and filesystems
* Libs
contains dynamic '''Libr'''airies of functions
* Locale
contains all files used to localise the system (catalogs, keymaps...)
* MUI
contains the needed files for programs that use the MUI third party graphic interface
* [[Prefs]]
contains the preference programs used to customise AmigaOS
* S
contains the '''S'''cripts
* SObjs
contains .so shared object library files
* Storage
contains other optional files
* System
contains some programs used by the system itself (i.e. you don't need to run them yourself) or low-level programs like disk tools
* [[Utilities]]
contains several programs you can use to achieve some tasks on AmigaOS

= Motorola 680x0 Emulators =

For a long time Amigas have had the famous Motorola 680x0 processors as the central unit for execution. Unfortunately the time of the 680x0 series is passing in favor of other architectures. The new era of processors reached the Amiga some time ago, when expansion boards became available for extending the Classic systems with the raw power of a PowerPC processor.

In the old operating system (AmigaOS 3.x) it was not possible to gain the full advantage of the new processors. The system itself and most of the applications required the original Motorola 680x0 processor. There was no 680x0 emulation available for the PowerPCs, so the 680x0 could not be "switched off".

Thus the new processors remained as a powerful, but mostly unused adjunct to the main 680x0 processor. "Native" PowerPC programs were rare, and every time a PowerPC program called the system, a so called "context switch" occurred between the 680x0 and PowerPC code, often causing a large performance penalty.

The new Amiga platform is based on the PowerPC processor family, therefore the new version of the AmigaOS has to smooth the transition from the 680x0 series, which is achieved by emulating the old processor architecture. The operating system itself is written almost 100 percent for the PowerPC processors, but the 680x0 legacy applications require an emulated 680x0 processor.

== Two 680x0 Emulators ==

In version 4.0 of AmigaOS, two different emulators were implemented; one is the successor of BlackBox emulation, it is an interpretive emulator, thus the emulation speed is mediocre. On the other hand it has a very low "reaction time", and is ideal for time critical parts, such as interrupts.

The other is Petunia, the "JIT emulator". A fast, but less compatible way of emulation of the legacy Motorola processors. It is intended mainly for emulating applications, and therefore, when execution of the application leaves the bounds of the application's code segment, emulation falls back to the interpretive method, where it does its job and returns to the JIT emulation again.

Dynamic recompilation (also called just-in-time compilation or simply JIT compilation) is a technique of translating foreign processor machine code to native machine code, "on the fly".

This technique is common nowadays, commonly applied in JAVA virtual machines, and it is also used with success in several emulators. In dynamic recompilation there is the possibility of runtime optimization of the emulated code by collecting statistics of the execution process. Therefore (theoretically) the final executed code can be even faster than the original code on its original processor.

== Features ==

Emulated opcodes:
* all user and supervisor level opcodes of the Motorola 68040
* all FPU opcodes of the Motorola 68881/68882

AmigaOS claims only 68020/68881 compatibility to applications because this is the safest compatibility level, but both emulators are compatible with the machine code up to the level of 68040/060 processors.

At compile time, a low level flag and branch control analysis allows on-the-fly optimizations of compiled code.

== Removing the JIT Emulator ==

Using the dynamic translation requires a lot more memory than the interpretive emulation. The translated code needs to be stored somewhere, not to mention the data collection tables.

If speed is not as important as the memory consumption of the system, then the JIT emulator can be removed, leaving the job to the interpretive emulator.

Thanks to the modular design of AmigaOS kickstart, all you need to do is edit the "Sys:Kickstart/Kicklayout" file, simply put a semicolon (;) at the beginning of the module line of Petunia.library.kmod. After rebooting the system from cold, the JIT emulator will not be reloaded. Make sure that you alter the appropriate configuration in the Kicklayout file, there may be several alternative configurations, with different names like "DefaultJIT", or "DefaultNoJIT".

== Configuring the Emulators ==

Petunia cooperates with a so called "black list". By default Petunia emulates every 680x0 program or library that is loaded by DOS.library/LoadSeg function, but if an executable or library shows incompatibilities with Petunia, then it can be explicitly inhibited from the dynamic recompilation by specifying it in a list file.

If an executable needs to be added to the list, then it can be done by extending the file "DEVS:applications.dos" with the '''Compatibility''' preferences program from the Prefs drawer of the system. Adding a program name to the list and checking it will prevent Petunia from emulating that program, and it will be interpreted instead by the built-in interpreter.

Removing a program from the list or unchecking (thus allowing Petunia to emulate it again) can be done with the same preferences program.

Please note: some programs consist of multiple executables (shared libraries, plugins). If you want to fully disable the translation of such programs, then every part must be added to the list.

For example to disable UnArc fully, you would have to add all files from libs:xad and also xadmaster.library to the list.

= AmigaOS boot procedure =

Basically a computer with AmigaOS does the following when the power button is pushed:

* [[File:Uboot.jpg|200px]]
the BIOS ([[UserDoc:BIOS|Uboot]] or [[UserDoc:BIOS|CFE]]) of the computer initialises the hardware: graphic card, USB ports... At this point, the monitor wakes up and the first information are displayed. This allows to see if hardware is correctly recognised. As an example you can see if a hard drive is correctly connected into the machine and your BIOS is correctly setup to make this drive useable.
* depending on how you setup the BIOS it will look on the harddisk to find the Second Level Booter (SLB). This program is stored on the first sectors of the disk. Whereas the BIOS does not know about AmigaOS disk structure, the SLB will be able to ''understand'' the AmigaOS partitions and files. In other words, it is the link between the BIOS and the rest of the boot procedure. Its goal is also to give you the ability to start several configurations present on the same drive.
* [[File:SLB.png|200px]]
the SLB will analyses all Amiga partitions on the disk it is installed on. It will read each [[UserDoc:kickstart_configuration|system configuration]] it finds on the partitions. It will show all available configurations for the user to select one to load.
The user can define many different kickstart configurations to choose from. Also both AmigaOS and Linux can be selected for boot.
* [[File:Kmods loading.png|200px]]
the SLB loads the kickstart files of the selected configuration and executes the '''Loader''' module
* '''Loader''' executes the kickstart modules (Exec, devices, libraries...)
* AmigaOS becomes alive displaying the AmigaOS boot picture on the monitor
* the AmigaDOS library executes the [[UserDoc:System_Scripts#startup-sequence|startup-sequence]] script found on the system volume
* the Startup-sequence will be executed and all commands it contains are executed. It means that starting from here the boot procedure is easy to follow and understand.
* the Workbench is started

At this point the user can use his/her computer.

= How to make a Bootable USB Memory Stick for AmigaOS 4.1 =

By Julian Margetson ("Spectre660")

Prerequisites:
* USB memory stick of 2 GB or less in size.
* It is best to only have one USB mass storage device connected while you are creating your bootable USB memory stick.
* Plug the USB memory stick into a USB port on your machine.
* Note that the device will be formatted so make sure that you use an empty memory stick or one that does not contain any data that you need or backup the contents before you begin.

Procedure:
# You use Media Toolbox in the System: drawer to prepare the USB stick. On starting Media Toolbox select ''usbdisk.device'' as the device to use.
# Make certain that you have selected usbdisk.device and not any other device.
# Click on "Start"
# You will see the usb mass storage unit connected in a list.
# Make sure that the Unit type displayed for the USB memory stick is "Removable hard disk"
# Select that Unit by clicking on it.
# The first thing that you need to do is to install the RDB onto the USB Memory Stick.
# Click on the "Install" button.
# A window Labeled "RDB/disk geometry editing" comes up.
## Towards the bottom of the window is the "AmigaOne boot code (SLB)" section.
## Select the "Install" button .
## A file requester "Select AmigaOne Boot Code" now comes up with the Drawer choice defaulting to "l:"
## Select file "slb_v2".
## Select Ok.
## You are now returned to the "RDB/disk geometry editing window".
## Select "Ok-accept changes".
# You are now returned to the display showing the attached USB unit.
# Select "Edit partitions and Filesystems". You will now see the Window 'Editing partitions for disk"
# Select "Add partition"
# This defaults to using the whole device as a single partition.
# It is possible to use create more partitions but for this tutorial we will only use one.
# You now need to give the partition a unique name (e.g. USB0 or something that is different from any of the existing partitions on your hard drive). This is done by changing the default DH0 in the "Name" box.
# Now make sure that the Boxes "Automount" and "Bootable" are selected and show the "Tick mark".
# You need to set "Boot priority" to higher than the boot priority of your hard drive boot partition(s). This is done by increasing Boot priority by clicking on the "+" to the right of the "boot priority" box. Normally you can set the boot priority to 2 .
# Next it is time to select the file system to use.
# Select "Select filesystem/edit details".
# The Window "Editing details for partition 'USB0'" ,or whatever partition name you used, comes up.
## Select the file system that you are going to use by selecting the pull down menu under "Filesystem chooser".
## Only filesystems SFS/00 or SFS/02 will work for a bootable device.
## The option that gives the most flexibility at the moment is SFS/00 as a USB stick in this format can be read and written to using another compatible system in the event that you need to make modifications after it is created without a booting AmigaOS 4.1 machine.
## Next select Blocksize from the "Blocksize" pull down menu. 512 is the correct size to use.
## Now Select "Ok-accept changes".
## Your are now returned to the "Edit partitions for disk" window.
## Again select "Ok-accept changes"
# You are now returned to the window showing the USB mass storage unit list.
# Select "Save to disk"
# A requester pops up with the options "Yes, Save." or "No!"
# Select the "Yes, save." option.
# You now close Media Toolbox by clicking on the close icon (X) on the left of the Media Toolbox window.
# This will give you a requester advising that you need to reboot the machine for the changes to take effect. At this point you need to remove the USB memory stick for the machine. If you do not then the Machine will attempt boot from it before it is formatted and the required Kickstart and AmigaOS 4.1 files are copied to it.
# Select "Yes, reboot NOW!".
# Once you have rebooted connect your USB Memory Stick to a USB port.
# A disk icon "USB0:Uninitialized" (or whatever partition name you used) appears on Workbench.
# You now need to format the device.
# To format Select this Icon and go to the Workbench "Icons" menu .
# Select "Format Disk"
# You can give the USB Memory Stick a unique name and select whether you want a Trashcan or not.
# You can use either a full Format or a Quick Format. Full Format may take a few minutes.
# Once formatted the USB Memory Stick is ready for you to copy the required files from you hard drive or AmigaOS Install CD to it in order to boot AmigaOS 4.1 from it.

UserDoc:How AmigaOS Works

2015-05-29T06:10:51Z

Brian Deneen: /* The Graphics library */ corrected word case

As already mentioned, AmigaOS was a pioneer in the early days of personal computing in delivering sophistication that contemporary systems could only have dreamt of and pretended to offer. Today, AmigaOS continues to offer a straightforward elegance that seems to be overlooked in the development of other platforms. Thanks to the concepts behind AmigaOS, the system is easy to understand and to use by everyone.

In this page we will explore all these concepts of AmigaOS. Also you will learn here the naming of all parts of the system.

= Introduction =

AmigaOS is made of different components which are either mandatory (i.e., AmigaOS will not work without them) or components the user can choose to use or not. All these components can have one or mutiple interfaces a user or a developer can use to operate with the components and through them to control the operating system.

= The most important components =

== Exec, the AmigaOS kernel ==

Exec is the kernel of AmigaOS. It is the component that pilots all other components. It is responsible for running programs, dealing with computer memory and managing low-level resources that programs may need. In other words, it organises everything to make the operating system run.

It is made of different parts that cannot be moved outside the kernel: the scheduler, the memory pager and the 68k interpretive emulator.

== AmigaDOS: the underlying system ==

The word "DOS" was originally an acronym for "Disk Operating System". Some say it should be "Disk Based Operating System" as it does a lot more than operate a disk and that it was really an operating system based (stored) on disks. Some say it should be "Device Operating System".

The whole AmigaDOS system includes things such as:

* A set of commands that can be used in the Shell window and elsewhere.
* A system for saving data to disk and retrieving it from disk.
* A system for filing data on disks.
* An interface for peripherals such as keyboards, monitors, printers, etc.
* A method of running programs
* A multitasking system for running more than one program at a time.
* etc. etc. etc.

Read the [[AmigaDOS manual]] to understand and learn everything about AmigaDOS.

== The Graphics library ==

The Graphics library handles every low level graphic operation like designing pixels on the monitor, creating graphic elements (bobs, sprites) and also writing text output.

== Intuition ==

The Intuition library is responsible for every graphical objects: windows, screens, gadgets, mouse pointers... It lays between any graphic program and the graphics library.

== The Workbench ==

The Workbench is the graphical place where you will manage your computer and all your files. The name was chosen because the user will use tools to create and work with the computer.

[[File:Wb.png|320px]]

== The Shell ==

While some people prefer to control the operating system using their mouse, others prefer using the keyboard. The shell is a text based window when you can type commands to execute actions in the operating system. In the shell the commands will display the results of their execution.

== ARexx - inter-program communication by scripting ==

The ARexx scripting language can be used to operate the Workbench and the most important Amiga applications from a script containing ARexx commands. This is extremely useful to perform repetitive tasks or to do what the controlled application was not even design to do.
After a learning curve, everybody can use ARexx as it is built in the system and the scripts can be executed immediately like any other tool.

= How is my data stored? =
== Files ==
=== Executable files ===
Programs you can start are stored in executable files. They contain binary code directly understandable by the computer. They are files with an executable bit, a flag that shows AmigaOS that such file will do something when started.
An example is a music player. When you start this executable, the player opens and you can start playing music files.

AmigaOS can run two different kinds of executable files: the AmigaOS native programs made for the PowerPC processor and programs created for the Motorola 68k processors. The laters are executed inside an emulation that transcripts them into PowerPC code.

==== Scripts ====

Scripts are text files containing a list of commands. So they are not strictly executables like ''binary code'' files but they can be executed by AmigaOS like if they were.
This is the case with AmigaDOS and ARexx scripts. These files need to have the executable bit, and the script bit.

=== Data files ===
Files that are not executable are data files. These contain some data that will be manipulated by programs. Some examples are a music file, a video file or a text document.

== Directories/Drawers ==
In order to organise things a bit, files are not all of them in the same place. We create directories which like drawers of a cabinet will store different files of the same kind.
Often the name ''directory'' is used when talking about the directory which is stored on a disk. The graphical interface of AmigaOS being called the Workbench, directories are often called ''drawers''.

Note: directories are often called ''folders'' on other systems.

== Disks, partitions and volumes ==
=== Disks ===
Disks are storage medium you can purchase on a computer store. We use them to store our files. They can be internal hard disks, external ones or a USB disk drive.

=== Partitions ===
A disk is often very big and many users prefer to make it more organised. This is done virtually splitting the disk into several smaller parts. This operation is known as creating partitions on a disk.

[[File:Partitions.png|Small part of Media Toolbox showing different partitions on the harddisk]]

On this screenshot you can see one harddisk with many partitions. Each color corresponds to a different filesystem which defines how data is stored. Also you can see a greyed area which is a blank area on the disk i.e. no partition is defined at this position.

=== Volumes ===
A partition is a physical area on a disk. To access it with AmigaOS we could read the physical data off the partition but it's not an easy way. To make it easier AmigaOS uses the concept of volumes. These are virtual representations of a partition. The volumes have a name so AmigaOS and therefore the user can access all files/directories stored on it in a very practical way: just by using its name.

= How to identify files/directories =

== On the Workbench ==

The Workbench being graphical, a lot of things are understandable just by looking at them. That's why icons are often enough to understand what kind of object it represents: a file, a directory, a disk...

In case you have a doubt, just look at the information on an icon. The Workbench will tell you the type of the object. It is displayed next to its name.

== In a shell ==

In a shell the '''list''' command can be used to see if an object is a file or a directory.

[[File:Files-dirs-in-shell.png|The '''list''' command shows a file of 925678 bytes and two directories]]

A file will be displayed with its size, whereas a directory will be displayed with the text '''Dir''' next to it.

Also, as you can see on the screenshot, the list command displays other characteristics on these 3 items: the protection bits and the date they were updated the last time. The command also sums up what it just listed.

= All AmigaOS components =

AmigaOS is made of components that are needed as soon as the system starts or later when the user or the system needs them.

== Kickstart modules ==

These components are the heart of AmigaOS. Their duties is to do graphics, to handle discs or to handle all reads/writes to files. Also one of them is the AmigaOS kernel which is a kind of director handling the work of all other components.
These Kickstart modules are loaded at the beginning of the operating system boot process (read [[UserDoc:How_AmigaOS_Works#AmigaOS_boot_procedure|here]]). You can find all them in the '''Kickstart''' directory in the system volume. Here is a list:

=== Mandatory modules ===

The following modules are required in any AmigaOS system. Without one of these, the system will not start.

* kernel - The kernel works like a conductor in an orchestra. Its job is to make everything works together. It creates processes, handle memory usage, defines the way other components will access peripherals...etc. Note that the AmigaOS kernel is not based on any other kernel. It is a self made kernel that works since 1983.
* loader - this component handles the loading of all other kickstart modules
* battclock.resource.kmod - this module handles reading/writing the battery backed up clock which is used on all computers to keep the date and time
* bootimage - this is the boot picture. It is displayed during the start sequence of AmigaOS
* bootmenu.kmod - this component handles the Early Startup Menu the use can use to define some settings before starting AmigaOS
* con-handler.kmod - it directs the read and write requests to the console window, to a serial AUX: device or any other supported interface
* console.device.kmod - it opens a window and reads/writes text to and from that window
* diskboot.kmod - handles the booting of AmigaOS from a supported disk
* diskboot.config - this is a text file experienced users can modify to change the boot behaviour of AmigaOS
* dos.library.kmod - this module is a collection of functions that any program can use to perform actions on disks, files and directories
* elf.library.kmod - handles the loading of executable programs
* env-handler.kmod - handles the read/writes of environment variables
* FileSystem.resource.kmod - handles the use of the different filesystems
* gadtools.library.kmod - collection of functions used to create all graphic objects like gadgets, sliders, menus...
* gameport.device.kmod - handles the read/writes of game pads and joysticks
* graphics.library.kmod - collection of functions used to draw graphic elements on the monitor
* hunk.library.kmod - set of functions to read a data stream into memory
* input.device.kmod - handles of input events like keyboard events or mouse clicks
* intuition.library.kmod - collection of functions to create and handle all graphic elements (screens, windows, the mouse pointer...)
* layers.library.kmod - set of functions to be used to handle different layers in graphic operations
* keyboard.device.kmod - driver for the keyboard
* keymap.library.kmod - functions to handle different keymaps
* newlib.library.kmod - collection of functions to perform memory operations (allocating memory, copying memory areas... )
* nonvolatile.library.kmod - provides a simple means for an application developer to manage nonvolatile storage
* nvram.resource.kmod - handles the read/writes to the EEPROM chip present on many AmigaOS computers
* PCIGraphics.card - driver that supports the use of different graphic cards
* ram-handler.kmod - functions that handles the '''Ram disk:''' special disk
* ramdrive.device.kmod - device that allows the usage of the ramdrive device '''RAD:''' disk
* ramlib.kmod - loads disk based libraries and devices for exec.library
* rtg.library - library of functions to perform lowlevel graphic operations on graphic cards
* shell.kmod - the AmigaOS command line interface
* strap.kmod - module that handles booting on different disk devices
* timer.device.kmod - driver to give access to timing functions

=== Filesystem support ===

These kickstart modules can be loaded or left aside. If you want to use a particular filesystem on your disk partitions, you need to load the corresponding filesystem module.

* CDFileSystem - handles the CD-ROM disks with data stored in different formats: ISO9660, HFS...
* SmartFilesystem - allows the usage of partitions in SFS0 and SFS2 layouts
* JXFileSystem - allows the usage of partitions in JXFS layout
* FastFileSystem - allows the usage of partitions in FFS and FFS2 layouts
* diskcache.library.kmod - component required by the SmartFileSystem and JXFileSystem modules

=== Hardware drivers ===

==== Graphic cards drivers ====

* 3dfxVoodoo.chip
* 3DLabsPermedia2.chip
* ATIRadeon.chip
* RadeonHD.chip
* siliconmotion502.chip

==== Disk drivers ====

Each of these drivers allow the use of disks connected to a disk controller. These files are named with the name of the controller they support. As an example, the '''sii3114ide.device.kmod''' allows to use disks connected on a '''Silicon Image SiI3114''' controller chip.

* it8212ide.device.kmod
* lsi53c8xx.device.kmod
* sam460sata.device.kmod
* sii3112ide.device.kmod
* sii3512ide.device.kmod
* sii3114ide.device.kmod
* sii0680ide.device.kmod
* sii3132ide.device.kmod

==== USB drivers ====

* hub.usbfd
* usbsys.device
* usbresource.library
* ehci.usbhcd
* ohci.usbhcd
* uhci.usbhcd
* massstorage.usbfd

==== Other drivers ====

* bootkeyboard.usbfd - allows a USB keyboard to be used even before the USB stack is loaded
* bootmouse.usbfd - allows a USB mouse to be used even before the USB stack is loaded
* fpga.resource.kmod - allows to use the FPGA components which are present on some Amiga computers
* i2c.resource.kmod - allows to use the i2c interface present on some Amiga computers
* xena.resource.kmod - provides access to the Xena chip on the AmigaOne X1000

=== Misc modules ===

* petunia.library.kmod - this module contains the Just-In-Time emulator that allows AmigaOS to run programs made for the Motorola 68k processor

== System components ==

[[File:Workbench_directory_listing.png|frame|right|List of directories and files present at the root of any AmigaOS system]]

Beside the kickstart modules, AmigaOS uses many different components that can be loaded only when used. These files are stored in different directories in the system volume.
Here is described a default AmigaOS installation.

* C
This directory contains AmigaDOS '''C'''ommands
* Classes
contains different object elements easy to be used in any program: gadgets, requesters, graphic table, windows...
* Devs
contains definition for '''Dev'''ices
* Emulation
contains files used for the 68k emulation (though E-UAE)
* Fonts
contains various systems fonts
* Internet
contains a dialer to connect to Internet
* Kickstart
contains the kickstart modules
* L
contains hand'''l'''ers and filesystems
* Libs
contains dynamic '''Libr'''airies of functions
* Locale
contains all files used to localise the system (catalogs, keymaps...)
* MUI
contains the needed files for programs that use the MUI third party graphic interface
* [[Prefs]]
contains the preference programs used to customise AmigaOS
* S
contains the '''S'''cripts
* SObjs
contains .so shared object library files
* Storage
contains other optional files
* System
contains some programs used by the system itself (i.e. you don't need to run them yourself) or low-level programs like disk tools
* [[Utilities]]
contains several programs you can use to achieve some tasks on AmigaOS

= Motorola 680x0 Emulators =

For a long time Amigas have had the famous Motorola 680x0 processors as the central unit for execution. Unfortunately the time of the 680x0 series is passing in favor of other architectures. The new era of processors reached the Amiga some time ago, when expansion boards became available for extending the Classic systems with the raw power of a PowerPC processor.

In the old operating system (AmigaOS 3.x) it was not possible to gain the full advantage of the new processors. The system itself and most of the applications required the original Motorola 680x0 processor. There was no 680x0 emulation available for the PowerPCs, so the 680x0 could not be "switched off".

Thus the new processors remained as a powerful, but mostly unused adjunct to the main 680x0 processor. "Native" PowerPC programs were rare, and every time a PowerPC program called the system, a so called "context switch" occurred between the 680x0 and PowerPC code, often causing a large performance penalty.

The new Amiga platform is based on the PowerPC processor family, therefore the new version of the AmigaOS has to smooth the transition from the 680x0 series, which is achieved by emulating the old processor architecture. The operating system itself is written almost 100 percent for the PowerPC processors, but the 680x0 legacy applications require an emulated 680x0 processor.

== Two 680x0 Emulators ==

In version 4.0 of AmigaOS, two different emulators were implemented; one is the successor of BlackBox emulation, it is an interpretive emulator, thus the emulation speed is mediocre. On the other hand it has a very low "reaction time", and is ideal for time critical parts, such as interrupts.

The other is Petunia, the "JIT emulator". A fast, but less compatible way of emulation of the legacy Motorola processors. It is intended mainly for emulating applications, and therefore, when execution of the application leaves the bounds of the application's code segment, emulation falls back to the interpretive method, where it does its job and returns to the JIT emulation again.

Dynamic recompilation (also called just-in-time compilation or simply JIT compilation) is a technique of translating foreign processor machine code to native machine code, "on the fly".

This technique is common nowadays, commonly applied in JAVA virtual machines, and it is also used with success in several emulators. In dynamic recompilation there is the possibility of runtime optimization of the emulated code by collecting statistics of the execution process. Therefore (theoretically) the final executed code can be even faster than the original code on its original processor.

== Features ==

Emulated opcodes:
* all user and supervisor level opcodes of the Motorola 68040
* all FPU opcodes of the Motorola 68881/68882

AmigaOS claims only 68020/68881 compatibility to applications because this is the safest compatibility level, but both emulators are compatible with the machine code up to the level of 68040/060 processors.

At compile time, a low level flag and branch control analysis allows on-the-fly optimizations of compiled code.

== Removing the JIT Emulator ==

Using the dynamic translation requires a lot more memory than the interpretive emulation. The translated code needs to be stored somewhere, not to mention the data collection tables.

If speed is not as important as the memory consumption of the system, then the JIT emulator can be removed, leaving the job to the interpretive emulator.

Thanks to the modular design of AmigaOS kickstart, all you need to do is edit the "Sys:Kickstart/Kicklayout" file, simply put a semicolon (;) at the beginning of the module line of Petunia.library.kmod. After rebooting the system from cold, the JIT emulator will not be reloaded. Make sure that you alter the appropriate configuration in the Kicklayout file, there may be several alternative configurations, with different names like "DefaultJIT", or "DefaultNoJIT".

== Configuring the Emulators ==

Petunia cooperates with a so called "black list". By default Petunia emulates every 680x0 program or library that is loaded by DOS.library/LoadSeg function, but if an executable or library shows incompatibilities with Petunia, then it can be explicitly inhibited from the dynamic recompilation by specifying it in a list file.

If an executable needs to be added to the list, then it can be done by extending the file "DEVS:applications.dos" with the '''Compatibility''' preferences program from the Prefs drawer of the system. Adding a program name to the list and checking it will prevent Petunia from emulating that program, and it will be interpreted instead by the built-in interpreter.

Removing a program from the list or unchecking (thus allowing Petunia to emulate it again) can be done with the same preferences program.

Please note: some programs consist of multiple executables (shared libraries, plugins). If you want to fully disable the translation of such programs, then every part must be added to the list.

For example to disable UnArc fully, you would have to add all files from libs:xad and also xadmaster.library to the list.

= AmigaOS boot procedure =

Basically a computer with AmigaOS does the following when the power button is pushed:

* [[File:Uboot.jpg|200px]]
the BIOS ([[UserDoc:BIOS|Uboot]] or [[UserDoc:BIOS|CFE]]) of the computer initialises the hardware: graphic card, USB ports... At this point, the monitor wakes up and the first information are displayed. This allows to see if hardware is correctly recognised. As an example you can see if a hard drive is correctly connected into the machine and your BIOS is correctly setup to make this drive useable.
* depending on how you setup the BIOS it will look on the harddisk to find the Second Level Booter (SLB). This program is stored on the first sectors of the disk. Whereas the BIOS does not know about AmigaOS disk structure, the SLB will be able to ''understand'' the AmigaOS partitions and files. In other words, it is the link between the BIOS and the rest of the boot procedure. Its goal is also to give you the ability to start several configurations present on the same drive.
* [[File:SLB.png|200px]]
the SLB will analyses all Amiga partitions on the disk it is installed on. It will read each [[UserDoc:kickstart_configuration|system configuration]] it finds on the partitions. It will show all available configurations for the user to select one to load.
The user can define many different kickstart configurations to choose from. Also both AmigaOS and Linux can be selected for boot.
* [[File:Kmods loading.png|200px]]
the SLB loads the kickstart files of the selected configuration and executes the '''Loader''' module
* '''Loader''' executes the kickstart modules (Exec, devices, libraries...)
* AmigaOS becomes alive displaying the AmigaOS boot picture on the monitor
* the AmigaDOS library executes the [[UserDoc:System_Scripts#startup-sequence|startup-sequence]] script found on the system volume
* the Startup-sequence will be executed and all commands it contains are executed. It means that starting from here the boot procedure is easy to follow and understand.
* the Workbench is started

At this point the user can use his/her computer.

= How to make a Bootable USB Memory Stick for AmigaOS 4.1 =

By Julian Margetson ("Spectre660")

Prerequisites:
* USB memory stick of 2 GB or less in size.
* It is best to only have one USB mass storage device connected while you are creating your bootable USB memory stick.
* Plug the USB memory stick into a USB port on your machine.
* Note that the device will be formatted so make sure that you use an empty memory stick or one that does not contain any data that you need or backup the contents before you begin.

Procedure:
# You use Media Toolbox in the System: drawer to prepare the USB stick. On starting Media Toolbox select ''usbdisk.device'' as the device to use.
# Make certain that you have selected usbdisk.device and not any other device.
# Click on "Start"
# You will see the usb mass storage unit connected in a list.
# Make sure that the Unit type displayed for the USB memory stick is "Removable hard disk"
# Select that Unit by clicking on it.
# The first thing that you need to do is to install the RDB onto the USB Memory Stick.
# Click on the "Install" button.
# A window Labeled "RDB/disk geometry editing" comes up.
## Towards the bottom of the window is the "AmigaOne boot code (SLB)" section.
## Select the "Install" button .
## A file requester "Select AmigaOne Boot Code" now comes up with the Drawer choice defaulting to "l:"
## Select file "slb_v2".
## Select Ok.
## You are now returned to the "RDB/disk geometry editing window".
## Select "Ok-accept changes".
# You are now returned to the display showing the attached USB unit.
# Select "Edit partitions and Filesystems". You will now see the Window 'Editing partitions for disk"
# Select "Add partition"
# This defaults to using the whole device as a single partition.
# It is possible to use create more partitions but for this tutorial we will only use one.
# You now need to give the partition a unique name (e.g. USB0 or something that is different from any of the existing partitions on your hard drive). This is done by changing the default DH0 in the "Name" box.
# Now make sure that the Boxes "Automount" and "Bootable" are selected and show the "Tick mark".
# You need to set "Boot priority" to higher than the boot priority of your hard drive boot partition(s). This is done by increasing Boot priority by clicking on the "+" to the right of the "boot priority" box. Normally you can set the boot priority to 2 .
# Next it is time to select the file system to use.
# Select "Select filesystem/edit details".
# The Window "Editing details for partition 'USB0'" ,or whatever partition name you used, comes up.
## Select the file system that you are going to use by selecting the pull down menu under "Filesystem chooser".
## Only filesystems SFS/00 or SFS/02 will work for a bootable device.
## The option that gives the most flexibility at the moment is SFS/00 as a USB stick in this format can be read and written to using another compatible system in the event that you need to make modifications after it is created without a booting AmigaOS 4.1 machine.
## Next select Blocksize from the "Blocksize" pull down menu. 512 is the correct size to use.
## Now Select "Ok-accept changes".
## Your are now returned to the "Edit partitions for disk" window.
## Again select "Ok-accept changes"
# You are now returned to the window showing the USB mass storage unit list.
# Select "Save to disk"
# A requester pops up with the options "Yes, Save." or "No!"
# Select the "Yes, save." option.
# You now close Media Toolbox by clicking on the close icon (X) on the left of the Media Toolbox window.
# This will give you a requester advising that you need to reboot the machine for the changes to take effect. At this point you need to remove the USB memory stick for the machine. If you do not then the Machine will attempt boot from it before it is formatted and the required Kickstart and AmigaOS 4.1 files are copied to it.
# Select "Yes, reboot NOW!".
# Once you have rebooted connect your USB Memory Stick to a USB port.
# A disk icon "USB0:Uninitialized" (or whatever partition name you used) appears on Workbench.
# You now need to format the device.
# To format Select this Icon and go to the Workbench "Icons" menu .
# Select "Format Disk"
# You can give the USB Memory Stick a unique name and select whether you want a Trashcan or not.
# You can use either a full Format or a Quick Format. Full Format may take a few minutes.
# Once formatted the USB Memory Stick is ready for you to copy the required files from you hard drive or AmigaOS Install CD to it in order to boot AmigaOS 4.1 from it.

UserDoc:How AmigaOS Works

2015-05-29T06:08:52Z

Brian Deneen: /* Exec, the AmigaOS kernel */ added punctuation

As already mentioned, AmigaOS was a pioneer in the early days of personal computing in delivering sophistication that contemporary systems could only have dreamt of and pretended to offer. Today, AmigaOS continues to offer a straightforward elegance that seems to be overlooked in the development of other platforms. Thanks to the concepts behind AmigaOS, the system is easy to understand and to use by everyone.

In this page we will explore all these concepts of AmigaOS. Also you will learn here the naming of all parts of the system.

= Introduction =

AmigaOS is made of different components which are either mandatory (i.e., AmigaOS will not work without them) or components the user can choose to use or not. All these components can have one or mutiple interfaces a user or a developer can use to operate with the components and through them to control the operating system.

= The most important components =

== Exec, the AmigaOS kernel ==

Exec is the kernel of AmigaOS. It is the component that pilots all other components. It is responsible for running programs, dealing with computer memory and managing low-level resources that programs may need. In other words, it organises everything to make the operating system run.

It is made of different parts that cannot be moved outside the kernel: the scheduler, the memory pager and the 68k interpretive emulator.

== AmigaDOS: the underlying system ==

The word "DOS" was originally an acronym for "Disk Operating System". Some say it should be "Disk Based Operating System" as it does a lot more than operate a disk and that it was really an operating system based (stored) on disks. Some say it should be "Device Operating System".

The whole AmigaDOS system includes things such as:

* A set of commands that can be used in the Shell window and elsewhere.
* A system for saving data to disk and retrieving it from disk.
* A system for filing data on disks.
* An interface for peripherals such as keyboards, monitors, printers, etc.
* A method of running programs
* A multitasking system for running more than one program at a time.
* etc. etc. etc.

Read the [[AmigaDOS manual]] to understand and learn everything about AmigaDOS.

== The Graphics library ==

The Graphics library handles every low level graphic operations like designing pixels on the monitor, creating graphic elements (bobs, sprites) and also writing text output.

== Intuition ==

The Intuition library is responsible for every graphical objects: windows, screens, gadgets, mouse pointers... It lays between any graphic program and the graphics library.

== The Workbench ==

The Workbench is the graphical place where you will manage your computer and all your files. The name was chosen because the user will use tools to create and work with the computer.

[[File:Wb.png|320px]]

== The Shell ==

While some people prefer to control the operating system using their mouse, others prefer using the keyboard. The shell is a text based window when you can type commands to execute actions in the operating system. In the shell the commands will display the results of their execution.

== ARexx - inter-program communication by scripting ==

The ARexx scripting language can be used to operate the Workbench and the most important Amiga applications from a script containing ARexx commands. This is extremely useful to perform repetitive tasks or to do what the controlled application was not even design to do.
After a learning curve, everybody can use ARexx as it is built in the system and the scripts can be executed immediately like any other tool.

= How is my data stored? =
== Files ==
=== Executable files ===
Programs you can start are stored in executable files. They contain binary code directly understandable by the computer. They are files with an executable bit, a flag that shows AmigaOS that such file will do something when started.
An example is a music player. When you start this executable, the player opens and you can start playing music files.

AmigaOS can run two different kinds of executable files: the AmigaOS native programs made for the PowerPC processor and programs created for the Motorola 68k processors. The laters are executed inside an emulation that transcripts them into PowerPC code.

==== Scripts ====

Scripts are text files containing a list of commands. So they are not strictly executables like ''binary code'' files but they can be executed by AmigaOS like if they were.
This is the case with AmigaDOS and ARexx scripts. These files need to have the executable bit, and the script bit.

=== Data files ===
Files that are not executable are data files. These contain some data that will be manipulated by programs. Some examples are a music file, a video file or a text document.

== Directories/Drawers ==
In order to organise things a bit, files are not all of them in the same place. We create directories which like drawers of a cabinet will store different files of the same kind.
Often the name ''directory'' is used when talking about the directory which is stored on a disk. The graphical interface of AmigaOS being called the Workbench, directories are often called ''drawers''.

Note: directories are often called ''folders'' on other systems.

== Disks, partitions and volumes ==
=== Disks ===
Disks are storage medium you can purchase on a computer store. We use them to store our files. They can be internal hard disks, external ones or a USB disk drive.

=== Partitions ===
A disk is often very big and many users prefer to make it more organised. This is done virtually splitting the disk into several smaller parts. This operation is known as creating partitions on a disk.

[[File:Partitions.png|Small part of Media Toolbox showing different partitions on the harddisk]]

On this screenshot you can see one harddisk with many partitions. Each color corresponds to a different filesystem which defines how data is stored. Also you can see a greyed area which is a blank area on the disk i.e. no partition is defined at this position.

=== Volumes ===
A partition is a physical area on a disk. To access it with AmigaOS we could read the physical data off the partition but it's not an easy way. To make it easier AmigaOS uses the concept of volumes. These are virtual representations of a partition. The volumes have a name so AmigaOS and therefore the user can access all files/directories stored on it in a very practical way: just by using its name.

= How to identify files/directories =

== On the Workbench ==

The Workbench being graphical, a lot of things are understandable just by looking at them. That's why icons are often enough to understand what kind of object it represents: a file, a directory, a disk...

In case you have a doubt, just look at the information on an icon. The Workbench will tell you the type of the object. It is displayed next to its name.

== In a shell ==

In a shell the '''list''' command can be used to see if an object is a file or a directory.

[[File:Files-dirs-in-shell.png|The '''list''' command shows a file of 925678 bytes and two directories]]

A file will be displayed with its size, whereas a directory will be displayed with the text '''Dir''' next to it.

Also, as you can see on the screenshot, the list command displays other characteristics on these 3 items: the protection bits and the date they were updated the last time. The command also sums up what it just listed.

= All AmigaOS components =

AmigaOS is made of components that are needed as soon as the system starts or later when the user or the system needs them.

== Kickstart modules ==

These components are the heart of AmigaOS. Their duties is to do graphics, to handle discs or to handle all reads/writes to files. Also one of them is the AmigaOS kernel which is a kind of director handling the work of all other components.
These Kickstart modules are loaded at the beginning of the operating system boot process (read [[UserDoc:How_AmigaOS_Works#AmigaOS_boot_procedure|here]]). You can find all them in the '''Kickstart''' directory in the system volume. Here is a list:

=== Mandatory modules ===

The following modules are required in any AmigaOS system. Without one of these, the system will not start.

* kernel - The kernel works like a conductor in an orchestra. Its job is to make everything works together. It creates processes, handle memory usage, defines the way other components will access peripherals...etc. Note that the AmigaOS kernel is not based on any other kernel. It is a self made kernel that works since 1983.
* loader - this component handles the loading of all other kickstart modules
* battclock.resource.kmod - this module handles reading/writing the battery backed up clock which is used on all computers to keep the date and time
* bootimage - this is the boot picture. It is displayed during the start sequence of AmigaOS
* bootmenu.kmod - this component handles the Early Startup Menu the use can use to define some settings before starting AmigaOS
* con-handler.kmod - it directs the read and write requests to the console window, to a serial AUX: device or any other supported interface
* console.device.kmod - it opens a window and reads/writes text to and from that window
* diskboot.kmod - handles the booting of AmigaOS from a supported disk
* diskboot.config - this is a text file experienced users can modify to change the boot behaviour of AmigaOS
* dos.library.kmod - this module is a collection of functions that any program can use to perform actions on disks, files and directories
* elf.library.kmod - handles the loading of executable programs
* env-handler.kmod - handles the read/writes of environment variables
* FileSystem.resource.kmod - handles the use of the different filesystems
* gadtools.library.kmod - collection of functions used to create all graphic objects like gadgets, sliders, menus...
* gameport.device.kmod - handles the read/writes of game pads and joysticks
* graphics.library.kmod - collection of functions used to draw graphic elements on the monitor
* hunk.library.kmod - set of functions to read a data stream into memory
* input.device.kmod - handles of input events like keyboard events or mouse clicks
* intuition.library.kmod - collection of functions to create and handle all graphic elements (screens, windows, the mouse pointer...)
* layers.library.kmod - set of functions to be used to handle different layers in graphic operations
* keyboard.device.kmod - driver for the keyboard
* keymap.library.kmod - functions to handle different keymaps
* newlib.library.kmod - collection of functions to perform memory operations (allocating memory, copying memory areas... )
* nonvolatile.library.kmod - provides a simple means for an application developer to manage nonvolatile storage
* nvram.resource.kmod - handles the read/writes to the EEPROM chip present on many AmigaOS computers
* PCIGraphics.card - driver that supports the use of different graphic cards
* ram-handler.kmod - functions that handles the '''Ram disk:''' special disk
* ramdrive.device.kmod - device that allows the usage of the ramdrive device '''RAD:''' disk
* ramlib.kmod - loads disk based libraries and devices for exec.library
* rtg.library - library of functions to perform lowlevel graphic operations on graphic cards
* shell.kmod - the AmigaOS command line interface
* strap.kmod - module that handles booting on different disk devices
* timer.device.kmod - driver to give access to timing functions

=== Filesystem support ===

These kickstart modules can be loaded or left aside. If you want to use a particular filesystem on your disk partitions, you need to load the corresponding filesystem module.

* CDFileSystem - handles the CD-ROM disks with data stored in different formats: ISO9660, HFS...
* SmartFilesystem - allows the usage of partitions in SFS0 and SFS2 layouts
* JXFileSystem - allows the usage of partitions in JXFS layout
* FastFileSystem - allows the usage of partitions in FFS and FFS2 layouts
* diskcache.library.kmod - component required by the SmartFileSystem and JXFileSystem modules

=== Hardware drivers ===

==== Graphic cards drivers ====

* 3dfxVoodoo.chip
* 3DLabsPermedia2.chip
* ATIRadeon.chip
* RadeonHD.chip
* siliconmotion502.chip

==== Disk drivers ====

Each of these drivers allow the use of disks connected to a disk controller. These files are named with the name of the controller they support. As an example, the '''sii3114ide.device.kmod''' allows to use disks connected on a '''Silicon Image SiI3114''' controller chip.

* it8212ide.device.kmod
* lsi53c8xx.device.kmod
* sam460sata.device.kmod
* sii3112ide.device.kmod
* sii3512ide.device.kmod
* sii3114ide.device.kmod
* sii0680ide.device.kmod
* sii3132ide.device.kmod

==== USB drivers ====

* hub.usbfd
* usbsys.device
* usbresource.library
* ehci.usbhcd
* ohci.usbhcd
* uhci.usbhcd
* massstorage.usbfd

==== Other drivers ====

* bootkeyboard.usbfd - allows a USB keyboard to be used even before the USB stack is loaded
* bootmouse.usbfd - allows a USB mouse to be used even before the USB stack is loaded
* fpga.resource.kmod - allows to use the FPGA components which are present on some Amiga computers
* i2c.resource.kmod - allows to use the i2c interface present on some Amiga computers
* xena.resource.kmod - provides access to the Xena chip on the AmigaOne X1000

=== Misc modules ===

* petunia.library.kmod - this module contains the Just-In-Time emulator that allows AmigaOS to run programs made for the Motorola 68k processor

== System components ==

[[File:Workbench_directory_listing.png|frame|right|List of directories and files present at the root of any AmigaOS system]]

Beside the kickstart modules, AmigaOS uses many different components that can be loaded only when used. These files are stored in different directories in the system volume.
Here is described a default AmigaOS installation.

* C
This directory contains AmigaDOS '''C'''ommands
* Classes
contains different object elements easy to be used in any program: gadgets, requesters, graphic table, windows...
* Devs
contains definition for '''Dev'''ices
* Emulation
contains files used for the 68k emulation (though E-UAE)
* Fonts
contains various systems fonts
* Internet
contains a dialer to connect to Internet
* Kickstart
contains the kickstart modules
* L
contains hand'''l'''ers and filesystems
* Libs
contains dynamic '''Libr'''airies of functions
* Locale
contains all files used to localise the system (catalogs, keymaps...)
* MUI
contains the needed files for programs that use the MUI third party graphic interface
* [[Prefs]]
contains the preference programs used to customise AmigaOS
* S
contains the '''S'''cripts
* SObjs
contains .so shared object library files
* Storage
contains other optional files
* System
contains some programs used by the system itself (i.e. you don't need to run them yourself) or low-level programs like disk tools
* [[Utilities]]
contains several programs you can use to achieve some tasks on AmigaOS

= Motorola 680x0 Emulators =

For a long time Amigas have had the famous Motorola 680x0 processors as the central unit for execution. Unfortunately the time of the 680x0 series is passing in favor of other architectures. The new era of processors reached the Amiga some time ago, when expansion boards became available for extending the Classic systems with the raw power of a PowerPC processor.

In the old operating system (AmigaOS 3.x) it was not possible to gain the full advantage of the new processors. The system itself and most of the applications required the original Motorola 680x0 processor. There was no 680x0 emulation available for the PowerPCs, so the 680x0 could not be "switched off".

Thus the new processors remained as a powerful, but mostly unused adjunct to the main 680x0 processor. "Native" PowerPC programs were rare, and every time a PowerPC program called the system, a so called "context switch" occurred between the 680x0 and PowerPC code, often causing a large performance penalty.

The new Amiga platform is based on the PowerPC processor family, therefore the new version of the AmigaOS has to smooth the transition from the 680x0 series, which is achieved by emulating the old processor architecture. The operating system itself is written almost 100 percent for the PowerPC processors, but the 680x0 legacy applications require an emulated 680x0 processor.

== Two 680x0 Emulators ==

In version 4.0 of AmigaOS, two different emulators were implemented; one is the successor of BlackBox emulation, it is an interpretive emulator, thus the emulation speed is mediocre. On the other hand it has a very low "reaction time", and is ideal for time critical parts, such as interrupts.

The other is Petunia, the "JIT emulator". A fast, but less compatible way of emulation of the legacy Motorola processors. It is intended mainly for emulating applications, and therefore, when execution of the application leaves the bounds of the application's code segment, emulation falls back to the interpretive method, where it does its job and returns to the JIT emulation again.

Dynamic recompilation (also called just-in-time compilation or simply JIT compilation) is a technique of translating foreign processor machine code to native machine code, "on the fly".

This technique is common nowadays, commonly applied in JAVA virtual machines, and it is also used with success in several emulators. In dynamic recompilation there is the possibility of runtime optimization of the emulated code by collecting statistics of the execution process. Therefore (theoretically) the final executed code can be even faster than the original code on its original processor.

== Features ==

Emulated opcodes:
* all user and supervisor level opcodes of the Motorola 68040
* all FPU opcodes of the Motorola 68881/68882

AmigaOS claims only 68020/68881 compatibility to applications because this is the safest compatibility level, but both emulators are compatible with the machine code up to the level of 68040/060 processors.

At compile time, a low level flag and branch control analysis allows on-the-fly optimizations of compiled code.

== Removing the JIT Emulator ==

Using the dynamic translation requires a lot more memory than the interpretive emulation. The translated code needs to be stored somewhere, not to mention the data collection tables.

If speed is not as important as the memory consumption of the system, then the JIT emulator can be removed, leaving the job to the interpretive emulator.

Thanks to the modular design of AmigaOS kickstart, all you need to do is edit the "Sys:Kickstart/Kicklayout" file, simply put a semicolon (;) at the beginning of the module line of Petunia.library.kmod. After rebooting the system from cold, the JIT emulator will not be reloaded. Make sure that you alter the appropriate configuration in the Kicklayout file, there may be several alternative configurations, with different names like "DefaultJIT", or "DefaultNoJIT".

== Configuring the Emulators ==

Petunia cooperates with a so called "black list". By default Petunia emulates every 680x0 program or library that is loaded by DOS.library/LoadSeg function, but if an executable or library shows incompatibilities with Petunia, then it can be explicitly inhibited from the dynamic recompilation by specifying it in a list file.

If an executable needs to be added to the list, then it can be done by extending the file "DEVS:applications.dos" with the '''Compatibility''' preferences program from the Prefs drawer of the system. Adding a program name to the list and checking it will prevent Petunia from emulating that program, and it will be interpreted instead by the built-in interpreter.

Removing a program from the list or unchecking (thus allowing Petunia to emulate it again) can be done with the same preferences program.

Please note: some programs consist of multiple executables (shared libraries, plugins). If you want to fully disable the translation of such programs, then every part must be added to the list.

For example to disable UnArc fully, you would have to add all files from libs:xad and also xadmaster.library to the list.

= AmigaOS boot procedure =

Basically a computer with AmigaOS does the following when the power button is pushed:

* [[File:Uboot.jpg|200px]]
the BIOS ([[UserDoc:BIOS|Uboot]] or [[UserDoc:BIOS|CFE]]) of the computer initialises the hardware: graphic card, USB ports... At this point, the monitor wakes up and the first information are displayed. This allows to see if hardware is correctly recognised. As an example you can see if a hard drive is correctly connected into the machine and your BIOS is correctly setup to make this drive useable.
* depending on how you setup the BIOS it will look on the harddisk to find the Second Level Booter (SLB). This program is stored on the first sectors of the disk. Whereas the BIOS does not know about AmigaOS disk structure, the SLB will be able to ''understand'' the AmigaOS partitions and files. In other words, it is the link between the BIOS and the rest of the boot procedure. Its goal is also to give you the ability to start several configurations present on the same drive.
* [[File:SLB.png|200px]]
the SLB will analyses all Amiga partitions on the disk it is installed on. It will read each [[UserDoc:kickstart_configuration|system configuration]] it finds on the partitions. It will show all available configurations for the user to select one to load.
The user can define many different kickstart configurations to choose from. Also both AmigaOS and Linux can be selected for boot.
* [[File:Kmods loading.png|200px]]
the SLB loads the kickstart files of the selected configuration and executes the '''Loader''' module
* '''Loader''' executes the kickstart modules (Exec, devices, libraries...)
* AmigaOS becomes alive displaying the AmigaOS boot picture on the monitor
* the AmigaDOS library executes the [[UserDoc:System_Scripts#startup-sequence|startup-sequence]] script found on the system volume
* the Startup-sequence will be executed and all commands it contains are executed. It means that starting from here the boot procedure is easy to follow and understand.
* the Workbench is started

At this point the user can use his/her computer.

= How to make a Bootable USB Memory Stick for AmigaOS 4.1 =

By Julian Margetson ("Spectre660")

Prerequisites:
* USB memory stick of 2 GB or less in size.
* It is best to only have one USB mass storage device connected while you are creating your bootable USB memory stick.
* Plug the USB memory stick into a USB port on your machine.
* Note that the device will be formatted so make sure that you use an empty memory stick or one that does not contain any data that you need or backup the contents before you begin.

Procedure:
# You use Media Toolbox in the System: drawer to prepare the USB stick. On starting Media Toolbox select ''usbdisk.device'' as the device to use.
# Make certain that you have selected usbdisk.device and not any other device.
# Click on "Start"
# You will see the usb mass storage unit connected in a list.
# Make sure that the Unit type displayed for the USB memory stick is "Removable hard disk"
# Select that Unit by clicking on it.
# The first thing that you need to do is to install the RDB onto the USB Memory Stick.
# Click on the "Install" button.
# A window Labeled "RDB/disk geometry editing" comes up.
## Towards the bottom of the window is the "AmigaOne boot code (SLB)" section.
## Select the "Install" button .
## A file requester "Select AmigaOne Boot Code" now comes up with the Drawer choice defaulting to "l:"
## Select file "slb_v2".
## Select Ok.
## You are now returned to the "RDB/disk geometry editing window".
## Select "Ok-accept changes".
# You are now returned to the display showing the attached USB unit.
# Select "Edit partitions and Filesystems". You will now see the Window 'Editing partitions for disk"
# Select "Add partition"
# This defaults to using the whole device as a single partition.
# It is possible to use create more partitions but for this tutorial we will only use one.
# You now need to give the partition a unique name (e.g. USB0 or something that is different from any of the existing partitions on your hard drive). This is done by changing the default DH0 in the "Name" box.
# Now make sure that the Boxes "Automount" and "Bootable" are selected and show the "Tick mark".
# You need to set "Boot priority" to higher than the boot priority of your hard drive boot partition(s). This is done by increasing Boot priority by clicking on the "+" to the right of the "boot priority" box. Normally you can set the boot priority to 2 .
# Next it is time to select the file system to use.
# Select "Select filesystem/edit details".
# The Window "Editing details for partition 'USB0'" ,or whatever partition name you used, comes up.
## Select the file system that you are going to use by selecting the pull down menu under "Filesystem chooser".
## Only filesystems SFS/00 or SFS/02 will work for a bootable device.
## The option that gives the most flexibility at the moment is SFS/00 as a USB stick in this format can be read and written to using another compatible system in the event that you need to make modifications after it is created without a booting AmigaOS 4.1 machine.
## Next select Blocksize from the "Blocksize" pull down menu. 512 is the correct size to use.
## Now Select "Ok-accept changes".
## Your are now returned to the "Edit partitions for disk" window.
## Again select "Ok-accept changes"
# You are now returned to the window showing the USB mass storage unit list.
# Select "Save to disk"
# A requester pops up with the options "Yes, Save." or "No!"
# Select the "Yes, save." option.
# You now close Media Toolbox by clicking on the close icon (X) on the left of the Media Toolbox window.
# This will give you a requester advising that you need to reboot the machine for the changes to take effect. At this point you need to remove the USB memory stick for the machine. If you do not then the Machine will attempt boot from it before it is formatted and the required Kickstart and AmigaOS 4.1 files are copied to it.
# Select "Yes, reboot NOW!".
# Once you have rebooted connect your USB Memory Stick to a USB port.
# A disk icon "USB0:Uninitialized" (or whatever partition name you used) appears on Workbench.
# You now need to format the device.
# To format Select this Icon and go to the Workbench "Icons" menu .
# Select "Format Disk"
# You can give the USB Memory Stick a unique name and select whether you want a Trashcan or not.
# You can use either a full Format or a Quick Format. Full Format may take a few minutes.
# Once formatted the USB Memory Stick is ready for you to copy the required files from you hard drive or AmigaOS Install CD to it in order to boot AmigaOS 4.1 from it.

UserDoc:How AmigaOS Works

2015-05-29T06:07:39Z

Brian Deneen: /* Introduction */ added new punctuation

As already mentioned, AmigaOS was a pioneer in the early days of personal computing in delivering sophistication that contemporary systems could only have dreamt of and pretended to offer. Today, AmigaOS continues to offer a straightforward elegance that seems to be overlooked in the development of other platforms. Thanks to the concepts behind AmigaOS, the system is easy to understand and to use by everyone.

In this page we will explore all these concepts of AmigaOS. Also you will learn here the naming of all parts of the system.

= Introduction =

AmigaOS is made of different components which are either mandatory (i.e., AmigaOS will not work without them) or components the user can choose to use or not. All these components can have one or mutiple interfaces a user or a developer can use to operate with the components and through them to control the operating system.

= The most important components =

== Exec, the AmigaOS kernel ==

Exec is the kernel of AmigaOS. It is the component that pilots all other components. It is responsible of running programs, dealing with computer memory, managing low-level resources that programs may need. In other words, it organises everything to make the operating system run.

It is made of different parts that cannot be moved outside the kernel: the scheduler, the memory pager and the 68k interpretive emulator.

== AmigaDOS: the underlying system ==

The word "DOS" was originally an acronym for "Disk Operating System". Some say it should be "Disk Based Operating System" as it does a lot more than operate a disk and that it was really an operating system based (stored) on disks. Some say it should be "Device Operating System".

The whole AmigaDOS system includes things such as:

* A set of commands that can be used in the Shell window and elsewhere.
* A system for saving data to disk and retrieving it from disk.
* A system for filing data on disks.
* An interface for peripherals such as keyboards, monitors, printers, etc.
* A method of running programs
* A multitasking system for running more than one program at a time.
* etc. etc. etc.

Read the [[AmigaDOS manual]] to understand and learn everything about AmigaDOS.

== The Graphics library ==

The Graphics library handles every low level graphic operations like designing pixels on the monitor, creating graphic elements (bobs, sprites) and also writing text output.

== Intuition ==

The Intuition library is responsible for every graphical objects: windows, screens, gadgets, mouse pointers... It lays between any graphic program and the graphics library.

== The Workbench ==

The Workbench is the graphical place where you will manage your computer and all your files. The name was chosen because the user will use tools to create and work with the computer.

[[File:Wb.png|320px]]

== The Shell ==

While some people prefer to control the operating system using their mouse, others prefer using the keyboard. The shell is a text based window when you can type commands to execute actions in the operating system. In the shell the commands will display the results of their execution.

== ARexx - inter-program communication by scripting ==

The ARexx scripting language can be used to operate the Workbench and the most important Amiga applications from a script containing ARexx commands. This is extremely useful to perform repetitive tasks or to do what the controlled application was not even design to do.
After a learning curve, everybody can use ARexx as it is built in the system and the scripts can be executed immediately like any other tool.

= How is my data stored? =
== Files ==
=== Executable files ===
Programs you can start are stored in executable files. They contain binary code directly understandable by the computer. They are files with an executable bit, a flag that shows AmigaOS that such file will do something when started.
An example is a music player. When you start this executable, the player opens and you can start playing music files.

AmigaOS can run two different kinds of executable files: the AmigaOS native programs made for the PowerPC processor and programs created for the Motorola 68k processors. The laters are executed inside an emulation that transcripts them into PowerPC code.

==== Scripts ====

Scripts are text files containing a list of commands. So they are not strictly executables like ''binary code'' files but they can be executed by AmigaOS like if they were.
This is the case with AmigaDOS and ARexx scripts. These files need to have the executable bit, and the script bit.

=== Data files ===
Files that are not executable are data files. These contain some data that will be manipulated by programs. Some examples are a music file, a video file or a text document.

== Directories/Drawers ==
In order to organise things a bit, files are not all of them in the same place. We create directories which like drawers of a cabinet will store different files of the same kind.
Often the name ''directory'' is used when talking about the directory which is stored on a disk. The graphical interface of AmigaOS being called the Workbench, directories are often called ''drawers''.

Note: directories are often called ''folders'' on other systems.

== Disks, partitions and volumes ==
=== Disks ===
Disks are storage medium you can purchase on a computer store. We use them to store our files. They can be internal hard disks, external ones or a USB disk drive.

=== Partitions ===
A disk is often very big and many users prefer to make it more organised. This is done virtually splitting the disk into several smaller parts. This operation is known as creating partitions on a disk.

[[File:Partitions.png|Small part of Media Toolbox showing different partitions on the harddisk]]

On this screenshot you can see one harddisk with many partitions. Each color corresponds to a different filesystem which defines how data is stored. Also you can see a greyed area which is a blank area on the disk i.e. no partition is defined at this position.

=== Volumes ===
A partition is a physical area on a disk. To access it with AmigaOS we could read the physical data off the partition but it's not an easy way. To make it easier AmigaOS uses the concept of volumes. These are virtual representations of a partition. The volumes have a name so AmigaOS and therefore the user can access all files/directories stored on it in a very practical way: just by using its name.

= How to identify files/directories =

== On the Workbench ==

The Workbench being graphical, a lot of things are understandable just by looking at them. That's why icons are often enough to understand what kind of object it represents: a file, a directory, a disk...

In case you have a doubt, just look at the information on an icon. The Workbench will tell you the type of the object. It is displayed next to its name.

== In a shell ==

In a shell the '''list''' command can be used to see if an object is a file or a directory.

[[File:Files-dirs-in-shell.png|The '''list''' command shows a file of 925678 bytes and two directories]]

A file will be displayed with its size, whereas a directory will be displayed with the text '''Dir''' next to it.

Also, as you can see on the screenshot, the list command displays other characteristics on these 3 items: the protection bits and the date they were updated the last time. The command also sums up what it just listed.

= All AmigaOS components =

AmigaOS is made of components that are needed as soon as the system starts or later when the user or the system needs them.

== Kickstart modules ==

These components are the heart of AmigaOS. Their duties is to do graphics, to handle discs or to handle all reads/writes to files. Also one of them is the AmigaOS kernel which is a kind of director handling the work of all other components.
These Kickstart modules are loaded at the beginning of the operating system boot process (read [[UserDoc:How_AmigaOS_Works#AmigaOS_boot_procedure|here]]). You can find all them in the '''Kickstart''' directory in the system volume. Here is a list:

=== Mandatory modules ===

The following modules are required in any AmigaOS system. Without one of these, the system will not start.

* kernel - The kernel works like a conductor in an orchestra. Its job is to make everything works together. It creates processes, handle memory usage, defines the way other components will access peripherals...etc. Note that the AmigaOS kernel is not based on any other kernel. It is a self made kernel that works since 1983.
* loader - this component handles the loading of all other kickstart modules
* battclock.resource.kmod - this module handles reading/writing the battery backed up clock which is used on all computers to keep the date and time
* bootimage - this is the boot picture. It is displayed during the start sequence of AmigaOS
* bootmenu.kmod - this component handles the Early Startup Menu the use can use to define some settings before starting AmigaOS
* con-handler.kmod - it directs the read and write requests to the console window, to a serial AUX: device or any other supported interface
* console.device.kmod - it opens a window and reads/writes text to and from that window
* diskboot.kmod - handles the booting of AmigaOS from a supported disk
* diskboot.config - this is a text file experienced users can modify to change the boot behaviour of AmigaOS
* dos.library.kmod - this module is a collection of functions that any program can use to perform actions on disks, files and directories
* elf.library.kmod - handles the loading of executable programs
* env-handler.kmod - handles the read/writes of environment variables
* FileSystem.resource.kmod - handles the use of the different filesystems
* gadtools.library.kmod - collection of functions used to create all graphic objects like gadgets, sliders, menus...
* gameport.device.kmod - handles the read/writes of game pads and joysticks
* graphics.library.kmod - collection of functions used to draw graphic elements on the monitor
* hunk.library.kmod - set of functions to read a data stream into memory
* input.device.kmod - handles of input events like keyboard events or mouse clicks
* intuition.library.kmod - collection of functions to create and handle all graphic elements (screens, windows, the mouse pointer...)
* layers.library.kmod - set of functions to be used to handle different layers in graphic operations
* keyboard.device.kmod - driver for the keyboard
* keymap.library.kmod - functions to handle different keymaps
* newlib.library.kmod - collection of functions to perform memory operations (allocating memory, copying memory areas... )
* nonvolatile.library.kmod - provides a simple means for an application developer to manage nonvolatile storage
* nvram.resource.kmod - handles the read/writes to the EEPROM chip present on many AmigaOS computers
* PCIGraphics.card - driver that supports the use of different graphic cards
* ram-handler.kmod - functions that handles the '''Ram disk:''' special disk
* ramdrive.device.kmod - device that allows the usage of the ramdrive device '''RAD:''' disk
* ramlib.kmod - loads disk based libraries and devices for exec.library
* rtg.library - library of functions to perform lowlevel graphic operations on graphic cards
* shell.kmod - the AmigaOS command line interface
* strap.kmod - module that handles booting on different disk devices
* timer.device.kmod - driver to give access to timing functions

=== Filesystem support ===

These kickstart modules can be loaded or left aside. If you want to use a particular filesystem on your disk partitions, you need to load the corresponding filesystem module.

* CDFileSystem - handles the CD-ROM disks with data stored in different formats: ISO9660, HFS...
* SmartFilesystem - allows the usage of partitions in SFS0 and SFS2 layouts
* JXFileSystem - allows the usage of partitions in JXFS layout
* FastFileSystem - allows the usage of partitions in FFS and FFS2 layouts
* diskcache.library.kmod - component required by the SmartFileSystem and JXFileSystem modules

=== Hardware drivers ===

==== Graphic cards drivers ====

* 3dfxVoodoo.chip
* 3DLabsPermedia2.chip
* ATIRadeon.chip
* RadeonHD.chip
* siliconmotion502.chip

==== Disk drivers ====

Each of these drivers allow the use of disks connected to a disk controller. These files are named with the name of the controller they support. As an example, the '''sii3114ide.device.kmod''' allows to use disks connected on a '''Silicon Image SiI3114''' controller chip.

* it8212ide.device.kmod
* lsi53c8xx.device.kmod
* sam460sata.device.kmod
* sii3112ide.device.kmod
* sii3512ide.device.kmod
* sii3114ide.device.kmod
* sii0680ide.device.kmod
* sii3132ide.device.kmod

==== USB drivers ====

* hub.usbfd
* usbsys.device
* usbresource.library
* ehci.usbhcd
* ohci.usbhcd
* uhci.usbhcd
* massstorage.usbfd

==== Other drivers ====

* bootkeyboard.usbfd - allows a USB keyboard to be used even before the USB stack is loaded
* bootmouse.usbfd - allows a USB mouse to be used even before the USB stack is loaded
* fpga.resource.kmod - allows to use the FPGA components which are present on some Amiga computers
* i2c.resource.kmod - allows to use the i2c interface present on some Amiga computers
* xena.resource.kmod - provides access to the Xena chip on the AmigaOne X1000

=== Misc modules ===

* petunia.library.kmod - this module contains the Just-In-Time emulator that allows AmigaOS to run programs made for the Motorola 68k processor

== System components ==

[[File:Workbench_directory_listing.png|frame|right|List of directories and files present at the root of any AmigaOS system]]

Beside the kickstart modules, AmigaOS uses many different components that can be loaded only when used. These files are stored in different directories in the system volume.
Here is described a default AmigaOS installation.

* C
This directory contains AmigaDOS '''C'''ommands
* Classes
contains different object elements easy to be used in any program: gadgets, requesters, graphic table, windows...
* Devs
contains definition for '''Dev'''ices
* Emulation
contains files used for the 68k emulation (though E-UAE)
* Fonts
contains various systems fonts
* Internet
contains a dialer to connect to Internet
* Kickstart
contains the kickstart modules
* L
contains hand'''l'''ers and filesystems
* Libs
contains dynamic '''Libr'''airies of functions
* Locale
contains all files used to localise the system (catalogs, keymaps...)
* MUI
contains the needed files for programs that use the MUI third party graphic interface
* [[Prefs]]
contains the preference programs used to customise AmigaOS
* S
contains the '''S'''cripts
* SObjs
contains .so shared object library files
* Storage
contains other optional files
* System
contains some programs used by the system itself (i.e. you don't need to run them yourself) or low-level programs like disk tools
* [[Utilities]]
contains several programs you can use to achieve some tasks on AmigaOS

= Motorola 680x0 Emulators =

For a long time Amigas have had the famous Motorola 680x0 processors as the central unit for execution. Unfortunately the time of the 680x0 series is passing in favor of other architectures. The new era of processors reached the Amiga some time ago, when expansion boards became available for extending the Classic systems with the raw power of a PowerPC processor.

In the old operating system (AmigaOS 3.x) it was not possible to gain the full advantage of the new processors. The system itself and most of the applications required the original Motorola 680x0 processor. There was no 680x0 emulation available for the PowerPCs, so the 680x0 could not be "switched off".

Thus the new processors remained as a powerful, but mostly unused adjunct to the main 680x0 processor. "Native" PowerPC programs were rare, and every time a PowerPC program called the system, a so called "context switch" occurred between the 680x0 and PowerPC code, often causing a large performance penalty.

The new Amiga platform is based on the PowerPC processor family, therefore the new version of the AmigaOS has to smooth the transition from the 680x0 series, which is achieved by emulating the old processor architecture. The operating system itself is written almost 100 percent for the PowerPC processors, but the 680x0 legacy applications require an emulated 680x0 processor.

== Two 680x0 Emulators ==

In version 4.0 of AmigaOS, two different emulators were implemented; one is the successor of BlackBox emulation, it is an interpretive emulator, thus the emulation speed is mediocre. On the other hand it has a very low "reaction time", and is ideal for time critical parts, such as interrupts.

The other is Petunia, the "JIT emulator". A fast, but less compatible way of emulation of the legacy Motorola processors. It is intended mainly for emulating applications, and therefore, when execution of the application leaves the bounds of the application's code segment, emulation falls back to the interpretive method, where it does its job and returns to the JIT emulation again.

Dynamic recompilation (also called just-in-time compilation or simply JIT compilation) is a technique of translating foreign processor machine code to native machine code, "on the fly".

This technique is common nowadays, commonly applied in JAVA virtual machines, and it is also used with success in several emulators. In dynamic recompilation there is the possibility of runtime optimization of the emulated code by collecting statistics of the execution process. Therefore (theoretically) the final executed code can be even faster than the original code on its original processor.

== Features ==

Emulated opcodes:
* all user and supervisor level opcodes of the Motorola 68040
* all FPU opcodes of the Motorola 68881/68882

AmigaOS claims only 68020/68881 compatibility to applications because this is the safest compatibility level, but both emulators are compatible with the machine code up to the level of 68040/060 processors.

At compile time, a low level flag and branch control analysis allows on-the-fly optimizations of compiled code.

== Removing the JIT Emulator ==

Using the dynamic translation requires a lot more memory than the interpretive emulation. The translated code needs to be stored somewhere, not to mention the data collection tables.

If speed is not as important as the memory consumption of the system, then the JIT emulator can be removed, leaving the job to the interpretive emulator.

Thanks to the modular design of AmigaOS kickstart, all you need to do is edit the "Sys:Kickstart/Kicklayout" file, simply put a semicolon (;) at the beginning of the module line of Petunia.library.kmod. After rebooting the system from cold, the JIT emulator will not be reloaded. Make sure that you alter the appropriate configuration in the Kicklayout file, there may be several alternative configurations, with different names like "DefaultJIT", or "DefaultNoJIT".

== Configuring the Emulators ==

Petunia cooperates with a so called "black list". By default Petunia emulates every 680x0 program or library that is loaded by DOS.library/LoadSeg function, but if an executable or library shows incompatibilities with Petunia, then it can be explicitly inhibited from the dynamic recompilation by specifying it in a list file.

If an executable needs to be added to the list, then it can be done by extending the file "DEVS:applications.dos" with the '''Compatibility''' preferences program from the Prefs drawer of the system. Adding a program name to the list and checking it will prevent Petunia from emulating that program, and it will be interpreted instead by the built-in interpreter.

Removing a program from the list or unchecking (thus allowing Petunia to emulate it again) can be done with the same preferences program.

Please note: some programs consist of multiple executables (shared libraries, plugins). If you want to fully disable the translation of such programs, then every part must be added to the list.

For example to disable UnArc fully, you would have to add all files from libs:xad and also xadmaster.library to the list.

= AmigaOS boot procedure =

Basically a computer with AmigaOS does the following when the power button is pushed:

* [[File:Uboot.jpg|200px]]
the BIOS ([[UserDoc:BIOS|Uboot]] or [[UserDoc:BIOS|CFE]]) of the computer initialises the hardware: graphic card, USB ports... At this point, the monitor wakes up and the first information are displayed. This allows to see if hardware is correctly recognised. As an example you can see if a hard drive is correctly connected into the machine and your BIOS is correctly setup to make this drive useable.
* depending on how you setup the BIOS it will look on the harddisk to find the Second Level Booter (SLB). This program is stored on the first sectors of the disk. Whereas the BIOS does not know about AmigaOS disk structure, the SLB will be able to ''understand'' the AmigaOS partitions and files. In other words, it is the link between the BIOS and the rest of the boot procedure. Its goal is also to give you the ability to start several configurations present on the same drive.
* [[File:SLB.png|200px]]
the SLB will analyses all Amiga partitions on the disk it is installed on. It will read each [[UserDoc:kickstart_configuration|system configuration]] it finds on the partitions. It will show all available configurations for the user to select one to load.
The user can define many different kickstart configurations to choose from. Also both AmigaOS and Linux can be selected for boot.
* [[File:Kmods loading.png|200px]]
the SLB loads the kickstart files of the selected configuration and executes the '''Loader''' module
* '''Loader''' executes the kickstart modules (Exec, devices, libraries...)
* AmigaOS becomes alive displaying the AmigaOS boot picture on the monitor
* the AmigaDOS library executes the [[UserDoc:System_Scripts#startup-sequence|startup-sequence]] script found on the system volume
* the Startup-sequence will be executed and all commands it contains are executed. It means that starting from here the boot procedure is easy to follow and understand.
* the Workbench is started

At this point the user can use his/her computer.

= How to make a Bootable USB Memory Stick for AmigaOS 4.1 =

By Julian Margetson ("Spectre660")

Prerequisites:
* USB memory stick of 2 GB or less in size.
* It is best to only have one USB mass storage device connected while you are creating your bootable USB memory stick.
* Plug the USB memory stick into a USB port on your machine.
* Note that the device will be formatted so make sure that you use an empty memory stick or one that does not contain any data that you need or backup the contents before you begin.

Procedure:
# You use Media Toolbox in the System: drawer to prepare the USB stick. On starting Media Toolbox select ''usbdisk.device'' as the device to use.
# Make certain that you have selected usbdisk.device and not any other device.
# Click on "Start"
# You will see the usb mass storage unit connected in a list.
# Make sure that the Unit type displayed for the USB memory stick is "Removable hard disk"
# Select that Unit by clicking on it.
# The first thing that you need to do is to install the RDB onto the USB Memory Stick.
# Click on the "Install" button.
# A window Labeled "RDB/disk geometry editing" comes up.
## Towards the bottom of the window is the "AmigaOne boot code (SLB)" section.
## Select the "Install" button .
## A file requester "Select AmigaOne Boot Code" now comes up with the Drawer choice defaulting to "l:"
## Select file "slb_v2".
## Select Ok.
## You are now returned to the "RDB/disk geometry editing window".
## Select "Ok-accept changes".
# You are now returned to the display showing the attached USB unit.
# Select "Edit partitions and Filesystems". You will now see the Window 'Editing partitions for disk"
# Select "Add partition"
# This defaults to using the whole device as a single partition.
# It is possible to use create more partitions but for this tutorial we will only use one.
# You now need to give the partition a unique name (e.g. USB0 or something that is different from any of the existing partitions on your hard drive). This is done by changing the default DH0 in the "Name" box.
# Now make sure that the Boxes "Automount" and "Bootable" are selected and show the "Tick mark".
# You need to set "Boot priority" to higher than the boot priority of your hard drive boot partition(s). This is done by increasing Boot priority by clicking on the "+" to the right of the "boot priority" box. Normally you can set the boot priority to 2 .
# Next it is time to select the file system to use.
# Select "Select filesystem/edit details".
# The Window "Editing details for partition 'USB0'" ,or whatever partition name you used, comes up.
## Select the file system that you are going to use by selecting the pull down menu under "Filesystem chooser".
## Only filesystems SFS/00 or SFS/02 will work for a bootable device.
## The option that gives the most flexibility at the moment is SFS/00 as a USB stick in this format can be read and written to using another compatible system in the event that you need to make modifications after it is created without a booting AmigaOS 4.1 machine.
## Next select Blocksize from the "Blocksize" pull down menu. 512 is the correct size to use.
## Now Select "Ok-accept changes".
## Your are now returned to the "Edit partitions for disk" window.
## Again select "Ok-accept changes"
# You are now returned to the window showing the USB mass storage unit list.
# Select "Save to disk"
# A requester pops up with the options "Yes, Save." or "No!"
# Select the "Yes, save." option.
# You now close Media Toolbox by clicking on the close icon (X) on the left of the Media Toolbox window.
# This will give you a requester advising that you need to reboot the machine for the changes to take effect. At this point you need to remove the USB memory stick for the machine. If you do not then the Machine will attempt boot from it before it is formatted and the required Kickstart and AmigaOS 4.1 files are copied to it.
# Select "Yes, reboot NOW!".
# Once you have rebooted connect your USB Memory Stick to a USB port.
# A disk icon "USB0:Uninitialized" (or whatever partition name you used) appears on Workbench.
# You now need to format the device.
# To format Select this Icon and go to the Workbench "Icons" menu .
# Select "Format Disk"
# You can give the USB Memory Stick a unique name and select whether you want a Trashcan or not.
# You can use either a full Format or a Quick Format. Full Format may take a few minutes.
# Once formatted the USB Memory Stick is ready for you to copy the required files from you hard drive or AmigaOS Install CD to it in order to boot AmigaOS 4.1 from it.

Tutorials:Main

2014-09-23T07:41:58Z

Brian Deneen: /* AmiWest 2013 section finished */

= Tutorials =

Tutorials have been provided by various authors.

== General ==

[[The Hacking Way: Part 1 - First Steps]]

[[The Right Tool for the Job (Shared Objects)]]

[[How to Build Stubs for 68k Libraries]]

== Debugging ==

[[How to install a hardware interrupt]]

[[How to open and use the exec debug interface]]

[[GDB for Beginners]]

[[Using Crash-Logs for Debugging]]

[[Debug Logging on AmigaOS]]

[[Redirecting Debug Output to the Serial Port on Startup]]

[[Advanced Serial Debugging Guide]]

== GUI ==

[[BOOPSI Gadget Help Strings]]

[[BOOPSI Popup Menus - Part 1]]

[[BOOPSI Popup Menus - Part 2]]

[[BOOPSI Popup Menus - Part 3]]

[[Screen Programming]]

== AmiWest 2014 ==

[[AmiWest Setup]]

== AmiWest 2013 ==

[[AmiWest 2013 Programming Conference Synopsis]]

[[AmiWest Setup]]

[[AmiWest 2013 Lesson 1|AmiWest Lesson 1: How to Crash]]

[[AmiWest 2013 Lesson 2|AmiWest Lesson 2: Interpreting Crash Reports]]

[[AmiWest 2013 Lesson 3|AmiWest Lesson 3: ProcTree Redux]]

[[AmiWest 2013 Lesson 4|AmiWest Lesson 4: Simple IP Clients & Servers]]

[[AmiWest 2013 Lesson 5|AmiWest Lesson 5: Bars&Pipes Tools]]

== AmiWest 2012 ==

[[AmiWest Setup]] [https://dl.dropboxusercontent.com/u/680455/AmiWest-2012-Programming/Introduction-360.mp4 - Video]

[[AmiWest Lesson 1|AmiWest Lesson 1: Coding Basics]] [https://dl.dropboxusercontent.com/u/680455/AmiWest-2012-Programming/Lesson01-360.mp4 - Video]

[[AmiWest Lesson 2|AmiWest Lesson 2: AmigaOS Fundamentals]][https://dl.dropboxusercontent.com/u/680455/AmiWest-2012-Programming/Lesson02-360.mp4 - Video]

[[AmiWest Lesson 3|AmiWest Lesson 3: Input and Output]][https://dl.dropboxusercontent.com/u/680455/AmiWest-2012-Programming/Lesson03-360.mp4 - Video]

[[AmiWest Lesson 4|AmiWest Lesson 4: ProcTree]][https://dl.dropboxusercontent.com/u/680455/AmiWest-2012-Programming/Lesson04-360.mp4 - Video]

[[AmiWest Lesson 5|AmiWest Lesson 5: MIDI]][https://dl.dropboxusercontent.com/u/680455/AmiWest-2012-Programming/Lesson05-360.mp4 - Video]

[[AmiWest Lesson 6|AmiWest Lesson 6: Application Library - Not Presented]]

[[AmiWest Lesson 7|AmiWest Lesson 7: Screen Blanker]][https://dl.dropboxusercontent.com/u/680455/AmiWest-2012-Programming/Lesson07-360.mp4 - Video]

[[AmiWest Lesson 8|AmiWest Lesson 8: ARexx Ports]][https://dl.dropboxusercontent.com/u/680455/AmiWest-2012-Programming/Lesson08-360.mp4 - Video]

[[AmiWest Support]][https://dl.dropboxusercontent.com/u/680455/AmiWest-2012-Programming/Wrap-Up-360.mp4 - Video]

AmiWest 2013

2014-09-23T07:38:23Z

Brian Deneen: /* AmiWest 2013 page deleted */

Tutorials:Main

2014-09-23T07:35:57Z

Brian Deneen: /* Tutorials - AmiWest 2013 restored */

AmiWest 2013

2014-09-23T07:26:15Z

Brian Deneen: /* AmiWest 2013 page restored */

[[AmiWest 2013 Programming Conference Synopsis]]

[[AmiWest Setup]]

[[AmiWest 2013 Lesson 1|AmiWest Lesson 1: How to Crash]]

[[AmiWest 2013 Lesson 2|AmiWest Lesson 2: Interpreting Crash Reports]]

[[AmiWest 2013 Lesson 3|AmiWest Lesson 3: ProcTree Redux]]

[[AmiWest 2013 Lesson 4|AmiWest Lesson 4: Simple IP Clients & Servers]]

[[AmiWest 2013 Lesson 5|AmiWest Lesson 5: Bars&Pipes Tools]]

Tutorials:Main

2014-09-23T06:55:13Z

Brian Deneen: /* AmiWest 2014 */

= Tutorials =

Tutorials have been provided by various authors.

== General ==

[[The Hacking Way: Part 1 - First Steps]]

[[The Right Tool for the Job (Shared Objects)]]

[[How to Build Stubs for 68k Libraries]]

== Debugging ==

[[How to install a hardware interrupt]]

[[How to open and use the exec debug interface]]

[[GDB for Beginners]]

[[Using Crash-Logs for Debugging]]

[[Debug Logging on AmigaOS]]

[[Redirecting Debug Output to the Serial Port on Startup]]

[[Advanced Serial Debugging Guide]]

== GUI ==

[[BOOPSI Gadget Help Strings]]

[[BOOPSI Popup Menus - Part 1]]

[[BOOPSI Popup Menus - Part 2]]

[[BOOPSI Popup Menus - Part 3]]

[[Screen Programming]]

== AmiWest 2014 ==

[[AmiWest Setup]]

== AmiWest 2012 ==

[[AmiWest Setup]] [https://dl.dropboxusercontent.com/u/680455/AmiWest-2012-Programming/Introduction-360.mp4 - Video]

[[AmiWest Lesson 1|AmiWest Lesson 1: Coding Basics]] [https://dl.dropboxusercontent.com/u/680455/AmiWest-2012-Programming/Lesson01-360.mp4 - Video]

[[AmiWest Lesson 2|AmiWest Lesson 2: AmigaOS Fundamentals]][https://dl.dropboxusercontent.com/u/680455/AmiWest-2012-Programming/Lesson02-360.mp4 - Video]

[[AmiWest Lesson 3|AmiWest Lesson 3: Input and Output]][https://dl.dropboxusercontent.com/u/680455/AmiWest-2012-Programming/Lesson03-360.mp4 - Video]

[[AmiWest Lesson 4|AmiWest Lesson 4: ProcTree]][https://dl.dropboxusercontent.com/u/680455/AmiWest-2012-Programming/Lesson04-360.mp4 - Video]

[[AmiWest Lesson 5|AmiWest Lesson 5: MIDI]][https://dl.dropboxusercontent.com/u/680455/AmiWest-2012-Programming/Lesson05-360.mp4 - Video]

[[AmiWest Lesson 6|AmiWest Lesson 6: Application Library - Not Presented]]

[[AmiWest Lesson 7|AmiWest Lesson 7: Screen Blanker]][https://dl.dropboxusercontent.com/u/680455/AmiWest-2012-Programming/Lesson07-360.mp4 - Video]

[[AmiWest Lesson 8|AmiWest Lesson 8: ARexx Ports]][https://dl.dropboxusercontent.com/u/680455/AmiWest-2012-Programming/Lesson08-360.mp4 - Video]

[[AmiWest Support]][https://dl.dropboxusercontent.com/u/680455/AmiWest-2012-Programming/Wrap-Up-360.mp4 - Video]

UserDoc:Main

2013-04-19T01:10:22Z

Brian Deneen: /* Welcome to AmigaOS */ Minor grammatical and phrasing changes to make the page read more smoothly.--~~~~

== Welcome to AmigaOS ==

AmigaOS was born in 1985 and delivered what contemporary personal computer operating systems could only dream of. As the first "multimedia" operating system, it was trivial for AmigaOS computers to display animations while playing music and reading data from disks. Such multimedia and multitasking finesse drew many people to this system. Some of them are famous: [http://www.amigahistory.co.uk/warhol.html Andy Warhol], Sir Arthur C. Clarke, [http://www.polyphoto.com/upchug/AEcastro.html NASA], Hollywood and the TV broadcasting industry, and many others that thought [http://www.youtube.com/watch?v=PWeO5IkCssk only Amiga makes it possible].

Today many people still think AmigaOS has something special that makes it more interesting and rewarding than other systems. This system allows the user to control the computer, not the other way around. It is a system you fully understand that is easier and more flexible to use. In other words, AmigaOS is '''more fun'''.

=== AmigaOS: The flexible operating system ===
AmigaOS is an operating system: a collection of efficient programs written to start the computer, let the user control the computer, and present feedback to the user.

AmigaOS is designed with ease of use and flexibility in mind. To begin with, AmigaOS provides a clear view of your computer, your applications and files. A number of methods are available to let your computer serve you, whether graphically with a mouse, using the "Shell" command line, or by some other means the user prefers.

AmigaOS strives to avoid stupid limitations that can be found on other systems. AmigaOS users can organise their files the way they like. There are few limits on file hierarchy, locations and file names. Drives don't have to be named with a letter or cryptic names (such as C:, or sda1), your files don't have to reside in your "Documents" folder and your hard drives aren't hidden from you. If you're not writing to drives and you want to "shut down", why wait for the OS to allow that? With AmigaOS, just hit the power switch. Done.

An Amiga does not start with pre-installed applications serving some sales conglomerate, marketing organization or their big brother. AmigaOS does not do actions behind the user's back. As unique as it is today, the AmigaOS computer serves the user and not the other way around. With one of the largest proportions of user-programmers around, the trustworthy AmigaOS user-friendly ethic is mirrored in AmigaOS applications.

Since the first versions more than twenty-five years ago, AmigaOS has also been designed to serve efficiently. Optimizing applications and OS code has always been the goal of programmers and developers of this operating system. The result is an operating system and applications that take less space on your hard drives, waste less time loading, consume less memory, require less processing power, and respond more quickly to the user.

And every update of AmigaOS doesn't demand you must buy newer, more powerful hardware. AmigaOS currently runs on twenty year old 200MHz computers or brand new dual core 1,800MHz computers. It's the user's choice how they want to '''enjoy''' AmigaOS.

=== Some AmigaOS features ===
Here are some of the features of AmigaOS that make it easy to control your computer. Some of these concepts were copied by other operating systems which tend to show they are the correct way of doing things.

* '''Small footprint:''' AmigaOS can work with 64 MB of memory. On disk, a default installation only takes around 200 MB. The smaller footprint translates into a more responsive user experience given any hardware.

* '''Straightforward operating system design:''' With a clear layout and easy to understand names (Classes, Libs, Fonts, Prefs, Storage, etc.), you can easily understand what everything in AmigaOS is and what it does for you. Nothing is hidden from the user and the user is not restricted by AmigaOS.

*'''User configurable graphic interface:''' Using the provided "preferences editors," the user can dramatically reconfigure how AmigaOS looks, sounds, runs and responds to every user whim.

* '''File recognition based on file content:''' You can name a file '''whatever you want''', even without an extension. Examples: "my file" or "picture of Jay in Santa Clara". There is no need to add an extension to explain what the file is, like ".txt" or ".jpg". AmigaOS really examines the '''file content''' to recognise what type of file it is.

* '''Logical assignments:''' Easily set and use logical names names for directories located anywhere on your system. For example, "Auto:" can point to your directory "car show pictures" buried on your media drive.

* '''Ram disk concept:''' On AmigaOS there is a special disk called the '''Ram disk''' which represents a part of your computer memory. This area is not fixed. It automatically grows whenever you store files in it. For example, it's a great place to unpack files to install from there, greatly speeding up the installation.

* '''Command line and graphical user interfaces:''' Both the the graphical user interface (GUI) and command line interface (where you type commands into a window with the keyboard) can be used to manage AmigaOS, its programs and files. Both interfaces are intergated with each other so you can easily use command lines from the GUI or open graphical elements from a command line.

*'''ARexx Ports:''' Throughout AmigaOS and third party programs, "ARexx" message ports let one application talk with others so that apps work together to serve the user. AmigaOS also provides the lightweight ARexx and modern Python programming languages that can control AmigaOS and applications with ARexx ports.

* '''Resident Commands:''' Commands can be made resident, i.e., they are kept in memory so that they can be reused with no loading time.

* '''Restart only the operating system:''' if you feel the need to restart the system, you can do so by restarting '''only AmigaOS''' and not the whole computer.

=== AmigaOS platform targets ===

While the original versions of AmigaOS ran on computers of the eighties using Motorola 68k series CPU chips, the current AmigaOS runs on computers using PowerPC processor chips [http://www.amigaos.net/content/72/supported-hardware hardware]. These can be older Amiga computers (also called "Classic Amigas") with PPC "accelerator cards" or new generation Amiga PPC computers.

In this guide, we will concentrate on the current AmigaOS running on the supported hardware.

== How does AmigaOS work? - Concepts ==

In this page we will discuss [[UserDoc:How AmigaOS Works|how AmigaOS works]]:

* [[UserDoc:How_AmigaOS_Works#The_most_important_components|The most important components]] (Exec, AmigaDOS, Intuition...)
* [[UserDoc:How_AmigaOS_Works#How_is_my_data_stored.3F|how files and data are stored]]
* [[UserDoc:How_AmigaOS_Works#All_AmigaOS_components|all AmigaOS components are described]]
* [[UserDoc:How_AmigaOS_Works#AmigaOS_boot_procedure|how AmigaOS is booted on your Amiga computer]]
* AmigaOS settings programs
* ...

== How to use AmigaOS? ==

AmigaOS is a collection of components that oversee the computer hardware & data and provide the user with easy, understandable tools to manage and use them.

In the following [[UserDoc:Introduction to AmigaOS|Introduction to AmigaOS pages]] we will discuss the basic concepts:

* how to use AmigaOS
* what the AmigaOS graphic user interface is composed of
* what interfaces AmigaOS provides, including the [[UserDoc:Workbench|Workbench]], the [[UserDoc:Shell|Shell]] or scripting languages.

From the introduction page, you can continue with more detailed pages on the [[UserDoc:Workbench|Workbench]] and the [[AmigaDOS manual]] . Now let's start with this [[UserDoc:Introduction to AmigaOS|Introduction to AmigaOS]].