# $Id: sound_db.txt 33336 2006-10-12 08:07:50Z lslezak $
# module: po/y2d_snd
# author: dan meszaros <dmeszar@suse.cz>
#

Sound card database design
==========================

1. Overview
===========

database is used for storing data for every piece of
supported hardware. it contains autogenerated data
(like device and vendor ids, paramerer description etc)
plus some manually added data (volume for nonstandard
mixer channel needed for proper card initialization etc).

database is placed in /usr/share/YaST2/data/sndcards.ycp on 
installed system.

2. Database structure
=====================

the whole database is ycp map, you just need to call 
SCR::Read(.target.ycp, "sndcards.ycp")

the topmost map contains keys:

    1) cards
    2) indices
    3) mod_idx
    4) modules

2.1 cards
=========

value is map. for each alsa kernel module (as key) it 
contains list of names of cards supported by this module.
this list is needed for manual sound card config in yast2-sound
(legacy isa cards etc.)
the module name is substituted by the module index (just 
to save space, this policy is used in mode places in db).
see 2.3 for details.

2.2 indices
===========

value is nested map. this part is used for searching the 
appropriate module for device_id/vendor_id pair. when looking
up for module for a card, first check out the map indexed by vendor_id.
you'll get map whose indices are device_ids and the value
is index to 'mod_idx' where you obtain the module name (string).

2.3 mod_idx
===========

leaves of 'indices' data structure are very redundant, i've 
decided to substitute the (string) module names by their indices.
value of mod_idx is map with numerical index as a key and the module
name as a value. this database is stored in src/module_index.ycp file

2.4 modules
===========

this structure contains map with module name as key and map of data
as value.

keys: 
    description (string):   used in 'manual card selection' dialog
    name (string):	    !optional. used in very special cases. see appendix A
			    usually the module name is used as a default.
    joystick (map):	    sound-driver-sensitive joystick settings
			    see ./joystick_db.txt
    mixer (map):	    some cards have special channels that needs to be
			    unmuted/set when initialized.
			    key is channel name, value means volume for this channel.
    main_volume (string)    name of the 'Master' volume element. this channel is
			    used in 'volume' dialog. this is always 'Master' (default)
			    except some PPC where the name is ... (huh i forgot..
			    probably 'Master Digital' or similar)
    params (map):	    parameters for module. module name is key in this map,
			    value is map with other data:
	    allows (string) possible values for option (if known). this string
			    has special syntax, see appendix B for details
	    default (string) default value fot this option
	    descr (locale/list) human readable desrciption for the option. 
			    if descr is list, it is sformated.
	    dialog (string) widget to be used for setting this option (not used
			    currently)
	    base (string)   ? (not used currently)
	    
3. database autogeneration
==========================

generator sources are in source/sound/data/src/
to rebuild the database, just do:

    cd source/sound/data/
    export Y2DIR=.
    make -f Makefile.generate clean	# remove the old DB
    make -f Makefile.generate		# generate the new one

this will generate db and copy it to sndcards.ycp 

NOTE: no changes should be done to po/y2d_snd/po/sound_db.ycp.generated
they will be overwriten by the next generation!! see chapter 4. for details
about how to add stuff manually to the database.

  Proofread (fixed) text should be included in 'proofread_strings' file. The
file contains lines with original and proofread text, syntax is:
"original text" "proofread/modified text"


NOTE: use i386 arch for building the database, don't use Xen kernel - some ALSA
drivers are missing in Xen kernel, the databe would not be complete!

3.1 files used for db generation
================================

alsa-module-syntax	- contains allowed values module parameters
proofread_strings	- contains text replacements (proofread messages)

Descriptions of module parameters are read using modinfo utility.

4. supplying data manually
==========================

these 4 files are stored in addons/ dir.

card_addons.ycp: additional sound cards (not listed in modules.genertic_string file)
id_addons.ycp:   additional vendor/device ids. the problem was, that modules that 
	         are used on other architectures are not in /lib/modules/.../ on i386
		 (and vice versa- the db MUST be generated on i386) so we know nothing
		 them.
joy_mods.ycp:	 for module name as key the value with joystick config is stored.
		 these data will be merged to 'modules' part of db.
mixer.ycp:	 strightforward
mod_addons.ycp:	 module entries that will be appended to the 'modules' map. typically
		 these are modules from other architectures + some exceptions. 
		 see appendix A


Appendix A
==========

see bug 6798. the thing is, that there is a card that is autodetected, but need
some params to be passed to the module. we cannot just add 'default=blabla' to each
option in 'modules->params' database, because this will break other cards that use that
module. this is fixed by adding the vendor/device id of this card to id_addons that will
tell us 'fake' module name (eg. 'snd-cs4236-modified). then we create a new module in 
module_index.ycp and module_addons, where we can safely supply all parameters this card
needs without breaking other cards.

Appendix B
==========

'allows' module options syntax

atoms: 
{0} stands for 0
{0,Disabled} is same as {0} (i don't know why this one was invented...)
{1,Enabled} same as {1} (ditto)
{0,5} stands for range 0,1,2,3,4,5
{0,6,2} stands for range with step 2: 0,2,4,6
{atom1,atom2} union of atom1 & atom2 is allowed

