This document is (C) 2003 Steffen Huber. If you use information provided inside this document, and manage to produce a working drive-specific driver description, you are (at least morally) obliged to mail me the driver along with a description of the hardware environment in which you have successfully used it. The latest version is always available via http://www.huber-net.de/cdbsup.htm Driver download will be available via http://www.huber-net.de/cdbdrv.htm V0.02 - suitable for CDBurn version 1.59beta8 How to write your own CDBurn driver =================================== This is a description of the currently available and supported configuration options in the new CDBurn "driver tweaking" interface. At the moment, mostly configuration options that were already available internally and were automatically selected dependant on the drive/interface used are now externally configurable. The configuration file is a bit cryptic at the moment and depends on the order of the configuration lines. This will be changed in the future. Keep in mind that to be able to fully understand all the implications of the configuration options you would need to know how the CDBurn source code exactly looks like. If you have difficulties understanding parts of the document, please ask on the CDBurn Smartgroups mailing list, or mail me at steffen@huber-net.de. It is always a good idea to start with a Default driver when producing your own, optimized driver. The Default driver should behave exactly like CDBurn behaved before the configurable driver was introduced. Restrictions ------------ Only the MMC driver is configurable, which means that people with old SCSI writers like Philips CDD2000/2600, HP4020/6020, Plasmon 4220, Teac CDR50S/55S, Sony CDU920/924/926/928/948 etc. won't be able to do anything useful with the driver configuration capability. I consider it extremely unlikely that this will change in the future. There are very little sanity checks active at the moment, and not all (or better: very few) of the defined possibilities are actually supported. I just wanted to make sure that the format does not need to be changed too soon and too often. CD Readers which are not also MMC CD Writers are not configurable. As you can mostly configure writing related stuff at the moment, this is not a great loss ;-) How drivers are loaded ---------------------- For every transport system, there is a directory available in !CDBurn.Drivers At the moment, the following transports are implemented: - SCSI - for SCSI drives and IDE drives with IDE-to-SCSI converters - Iyonix - for Castle's Iyonix PC (IDE) - APDL - for APDL and MicroDigital IDE interfaces and the Mico (IDE) - Simtec - for the Simtec IDE interface and the RiscStation machines (IDE) - Acorn - for Risc PC and A7000(+) internal interface (IDE) Each of those directories can contain an arbitrary amount of driver files. Drive-specific driver files are looked up "by name". The filename must exactly match the device information string of the drive with the blanks stripped. So a device which shows up as "SCSI:2 YAMAHA CRW-4260S" in CDBurn's writer menu would need a driver file named "YAMAHACRW-4260S". As a fallback, if the drive specific driver is not found, a generic driver called "Default" is used. If the default driver is also not found, some internal default settings will be used. The configuration dialogue shows which driver is used for the currently selected CD writer. The above scheme will soon be changed into something more flexible, less error-prone and generally nicer. How a driver file looks ----------------------- What follows is an example driver file - the Default SCSI driver. Each config line is preceded by several comment lines (introduced by #) which describe the options available. If a NOT SUPPORTED YET option is configured, writing will either fail, or the setting will be ignored, or other strange things might happen. So don't use it ;-) Note that the order of the configuration lines is critical, because CDBurn reads the config file sequentially (skipping all comment lines) and depends on the correct order of lines. This will change hopefully soon, when a MessageTrans style file will be used. Keywords are case sensitive! # Global settings # # BurnProof setting # # detect - look at the writer's configuration modepage to find out if the # drive supports BURN-Proof or an equivalent mechanism - if # BURN-Proof is supported, it is automatically activated during # write processes # # force - no matter what the detection says, enable BURN-Proof during write # process # # dont_use - no matter what the detection says, disable BURN-Proof during # write process. Might be useful to find out what writing speed # can be achieved without the BURN-Proof mechanism kicking in detect # Write Modepage type - this is an esoteric configuration, best to leave # it as "detect", as detection seems to be 100% reliable # # detect - automatically detect modepage style # MMC - force use of modepage according to MMC standard # NOT IMPLEMENTED YET # MMC_Short - force use of modepage according # NOT IMPLEMENTED YET detect # Disc at once setting - sets the preferred method of Disc at once writing # # SAO - use Cue-Sheet based session at once write method - this is the # only implementation currently available, and works for most SCSI # and very few IDE drives - there is a special section at the end # where some flags are specifiable for the writing process # PQ_DAO - use disc at once write method with client-generated PQ subcode # NOT IMPLEMENTED YET # RAW_DAO - use disc at once write method with client generated raw # P-W subcode - this would theoretically allow things like # CD+G, Karaoke CD and full support of CD-Text # NOT IMPLEMENTED YET # detect - tries to find out which disc at once method the drive supports # NOT IMPLEMENTED YET # none - disables disc at once writing completely (currently the only # option for most IDE drives and several SCSI drives) SAO # Settings relevant for Track at once, audio writing # # Speed setting mode # # failure_allowed - tries to set the drive speed, but does not cancel the # write operation if it fails # must_be_valid - only continues with the write operation if the speed # setting command is successful # NOT IMPLEMENTED YET # dont_try - speed setting is never called # NOT IMPLEMENTED YET failure_allowed # Settings for pause area before audio tracks - always set both settings # to "true" or "false"! # # true - try to set a new modepage with the updated pause before track # setting before starting to write the current track # false - always leave the default (150 blocks = 2 secs), never set a # new modepage between tracks in the writing process # # Note: some drives need the "false" setting at least during simulated # writes! false false # Track At Once Audio writing configuration # # Write Mode # # blocking - data will be written to the writer as soon as it is available, # i.e. if the writer's buffer is full and can't accept more # data, the writing is temporarily blocked until enough buffer # space is free. This operation mode might lead to timeout # issues, especially with IDE drives and slow writing speeds. # Use buffer-inspecting if possible. # buffer-inspecting - before writing data, the available free buffer space # is checked - the write operation is only executed # if enough space is available, avoiding possible # timeout issues. Beware: the call to find out the # available buffer space is not properly supported by # every drive! blocking # Multitasking setting for audio write operations # # true - should only be configured when "buffer-inspecting" mode # is used. Tries to multitask if there is not enough buffer # space available for the next write operation. # false - no multitasking false # Amount of blocks written at once - this setting is independant of the # "continuously read/written blocks" configuration option - the config # option configures how many blocks are read/written at once from/to # the harddisc, while this setting configures how many blocks are written # at once to the writer. This setting is important because some # interface/writer configurations only work with specific data sizes to # be written, mostly related to timeout issues and firmware bugs. A # higher number might make the writing process a tiny bit more efficient # (especially in buffer-inspecting mode). 16 # Empty drive cache method - after the data for each track is written, # the buffer of the drive needs the be emptied/flushed. There are # several ways to do that: # # blocking - actively calls the mmc command "synchronize cache" which # blocks until the cache is completely empty # timed - waits for a certain period of time until the drive has hopefully # flushed its cache # buffer-inspecting - inspects the drive's buffer state to find out when # the cache is flushed blocking # Multitasking setting for cache flush/close track # true - should only be configured when "buffer-inspecting" or "timed" # mode is used. Tries to multitask during waiting for the drive # to empty its cache # false - no multitasking false # Fixation settings for audio CDs # # Fixation method # blocking - fixation command is called in "blocking" mode, i.e. it only # finishes once fixation is finished. # timed - fixation command is called in "background" mode, i.e. it # returns immediately. CDBurn then tries to call TestUnitReady # frequently (every 2-3 seconds or so) to find out when the # drive has finished fixation. # NOTE some drives immediately pretend to be "ready" when # TestUnitReady is called. CDBurn then tries to open the drawer # and fails, because the drive suddenly realises that it is not # really ready. CDBurn then tries to open the drawer repeatedly, # but this process is *not* multitasking at the moment! blocking # Multitasking setting for audio fixation # # true - should only be configured when "timed" mode is used. Tries to # multitask during fixation. # false - no multitasking false # Settings relevant for Track at once, data writing # # Speed setting mode # # failure_allowed - tries to set the drive speed, but does not cancel the # write operation if it fails # must_be_valid - only continues with the write operation if the speed # setting command is successful # NOT IMPLEMENTED YET # dont_try - speed setting is never called # NOT IMPLEMENTED YET failure_allowed # Track At Once Audio writing configuration # # Write Mode # # blocking - data will be written to the writer as soon as it is available, # i.e. if the writer's buffer is full and can't accept more # data, the writing is temporarily blocked until enough buffer # space is free. This operation mode might lead to timeout # issues, especially with IDE drives and slow writing speeds. # Use buffer-inspecting if possible. # buffer-inspecting - before writing data, the available free buffer space # is checked - the write operation is only executed # if enough space is available, avoiding possible # timeout issues. Beware: the call to find out the # available buffer space is not properly supported by # every drive! blocking # Multitasking setting for data write operations # # true - should only be configured when "buffer-inspecting" mode # is used. Tries to multitask if there is not enough buffer # space available for the next write operation. # false - no multitasking false # Amount of blocks written at once - this setting is independant of the # "continuously read/written blocks" configuration option - the config # option configures how many blocks are read/written at once from/to # the harddisc, while this setting configures how many blocks are written # at once to the writer. This setting is important because some # interface/writer configurations only work with specific data sizes to # be written, mostly related to timeout issues and firmware bugs. A # higher number might make the writing process a tiny bit more efficient # (especially in buffer-inspecting mode). 16 # Empty drive cache method - after the data for each track is written, # the buffer of the drive needs the be emptied/flushed. There are # several ways to do that: # # blocking - actively calls the mmc command "synchronize cache" which # blocks until the cache is completely empty # timed - waits for a certain period of time until the drive has hopefully # flushed its cache # buffer-inspecting - inspects the drive's buffer state to find out when # the cache is flushed blocking # Multitasking setting for cache flush/close track # true - should only be configured when "buffer-inspecting" or "timed" # mode is used. Tries to multitask during waiting for the drive # to empty its cache # false - no multitasking false # Fixation settings for data CDs # # Fixation method # blocking - fixation command is called in "blocking" mode, i.e. it only # finishes once fixation is finished. # timed - fixation command is called in "background" mode, i.e. it # returns immediately. CDBurn then tries to call TestUnitReady # frequently (every 2-3 seconds or so) to find out when the # drive has finished fixation. # NOTE some drives immediately pretend to be "ready" when # TestUnitReady is called. CDBurn then tries to open the drawer # and fails, because the drive suddenly realises that it is not # really ready. CDBurn then tries to open the drawer repeatedly, # but this process is *not* multitasking at the moment! blocking # Multitasking setting for fixation # # true - should only be configured when "timed" mode is used. Tries to # multitask during fixation. # false - no multitasking false # DAO section - new for versions 1.59beta8 and later # # write preparation - speed setting mode, see above failure_allowed # write style, multitasking, amount of blocks written@once - see above buffer-inspecting true 32 # finish disc audio settings - empty drive cache method, multitasking # see above blocking true Typical problems and their solution ----------------------------------- By far the most problematic area is the writing process when multiple tracks are involved (Track at once audio CD creation). Both the finishing process for the track itself (synchronize cache, close track) and the setup for the following track are often critical areas. This is made even worse by the fact that an ever growing group of drives behave totally different during simulation than during real write. Future versions of the driver description file will therefore contain a special section for simulation configuration. In the meantime, you should really concentrate to get "real writing" working, and use CD-RW media for tests to minimze your financial losses ;-) The problem area described above is mostly IDE related. A typical "safe" IDE default for the Audio TAO section should be: ... # Settings for pause area before audio tracks - always set both settings # to "true" or "false"! false false # Track At Once Audio writing configuration # # Write Mode blocking # Multitasking setting for audio write operations false # Amount of blocks written at once 16 # Empty drive cache method timed # Multitasking setting for cache flush/close track false # Fixation method timed # Multitasking setting for audio fixation false ... SCSI devices are typically happy with blocking operations, so you might only need to set the two "pause area" flags to "false" to get your drive going - the Default SCSI driver is already such a "safe" driver. Performance optimization ------------------------ First of all, you have to think about the type of performance you are trying to optimize. If you want to go for minimized writing time, you should use a "blocking" writing mode (so no multitasking can be involved either) and the largest "amount of blocks written at once" setting your interface/drive can handle (usually, more than 64 is not sensible). You should also reserve enough buffer memory for CDBurn (see the file !CDBurn.memory) and set the "continuously read/written blocks" to the maximum amount allowed (which is - surprisingly - the same as the number configured in !CDBurn.memory ;-)). If you want to go for best multitasking performance, use a mediocre value for "continuously read/written blocks" like 128 or 256 (this translates to the loading of 256 or 512 KB of data "at once" from the harddisc, which is a blocking operation and therefore would disturb multitasking perception if it took too long), and values like 16 or 32 for "amount of blocks written at once" - this amount should not be too small (because the writing operation to the drive has a certain overhead, as well as the buffer state inspection, so you might end up with the buffer always big enough to directly write the next small block of data, without a Wimp Poll call, effectively disabling multitasking), and it should not be too big (because writing to the writer is also a blocking operation, and multitasking is only kicking in if the buffer state inspection reports not enough free space in buffer). Your choice. Keep in mind that filing system performance vastly differs for different block sizes, so what might be an ideal setting in conjunction with a Blitz interface might be not so ideal when using an Iyonix setup. I have created a working driver for my drive - what can I do now? ----------------------------------------------------------------- Send it to steffen@huber-net.de. It will then be put into the next distribution of drivers. Future extensions ----------------- It is expected that the driver description will be extended in the future, just because there are so much more slight and not-so-slight variations in driver operation sensible. The format described above is therefore a moving target. This is the reason why you should really send me all the drivers you have created - I will automatically convert them to any new format that might be used in the future. Some features of the driver configuration file might be moved to the CDBurn configuration dialogue in the future, depending on how useful they are to the average user. The only thing already there is the BURN-Proof configuration.