-
Notifications
You must be signed in to change notification settings - Fork 18
/
Copy pathThe libemulation Book.txt
147 lines (103 loc) · 7.69 KB
/
The libemulation Book.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
=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.