=Emulation Description Language 1.0=
EDL (Emulation Description Language) is an description language written in XML that is useful for describing software emulations of generic computer systems.

An emulation consists of a collection of devices. Each device represents a distinct physical entity, for example a floppy disk drive, a memory expansion, or a printer.

At a lower level, each device consists of a collection of components. A component is a reusable software component, for example RAM, a DMA controller or a CPU.

EDL stores the following information:

* It describes the wiring of components
* It describes the state of the components

==Definitions==
* This document uses quotes for indicating the start and end of a string.
* The resources folder is a folder containing emulation resource files. It is usually organized in the following way:
  - roms/ - Stores ROM images
  - images/ - Stores emulation images
  - sounds/ - Stores emulation sounds
* Images should be stored in PNG format
* Sounds should be stored in WAV format or OGG/Vorbis format
* Labels should be expressed in the native language of the device. If unclear, english should be used

==EDL Format==
EDL files can be stored stand-alone (for storing device descriptions), or packaged (for storing both device descriptions and state).

The standalone format consists of a file of extension ".xml". This file should store the EDL description.

The packaged format consists of a folder of extension ".emulation". This folder should contain an "info.xml" file for storing the EDL description. The folder 

might also contain component state files (e.g. for storing RAM content).

The packaged format can also be compressed using ZIP compression. All files in the archive (info.xml and component state files) should be stored at the ZIP root level, and the compressed ZIP file must have extension ".emulation". 

==EDL Tags==

==="edl"===
The EDL language is based on XML. The main XML element must be an "edl" element. This element has the following tags:

* version: Should be "1.0"
* label: The human-interface name of this emulation
* image: A path to an image of this emulation (relative to the "resources" folder)
* description: A human-interface description of this emulation (used in template/device selectors)
* options: Additional options (carries the emulation window position)

The "edl" element may only contain "device" elements.

==="device"===
Each "device" element corresponds to a physical device in the emulation.

The "device" element has the following tags:

* id: The id name of this device.
* label: The human-interface name of this device
* image: A path to an image of this device (relative to the "resources" folder)

The "device" element may contain "setting" elements.

==="inlet"===
An "inlet" element signals that a device's component is accepting an outlet.

It has the following tags:

* ref: The address of the property that holds the address of the other device's main component (used for communication)
* type: A connector name that must match the corresponding outlet. For example: "SerialPort"
* label: The human-interface name of this inlet. For example: "Video Connector", "Slot 2"
* image: A path to an image for this inlet (relative to the "resources" folder)

==="outlet"===
An "outlet" element signals that a device's components can be used for connecting 

defines an outlet for connecting this device to another device.

It has the following tags:

* ref: The address of the main component. This is used for communicating with this device
* type: A connector name that must match the corresponding inlet. For example: "SerialPort"
* label: The human-interface name of this outlet. For example: "Video Jack", "Port 1". Not required.
* image: A path to an image for this outlet (relative to the "resources" folder). Not required.

==="setting"===
A "setting" element defines a component's property that can be configured through the host user interface. It has the following tags:

* ref: The property address to be set with this setting
* type: One of the following: "checkbox" for properties that can be set  ("1") or unset("0"), "option" for properties that are one out of many, and "slider" for properties that can have a numeric value within a range.
* options: If the setting is of type "option", a comma-separated list of possible values (e.g. "None, Even, Odd"). If the setting is of type "slider", a comma-separated list of: minimum, step, maximum value. E.g. ("0.0, 0.01, 1.0" for a volume control). This tag is not used for checkbox settings.
* label: The human-interface name of this setting.

==="component"===
A "component" element defines a component. It has the following tags:

* name: The component name of this component
* class: The component class. This should match the name of the C++ class to be instantiated with the component.

A "component" element may contain "property", "data", "resource" or "connection" elements.

==="property"===
A "property" element defines a property which is set (through the OEComponent.setProperty call) when the emulation is instantiated, and get (through the OEComponent.getProperty call) when the emulation is about to be terminated. If the getProperty call returns false, the property is not modified.

I has the following tags:
* name: The name of the property
* value: The value of the property

==="data"===
A "data" element defines an array of binary user data which is set (through the OEComponent.setData call) when the emulation is instantiated, and get (through the OEComponent.getData call) when the emulation is about to be terminated. If the getData call returns false, no data is written.

I has the following tags:
* name: The name of the data
* src: A filename in the emulation package. The special symbol "${REF}" in the filename is replaced with the component's address, so unique names can be guaranteed.

==="resource"===
A "resource" element defines an array of binary resource data which is set (through the OEComponent.setResource call) when the emulation is instantiated.

It has the following tags:
* name: The name of the resource
* src: A filename in the resource folder.

==EDL Addresses==
The "ref" tags in the EDL description describes references to other components or properties with a EDL address. This address is constructed as follows:

[device{:}][component][.property]

==Architecture==
* EDL is inlet-centric. This means that it is the inlet component that is notified about a connected device. 
* EDL supports devices with more than one outlet.
* When deleting a device, a recursive deletion for all connected inlets should be performed first. Only then should the device's outlets be disconnected. A circularity check is performed to avoid loops.

==Event order==
The order of events for the lifetime of an EDL is:

* Components are created.
* Components's properties are configured (using the setter functions for values, refs and data).
* Components are initialized (through the init() call).

The order of events when saving an EDL file is:
* Component's properties are retrieved (using the getter functions for values and data).
* The EDL file is saved

The order of events when adding an EDL to an EDL file is:
* New components are created.
* New components's properties are configured (using the setter functions for values, refs and data).
* The EDL files are merged. New device names are chosen uniquely.
* Connection notifications are sent to the inlets that are connected to the new device.

The order of events when removing a device from an EDL file is:
* The devices connected to the device to be deleted are removed through recursion
* The components of the inlets that refer to the device to be deleted are notified that the component is disconnected. This is done with a OEComponent.connect(, NULL) value.
* The device's components are destroyed.
