Check for SYS/GL during library init. Reason is that
[AROS.git] / workbench / devs / audio / audio.device_readme
blobf6dad05a73735070935a90adbc80771983f2e81c
1 NOTICE(2010-06-26):
3 This is an original README file that acompanied the audio.device package. The
4 audio.device source codes has been freed and ported to AROS. The audio.device
5 source codes in AROS repository are distributed under AROS Public License.
7 Thanks go to Emanuele for feeing the codes!
8 http://www.gekoclimb.it/nexusdev/eaudio.device/index.html
10 "The eaudio.device source code may be downloaded here. I hope it will be usefull
11 to the community. There is no license or restriction about the use of the source
12 code. I would like only to be informed about the born of a new audio.device 
13 incarnation based on my code. That's enought!"
19                                                                 
20 ################################################################################################                
21                                                         
22                ###  #   # ####  ###  ###    ####  ##### #   # ###   ### #####  
23               #   # #   # #   #  #  #   #   #   # #     #   #  #   #    #
24               #   # #   # #   #  #  #   #   #   # #     #   #  #   #    #
25               ##### #   # #   #  #  #   #   #   # ####  #   #  #   #    ####
26               #   # #   # #   #  #  #   #   #   # #      # #   #   #    #
27               #   #  ###  ####  ###  ###  # ####  #####   #   ###   ### #####
29 ################################################################################################
31                                 Version 50.0 - 09.02.2004
33                                   /\/exus /)evelopment
40 Enhanced audio.device solution for MorphOS operating system
41 -----------------------------------------------------------
43 Developed by Emanuele Cesaroni of Nexus Development /\//)
44 (url = "http://www.genie.it/utenti/nexusdev")
45 (email = "emanuele.cesaroni@virgilio.it")
47 Index of this guide
48 -------------------
50 - Purpose
51 - Notices
52 - Requirements
53 - Installation
54 - How this works
55 - Compatibility
56 - Bugs
57 - Contacts
58 - Emulation approach
59 - Compatibility list
60 - To do
61 - History
67 Purpose
68 -------
69   The purpose of this device is to make fully compatibles with MorphOS all the programs written
70 in the past using the native audio.device which was thought to interact with the hardware audio
71 chips of the old 68k Amigas. This enhanced version of the audio.device redirects the commands to
72 the AHI device allowing to use the last generation of sound boards supported by the ahi system.
73   The device foresees all the audio.device's original commands: CMD_CLEAR, CMD_FLUSH, CMD_READ,
74 CMD_RESET, CMD_START, CMD_STOP, CMD_UPDATE, CMD_WRITE, ADCMD_ALLOCATE, ADCMD_FINISH, ADCMD_FREE,
75 ADCMD_LOCK, ADCMD_PERVOL, ADCMD_SETPREC and ADCMD_WAITCYCLE.
78 Notices
79 -------
80   The version you are using is still under development, so isn't in the final form. The project's
81 roadmap foresees to improve the device in the next releases. The first release is dated 11.2.2003
82 (version 50, revision 0). At beginning (early version 50) the device was compiled under GCC,
83 without any optimizations, in 68020+68881 code (so it wasn't PPC compiled yet).
84   In the next versions, after some debugging and testing, the code will be optimized and compiled
85 in fast PPC code. You can get the version device's number simply typing on shell:
87 "any_prompt> version devs:audio.device"
89 You will get a string as "audio.device xx.y" where xx is the version and the y the revision.
90 Probably the best is to run the test program enclosed in the device's archive (named 
91 audio.device_test) which outputs a lot of informations more. The program, if opens the device
92 successfully, prints a string as:
94 "audio.device 50.0 (02.10.03 - 68K) by Nexus Development 2003, written....".
96 or better if PPC compiled:
98 "audio.device 50.0 (02.10.03 - PPC) by Nexus Development 2003, written....".
100 "50.0" points to version.revision, so version 50 revision 0. Between brackets you have the
101 compiling date and if is compiled in 68K (68K) or PPC code (PPC).
102 Starting from version 50.0 dated october 2003 the code is fully PPC compiled.
105 Requirements
106 ------------
107   You need MorphOS running and a bit of harddisk space (about 200 KBytes) in your system's
108 partition. AHI device in version 4 minimum is strictly needed.
111 Installation
112 ------------
113   Simply copy the file "audio.device" to the "DEVS:" directory. Each time you want to update the
114 device with a new version or revision repeat the above passes replacing the "audio.device" file in
115 "DEVS:". Take care that after the first device use it could be loaded in ram where it becomes
116 resident. So to use the new installed one, when the old has been opened just only once, you need
117 to reboot the whole system. 
120 How this works
121 --------------
122   This audio.device when is opened for the first time performs these operations:
123 1) Creates a dos process (an exec superset slave task) which is responsable of all ahi.device
124    calls and is named "NexusDEV slave audio" (in version 50.0 with 127 as priority).
125 2) The slave process opens ahi.device and setups 4 message ports each one used for each audio unit
126    (from 0 to 3) to receive the CMD_WRITE commands.
128   So, for example, if a task opens the audio.device and wants to play a sample, allocates the
129 wanted channels combination (ADCMD_ALLLOCATE) and sends trought the device a CMD_WRITE command to
130 the slave process unit. The slave process converts the incoming audio io request into an ahi one
131 which will be sent to the ahi.device. When AHI returns the slave process returns the audio request
132 to the calling task.
134 **Important**
135   The device uses the AHI_DEFAULT_UNIT (unit 0). To get the best performances from the device in
136 conjunction with AHI set at least to 4 the number of channels field of unit 0 under the AHI main
137 preferences program. The equation is: more channels = better sound quality. 
139   
141 Compatibility
142 -------------
143   This audio.device is thought to be compatible with all the programs written using the OS instead
144 banging the hardware. Most coders used to lock (by ADCMD_LOCK) the channels to access directly
145 to the hardware audio registers. These programs are not compatible with this device but above all
146 with the entire OS. In this case you need of UAE. Refer to the "Compatibility list" and the "Emulation
147 Approach" sections.
148   
150 Bugs
151 ----
152   Because doesn't exist a native audio.device's source code available all the work done is based
153 upon an assumption derived from documents about the original audio.device operating method (reverse
154 engineering no disassembling). For this reason may be not compatible and most programs using it may
155 have problems. The debugging and the received reports about its usage in combination with certain
156 programs will allow to improve the whole project. Read the history log to get infos about the known
157 bugs.
161 Contacts
162 --------
163   To improve the device are wellcome impressions and reports about its behaviour. Please send them
164 writing to "emanuele.cesaroni@virgilio.it" using as email subject "AUDIO.DEVICE" please. Be more
165 precise as possible describing the problem you get, the program you was using with, the device
166 version and revision etc. If you are a developer of a program which uses the audio.device (and it
167 had always worked well) would be very appreciable if you test the app with my device reporting the
168 results and some infos more about the approach you had used coding.  
169   The device was written by Emanuele Cesaroni of Nexus Development (emanuele.cesaroni@virgilio.it).
170 You can find Nexus Development at "http://www.genie.it/utenti/nexusdev". 
171   Many thanks for your support...
174 Emulation approach
175 ------------------
176   The audio.device on the classic Amigas interacts with a physical piece of hardware, so with the 
177 well known Paula chip. Instead this enhanced audio.device interacts with AHI. For this reason 
178 even if AHI allows better performances the device is forced to be closer to the Paula own
179 performances. This allows a better emulation. This approach could give problem in certain 
180 situations. Here a list of them i found during the development.
182 1) The min period problem.
183   On all documents about Paula you can read that it supports a period range beetween 124 and
184 65536 clock's cycles per sample. You can ask less than 124 or more than 65536 but without get 
185 effects. This is an hardware limit which could not be surpassed. Even if AHI could supports very
186 lower period values i forced the device to work with 124 as minimum value. So if some coders,
187 in their programs, asked for values < 124 they won't be considered.     
188     
189    
191 Compatibility list
192 ------------------
193   The programs here listed were tested with the device. Their behaviour had seen regular in all
194 circumstances. The tests were done as deep as possible considering my aknowledgement with them.
195 Where you found a ! you can read some infos more about its behaviour. 
197 - ADoom v1.3
198 - AmigaOS v3.5 own sound preferences program (sound.datatype 40.6) 
199 - AmigaOS v3.1 own sound preferences program (sound.datatype 40.6)
200 - Amigenerator v0.34
201   ! The audio works but you heard a wait noise in the background. The only way to bypass the
202     problem is to run the program with the NOPSG option enabled. 
203 - Aqua
204 - Delitracker v2.32 
205   ! The program opens the audio.device to get the channels but after a CMD_LOCK it bangs the
206     hardware and then dies.
207 - DirectoryOpus v4.12
208 - DoomAttack 68k v1.10
209   ! The audio is ok but the video can't work properly on my machine.
210 - FroggerNG (68k and MorphOS versions)
211   ! Playing some videos the audio seems slow. This is due to the "Min period problem" about
212     what you can read in the "Emulation Approach" section. 
213 - MAME v0.34.3 (tested with very few roms)
214 - Miami v3.0d (sound.datatype 40.6) 
215 - MooVID v1.2 player on AmigaOS v3.5
216 - Multiview 45.9 (sound.datatype 40.6) 
217 - Payback 68k
218 - Ports of Call (game)
219 - Prayer v2.0
220   ! Not totally supported (needs a small change in sources) because bangs the hardware.
221 - PuzzleBOBS game v0.750 (in all its audio output modes)
222 - Rustle
223 - Samplitude Opus v3.5
224 - SongPlayer v1.4 (it opens the device to get the channels then bangs the hardware)
225 - WBClock v45.10 (sound.datatype 40.6) 
226 - YAM v2.3p1 (sound.datatype 40.6)
227 - Wipeout2097
228 - Xgb (Game boy emulator) 
232 To do
233 -----
235 1) Some commands as ADCMD_WAITCYCLE had never been tested by external apps (is very rare they are
236 used). They have been tested succesfully under the audio.device own test program only.
237 2) The device's init function probably touchs some register it shouldn't. Some programs (ADoom for
238 example) at first audio.device opening, stops forever after had opened the device. I think is due
239 to a stack or register problem. I am inquiring.
243 History
244 -------
246 (50.0 - 19.1.2004)
247 Some small changes to get Delitracker compatible at program starting and exiting. In any case Delitracker
248 bangs the hardware soon after an ADCMD_LOCK and on MorphOS it dies. If you don't play anything the program
249 exits well. Some fixes to the Slave Process init procedure too.
251 (50.0 - 17.12.2003)
252 Rewritten a small part of the builtin audio.device command (CMD_CLOSE) thought to die the slave process.
253 A fix now lets the device to work regularly with CMD_WRITE commands with more than one single cycle per
254 wave (ioa_Cycles) as it happens in "Ports of Call" game. Added again some semaphores where they are
255 strictly needed.
257 (50.0 - 15.11.2003)
258 After some tests i wrote again the linking protocol between the slave process and the main device unit.
259 Because the slave process **MUST** be synchronized with the device in certain situation were the data 
260 sharing model is not allowed i searched for a signal bit number which the slave process could use to
261 unlock the device waiting. The device infact sends the command to the slave process and soon after it 
262 waits for a signal while the slave process is touching some structures they can't manage in the same time.
263 When this lapse is ended the device is unlocked trought a signal. But which signal bit number use for
264 this controll exchange? Well, the own IORequest signal is not sufficent when a task sends command 
265 from more than one task. This is the example of Wipeout. It has two tasks, one opens the device and
266 waits for the commands end the other sends them only. Reply to the waiting one before the command is end
267 made a lot of confusion to the app which had a task completely locked. An other way i used in the past
268 was to alloc a signal for each Task the device receives command from. So i putted a copy of the pointer
269 of each of them in a list and when a command was received i went to see if a signal was just ready for that
270 task. If it was just allocated i used it for the linking procedure. This was a really big waste of time 
271 because at each command i had to do a long reasearch trought the list. So finally i adopted this method
272 which somebody could consider dangerous, but since today it has always worked. Simply when i receive an
273 IORequest i obtain its task pointer. I stole to it the CTRL_SIG_BREAKF signal and then i force it to wait
274 for this signal only. When the controll exchange is done i bring back the task's wait signal set to its
275 initial status. Hope this will work ever!  
276   
277 (50.0 - 2.10.2003)
278 A very long inactive time on this project. In this new release the device has been re-styled deeply
279 and the version was brought down again to the 50.0.
280 The most important changes of this re-styled version.
281 1) No more the FAKE and REAL operating modes difference. Now the device works only in REAL mode so it
282 outputs really the audio trought ahi.device which now is strictly needed al least in version v4. If
283 it isn't present on the system the device fails just in OpenDevice().
284 2) Erased totally the virtual channels system. Now there are only 4 channels, or better 4 units as the 
285 original audio.device had. The units are under the slave process control and each one has a message
286 port thought to receive CMD_WRITEs commands only. All the other commands are received by an other one
287 message port controlled by the slave process again.
288 3) No more IORequest mirroring but fast message handling between the device and the slave process.
289 4) Added the original audio.device's double buffering technique. When more than two CMD_WRITEs are sent
290 to the device the first is output, the second is put in a cache the others are inserted in a wait list.
291 This allows to start faster the second wave when the first is ended so the null audio lapse between them
292 is shorter for a better sound quality.
293 5) Rewritten all the commands functions. Now they are faster. Rewritten AbortIO() which was one of
294 the bigger problem of the past revisions. Now seems very stable and effectively functional.
295 6) Erased the old link system used to interact with the slave process. Actually is used the IORequest
296 own replyport and signal.
297 7) Rewritten BeginIO(), OpenDevice() and CloseDevice() internal routines and the slave process main
298 loop totally. Erased a lot of old code and complex procedures. The device now is smaller, simpler and
299 faster.
300 8) Erased all the semaphores used in BeginIO(), AbortIO() and in the OpenDevice() and CloseDevice()
301 internal functions.
303 (52.2 - 16.4.2003)
304 Not a new revision but a lot of few changes in the code to make it faster and more stable.
306 (52.2 - 10.4.2003)
307 A lot of improvements on this release. Rewritten TOTALLY AbortIO(). Now a lot of programs which 
308 gave problems in the past are working properly. Rewritten CMD_FLUSH and CMD_FINISH. Moreover
309 i modified the process priority. This may be dangerous but since i increase it all the programs
310 under testing are working better. The priority now is 127. Because the original audio.device worked
311 trought hardware interrupts is clear that a software device needs to be faster as possible in
312 replying to the programs.
314 (52.1 - 10.4.2003)
315 Modified the AHI starter. Actually i am using BeginIO() instead of SendIO(). This seems better in
316 certain circustances.
318 (52.0 - 7.4.2003)
319 Rewritten ADCMD_PERVOL. Actually it does a lot of usefull things. It modifies on channel the period
320 and volume as the classic audio.device used to do.
322 (51.9 - 4.4.2003)
323 Activated again the FAKE mode. It works as well as the REAL mode one. Rewritten some parts of code
324 which were not allowing to enable the -02 GCC optimization.
326 (51.8 - 2.4.2003)
327 Rewritten the system which manages, finds, allocs, frees the virtual channels. Actually the channel
328 struct at beginning has a node struct. This allows to move channels between lists without moving
329 data or copying structure fields for each audio output. Actually the exec.library/AllocSignal() not
330 checked is fixxed. When a task opens the audio.device its task's struct address is put in a list.
331 The list contains for the task a just allocated signal and some structs just ready to make faster
332 initializations and slave process message exchanging. Most part of the code was optimized erasing
333 function calls with quick memory array accesses (the case of the count chans routine). 
335 (51.7 - 28.3.2003)
336 Fixxed the NT_MESSAGE IOAudio node-type problem in BeginIO() so now most programs which use
337 CheckIO() now work (ADoom). Fixxed a bug in ADCMD_ALLOCATE when the task asks for a particular
338 channel key just known. Rewritten ADCMD_PERVOL even if actually it does nothing special more
339 than null. Added in this doc a program compatibility list. Tested with 12 channels and 4 programs
340 at 4 channels for each succesfully (only one didn't exit!).   
342 (51.6 - 22.3.2003)
343 Rewritten totally the system which manages lists. Verified, under Samplitude Opus, the CMD_STOP
344 and CMD_START. Now they work. Removed the FAKE mode part of code. It will be added again later 
345 recycling the REAL mode routines after the needed tests. So in release 51.6 the device works
346 exclusively in REAL mode. The whole is still 68k, not optimized.
348 (51.5 - 12.3.3003)
349 Rewritten the exit routines in the slave process. Actually the process is removed from the device
350 itself. Rewritten the device init functions which inits the slave process and an usefull semaphore. 
351 The tests under MorphOS actually are going well. No hits and no bad memory accesses.
353 (51.4 - 02.3.2003)
354 Fourth release. The device supports definitely AHI. The audio output is functional and good. I
355 tested it with my PuzzleBOBS game and it works. Rewritten the AbortIO() function so most of
356 programs which use it now work. The device now performs less operation during each audio
357 initializing for better performance.  
359 (51.3 - 20.2.2003)
360 Third release. Added some code for the REAL mode. The slave task actually is a process allowing
361 to open the ahi.device. The system opens AHI if it founds it. If not it swaps into FAKE mode.  
362 Actually is ready to work in REAL mode. Moreover the device was tested with 8 channels and two
363 programs asking both for 4 channels. The test was successfull but in this release the number of
364 channels was brought to 4 maximum again. The whole is still GCC 68K compiled without any
365 optimizations. Under MorphOS all the hits to Ramlib are disappear (there were some not allowed 
366 memory accesses). 
368 (51.2 - 19.2.2003)
369 Fixxed the message link system beetween slave task and audio.device with the use of exec.library/
370 AllocSignal() and exec.library/FreeSignal(). The whole is now faster and the major problems of 
371 the second release seem solved. The problem about the bad count period now is fixxed even if it
372 result a bit longer than the real audio.device one. This time difference increases when there are
373 more than one cycle for wave. That is due to the work done by the slave process which loses time
374 initialiting again the timer.device each cycle. The optimization of the slave process main code
375 in conjunction with the adoption of the ppc code should reduce the problem. This version wont be
376 released. 
378 (51.1 - 15.2.2003)
379 Second release. Some bugs were removed and the whole is improved. Actually at opening and closing
380 (exec.library/OpenDevice() and exec.library/CloseDevice()) the problems present in the revision 0
381 are fixxed. Some RamLib's hits, but no gurus. All the resources are freed and generally the whole
382 seems working well. The bad count period is already present and sometimes when two task open it
383 at the same time, one of them results locked at opening and the other at closing.  
385 (51.0 - 11.2.2003)
386 First release. The device is ready but needs to be deeply tested. Actually is 68k, supports only
387 4 channels and works in FAKE mode. Sometimes it crashes. If you run the test program from shell
388 add some mem to stack before. This may rend it more stable. 
393 COPYRIGHT
394 ---------
395   All of the files in this archive are Copyright 2003 Nexus Development of Emanuele Cesaroni.
396 The contents of this archive are protected by Copyright laws and Nexus Development reserves all
397 of the rights on the files. It's forbidden to alter any of the files in this archive in any way
398 and/or to modify the archive itself. In no event shall Nexus Development liable for any direct or
399 indirect damages arising out of the use of the files in this archive. Redistribution of this
400 archive in part or in its entire form is permitted.
408 /\/exus /)evelopment