diff --git a/doc/libdax_equip.gif b/doc/libdax_equip.gif new file mode 100644 index 0000000..3df86ae Binary files /dev/null and b/doc/libdax_equip.gif differ diff --git a/doc/libdax_job.gif b/doc/libdax_job.gif new file mode 100644 index 0000000..8138ad2 Binary files /dev/null and b/doc/libdax_job.gif differ diff --git a/doc/libdax_model.txt b/doc/libdax_model.txt new file mode 100644 index 0000000..6c7c176 --- /dev/null +++ b/doc/libdax_model.txt @@ -0,0 +1,658 @@ + +# Originally this was a backup of text input clicketitoggled into ArgoUML +# Meanwhile it becomes an intermediate storage for attributes and +# class interconnections in the notation of my C stub generator CgeN +# (see also end of this text) + + +Model=libdax + +ClassDiagram=Overview + +Class=API +Author=Thomas Schmitt +Version=1.0 +Since=11.03.2007 +Documentation=\ +The API is the only layer visible to the applications. It exposes MMC concepts +which it reflects and augments by its own architectural concepts. +Subordinates=EQUIP,JOB,AUX +Cgen=\ +cevapi +-m struct CevapeqP *equip +-m struct CevapjoB *job +-m struct CevapauX *aux +-m struct CevapgsT *gestures +@ +=end Class + +Class=EQUIP +Author=Thomas Schmitt +Version=1.0 +Since=11.03.2007 +Documentation=\ +EQUIP represents the physical and logical equipment in reach of libdax. +This includes the system, drives, media, and their current states. +PeerToPeer=GESTURES +Boss=API +Cgen=\ +cevapeqp +-v struct CevapI *boss +-m struct CevapeqpsyS *sys +@ +=end Class + +Class=JOB +Author=Thomas Schmitt +Version=1.0 +Since=11.03.2007 +Documentation=\ +JOB models the tasks to be performed via libdax. +This includes disc, session, track, source, fifo, dewav, burn options. +PeerToPeer=GESTURES +Boss=API +Cgen=\ +cevapjob +-v struct CevapI *boss +-m struct CevapjobtdO *todo +# >>> +@ +=end Class + +Class=AUX +Author=Thomas Schmitt +Version=1.0 +Since=11.03.2007 +Documentation=\ +AUX bundles any models which are neither EQUIP nor JOB. +This includes abort handler and message system. +PeerToPeer=GESTURES +Boss=API +Cgen=\ +cevapaux +-v struct CevapI *boss +# >>> +@ +=end Class + +Class=GESTURES +Author=Thomas Schmitt +Version=1.0 +Since=11.03.2007 +Documentation=\ +GESTURES ist the procedural repertoire which interconnects EQUIP, JOB, and AUX +and also provides to them the services from the SCSI oriented layers. +PeerToPeer=EQUIP,JOB,AUX +Subordinates=SCSI_CMD +Cgen=\ +cevapgst +-v struct CevapI *boss +# >>> +@ +=end Class + +Class=SCSI_CMD +Author=Thomas Schmitt +Version=1.0 +Since=11.03.2007 +Documentation=\ +SCSI_CMD represents the semantic part of SCSI (i.e. mainly MMC) specs. +This layer models each SCSI command that is used by libdax. It knows about +its parameters and constraints with particular equipment and jobs. +Boss=GESTURES +Subordinates=Classes with SCSI_EXEC Interface +=end Class + +Interface=SCSI_EXEC +Author=Thomas Schmitt +Version=1.0 +Since=16.03.2007 +Documentation=\ +SCSI_EXEC hides the difference between the implementation principle of +SCSI format+transport and the principle of SCSI service. +Boss=SCSI_CMD +Implementations=SCSI_FORMAT,SCSI_SERVICE +Cgen=\ +cevapsciexc +-v struct CevapscifmT *scsi_format +-v struct CevapscisvC *scsi_service +-v int silent_on_scsi_error +@ +=end Interface + +Class=SCSI_FORMAT +Author=Thomas Schmitt +Version=1.0 +Since=11.03.2007 +Documentation=\ +SCSI_FORMAT translates parameters of SCSI commands into CDBs, takes care for +transport and decodes the reply into parameters. +Boss=SCSI_CMD via SCSI_EXEC +Subordinates=SCSI_TRANSPORT +Cgen=\ +cevapscifmt +-v struct CevapsciexC *boss +-v struct CevapscitrN *scsi_transport +# >>> +@ +=end Class + +Class=SCSI_TRANSPORT +Author=Thomas Schmitt +Version=1.0 +Since=11.03.2007 +Documentation=\ +SCSI_TRANSPORT takes a formatted CDB from SCSI_FORMAT and makes the operating +system perform a SCSI transaction. It then returns the reply data in raw form. +Boss=SCSI_FORMAT +Os_specific=yes +Cgen=\ +cevapscitrn +-v struct CevapscifmT *boss +-v struct Burn_os_transport_drive_elementS *system_dep_drive_info +# >>> +@ +=end Class + +Class=SCSI_SERVICE +Author=Thomas Schmitt +Version=1.0 +Since=11.03.2007 +Documentation=\ +SCSI_SERVICE provides the combined services of SCSI_FORMAT and SCSI_TRANSPORT +via a set of parametrized functions which abstract SCSI command transactions. +Boss=SCSI_CMD via SCSI_EXEC +Os_specific=yes +Cgen=\ +cevapscisvc +-v struct CevapsciexC *boss +-v struct Burn_os_transport_drive_elementS *system_dep_drive_info +# >>> +@ +=end Class + +=end ClassDiagram=Overview + + + +ClassDiagram=Equip_overview + +Class=EquipSystem +Author=Thomas Schmitt +Version=1.0 +Since=16.03.2007 +Documentation=\ +EquipSystem is the inner root class of EQUIP. It describes the system on +which libdax is working. This includes the operating system, the system +adapter classes, the drives. +Boss=EQUIP +Subordinates=EquipDrive*N +Cgen=\ +cevapeqpsys +-v struct CevapeqP *boss +-m char *infotext +-l struct CevapeqpdrV *drives +-v struct CevapeqpdrV *eol_drive +# >>> be boss of SCSI_CMD ? +# >>> +@ +=end Class + + +Class=EquipDrive +Author=Thomas Schmitt +Version=1.0 +Since=16.03.2007 +Documentation=\ +EquipDrive represents a drive, including its capabilities, its processing +status, the media loaded. +Subordinates=EquipMedia +Boss=EquipSystem +Cgen=\ +-l cevapeqpdrv +-v struct CevapeqpsyS *boss +-m struct CevapeqpmdA *media +-m char *devname +-v int bus_no +-v int host +-v int id +-v int channel +-v int lun +-v int phys_if_std +-m char *phys_if_name +-v struct CevapsciexC *BURN_OS_TRANSPORT_DRIVE_ELEMENTS +-v int global_index +# >>> -v pthread_mutex_t access_lock +-v int current_feat2fh_byte4 +-v volatile int released + +# >>> next to process: transport.h : int complete_sessions +# >>> + +@ +=end Class + + +Class=EquipMedia +Author=Thomas Schmitt +Version=1.0 +Since=16.03.2007 +Documentation=\ +EquipMedia represents an optical disc, including its type, its writeability, +its formatting, its available formats and performances. +Subordinates=\ +EquipProfile*N,EquipFormat*N,EquipPerformance*N,EquipStatus,EquipMulticaps +Boss=EquipDrive +Cgen=\ +cevapeqpmda +-v struct CevapeqpdrV *boss +-m struct CevapeqpstA *status +-l struct CevapeqpprO *profiles +-v struct CevapeqpprO *eol_profile +-v int current_has_feat21h +-v int current_feat21h_link_size +-v int needs_close_session +-v int bg_format_status +-v int format_descr_type +-v off_t format_curr_max_size +-v unsigned int format_curr_blsas +-v int best_format_type +-v off_t best_format_size +-l struct CevapeqpfmT *format_descriptors +-v struct CevapeqpfmT *eol_format_descriptor +-v int nwa +-v int start_lba +-v int end_lba + +# >>> +@ +=end Class + + +Class=EquipProfile +Author=Thomas Schmitt +Version=1.0 +Since=16.03.2007 +Documentation=\ +EquipProfile maps a MMC profile into libdax (See mmc5r03c.pdf chapter 5). +A profile describes a set of features and may be either current, possible, +disabled, or unavailable. +Subordinates=EquipFeature*N +Boss=EquipMedia +Cgen=\ +-l cevapeqppro +-v struct CevapeqpmdA *boss +-v int profile_code +-v char *profile_text +-v int is_cd_profile +-v int is_supported_profile +-l struct CevapeqpftR *features +-v struct CevapeqpftR *eol_feature +# >>> +@ +=end Class + +Class=EquipFeature +Author=Thomas Schmitt +Version=1.0 +Since=16.03.2007 +Documentation=\ +EquipFeature maps a MMC feature into libdax (See mmc5r03c.pdf chapter 5). +A feature describes a set of SCSI commands and (implicitely) of use cases. +Boss=EquipProfile +Cgen=\ +-l cevapeqpftr +# >>> +@ +=end Class + +Class=EquipFormat +Author=Thomas Schmitt +Version=1.0 +Since= +Documentation=\ +>>> EquipFormat +Boss=EquipMedia +Cgen=\ +-l cevapeqpfmt +# >>> +@ +=end Class + +Class=EquipPerformance +Author=Thomas Schmitt +Version=1.0 +Since= +Documentation=\ +>>> EquipPerformance +Boss=EquipMedia +Cgen=\ +cevapeqppfm +# >>> +@ +=end Class + +Class=EquipStatus +Author=Thomas Schmitt +Version=1.0 +Since=17.3.2007 +Documentation=\ +EquipStatus represents the status of media and drive. This includes +blank/appendable/closed, progress indicator. +Boss=EquipMedia +Cgen=\ +cevapeqpsta +-v struct CevapeqpmdA *boss +-v int status +-m char *status_text +-v struct CevapeqpprO *current_profile +@ +=end Class + +Class=EquipMulticaps +Author=Thomas Schmitt +Version=1.0 +Since= +Documentation=\ +>>> EquipMulticaps +Boss=EquipMedia +=end Class + +# >>> need EquipDisc for describing the table of content +# >>> ??? Define AuxDisc class as common part of EquipDisc , JobDisc + +=end ClassDiagram=Equip_overview + + +ClassDiagram=Job_overview + +Class=JobTodo +Author=Thomas Schmitt +Version=1.0 +Since=18.3.2007 +Documentation=\ +JobTodo records what is to be done during a job. This includes peripheral +actions like tray load/eject and central actions like blank, format, burn. +Subordinates=JobDisc,JobOptions +Cgen=\ +cevapjobtdo +# >>> +@ +=end Class + +Class=JobDisc +Author=Thomas Schmitt +Version=1.0 +Since=18.3.2007 +Documentation=\ +JobDisc models a not yet existing disc structure which is to be created. +Subordinates=JobSession*N +Boss=JobTodo +=end Class + +Class=JobSession +Author=Thomas Schmitt +Version=1.0 +Since=18.3.2007 +Documentation=\ +JobSession represents a recording session. A session usually bundles +several tracks. Traditionally the last session of a disc is recognized +by operating systems as the thing to be mounted. +Subordinates=JobTrack*N,JobFifo +Boss=JobDisc +=end Class + +Class=JobTrack +Author=Thomas Schmitt +Version=1.0 +Since=18.3.2007 +Documentation=\ +JobTrack represents a track to be recorded. A track mainly is associated with +a data source but in many cases it also becomes a recognizable entity on the +target media. +Subordinates=JobBlock*N,JobTrackFilter,JobSource +Boss=JobSession +=end Class + +Class=JobBlock +Author=Thomas Schmitt +Version=1.0 +Since=18.3.2007 +Documentation=\ +JobBlock represents a single output data transaction unit. On CD this is +the same as an addressable media block resp. sector. On DVD this might be +an addressable block od 2k or a packet of e.g. 32k. +Boss=JobTrack +Cgen=\ +cevapjobblk +-v int alba +-v int rlba +# >>> +@ +=end Class + +Class=JobSource +Author=Thomas Schmitt +Version=1.0 +Since=8.4.2007 +Documentation=\ +JobSource represents a data source for a track. Typically this is a disk +file or a stream file descriptor like stdin. +Subordinates=JobSourceBlock*N +Boss=JobTrack +=end Class + +Class=JobSourceBlock +Author=Thomas Schmitt +Version=1.0 +Since=8.4.2007 +Documentation=\ +JobSourceBlock represents a single input data transaction unit. +Boss=JobSource +=end Class + +Class=JobFifo +Author=Thomas Schmitt +Version=1.0 +Since=8.4.2007 +Documentation=\ +JobFifo reads data via JobTrackFilter and buffers them until JobBlock can +accept them. +Boss=JobSession +=end Class + +Class=JobTrackFilter +Author=Thomas Schmitt +Version=1.0 +Since=8.4.2007 +Documentation=\ +JobTrackFilter reads data from JobSourceBlock, processes them and presents +them to JobFifo or JobBlock. This includes stripping of .wav headers. +Boss=JobTrack +=end Class + +Class=JobOptions +Author=Thomas Schmitt +Version=1.0 +Since=18.3.2007 +Documentation=\ +JobOptions bundles the adjustable parameters of a job. This includes dummy +mode, speed, appendability, blank mode, format selection, write mode, +underrun protection, random access addressing. +Boss=JobTodo +=end Class + +Class= +Author=Thomas Schmitt +Version=1.0 +Since= +Documentation=\ +=end Class + +=end ClassDiagram=Equip_overview + +# >>> a dummy to be integrated into the model +Cgen=\ +burn_os_transport_drive_elements +@ + + +=end Model=libdax + +---------------------------------------------------------------------------- +Notes: +---------------------------------------------------------------------------- + + Generate C stubs: + test_dir=...where_to_generate_the_stub... + model_dir=...where_to_find_the_model_file_libdax_model.txt... + xtr_dir=...where_to_find_the_extractor_script_extract_cgen_input.sh... + cgen_dir=...where_to_find_the_cgen_binary... + + /bin/rm "$test_dir"/cevap*.[cho] \ + "$test_dir"/burn_os_transport_drive_elements*.[cho] \ + "$test_dir"/a.out + cd "$test_dir"/ + cat "$model_dir"/libdax_model.txt | \ + "$xtr_dir"/extract_cgen_input.sh | \ + "$cgen_dir"/bin/cgen -no_stic -ansi -global_include cevap_global.h + + Compile: + ( cd "$test_dir" ; cc -g -c *.c 2>&1 | less ) + +---------------------------------------------------------------------------- +~/projekte/cdrskin_dir/libburn-develop/libcevap/extract_cgen_input.sh : + +#!/bin/sh + +copy_mode=0 + +while true +do + read line + if test "$copy_mode" = "0" + then + if echo " $line" | grep '^ Cgen=' >/dev/null 2>&1 + then + copy_mode=1 + if echo " $line" | grep '^ Cgen=..' >/dev/null 2>&1 + then + echo " $line" | sed -e 's/^ Cgen=//' + fi + elif echo " $line" | grep '^ =end Model=' >/dev/null 2>&1 + then +break + fi + else + if test " $line" = " @" + then + copy_mode=0 + echo "@" + else + echo " $line" | sed -e 's/^ //' + fi + fi +done + +---------------------------------------------------------------------------- + +Description of CgeN + +cgen produces a class stub in C programming language. The data structure of +the class is described by some lines which get read from stdin. The stub will +consist of two files .h and .c which emerge in the +current working directory. +It will define a struct for representing the class data aspects, +construtor _new(), destructor _destroy(), +getter __get() for each structure element. +Some more functions get added for particular class and element roles. + +After first generation, there is no further support by cgen. It simply refuses +to overwrite existing files because it supposes that those contain code added +by the human programmer. +Those programmer enhancements are supposed to include explanatory comments, +class specific methods, initial element values and other special precautions +within the generated functions. + + +Command line options + + -no_stic prevents usage of stic_dir/s_tools/*.[ch] + + -ansi generates ANSI C function heads and makes file .h hold + only public definitions: an opaque declaration of the class struct + and a list of function prototypes. The definiton of the class + struct is then in _private.h . + -global_include filename + sets the name of a file which will contain globally necessary + declarations. Currently it lists the existence of all class + structs. + +A class can have one of two roles: + +- Standalone class. + Input example: + my_class + +- Listable class, which has pointers to peer instances: .prev and .next + Such classes get a list destructor _destroy_all() which destroys + all members of a list (which is given by any of the list members). + There is a function _link() which inserts an instance into a list. + Input example: + -l my_class + +Elements have one of the following roles: + +- Value. It provides only storage for a C data type (which may be a C pointer + despite the role name "value"), a getter method __get(), + and a setter method __set(). + Input examples: + -v int i + -v int a[100] + -v char *cpt + -v struct xyz x + -v struct xyz *xpt + +- Managed. This has to be a pointer to a struct or to char. It will not + get attached to an object by the stub's code but its destructor + _destroy() will be called by _destruct(). In case of (char *) + it is supposed that a non-NULL value has been allocated by malloc(). + Managed (char *) types get a setter function __set() + which allocates memory and copies the textstring from its parameter. + Input examples: + -m struct XyZ *xyzpt + -m char *textstring + +- Chainlink. A pair of prev-next-style pointers to the own class struct. + Function _destruct() will unlink the affected instance and + put together its link partners. + Input example (there must always be two consequtive -c lines): + -c struct My_clasS *up + -c struct My_clasS *down + +- List. A pair of pointers to the struct of a listable class. The first + one holds the start of the list, the second one holds the end. + For insertion of list items there is provided method _new_(). + The inserted item is then content of the pointer. + _destroy() instance calls _destroy_all(). There is a method + _set_() which should be used with caution, if ever. + Input example (there must always be a -l and a -v line): + -l struct XyZ *list_start + -v struct XyZ *list_end + + +Example run: + + bin/cgen <<+ +-l class_x +-v int x +-m struct Class_Y *y +-m char *text +-c struct Class_X *boss +-c struct Class_X *slave +-l struct Class_X *providers +-v struct Class_X *last_provider +@ ++ + + diff --git a/doc/libdax_overview.gif b/doc/libdax_overview.gif new file mode 100644 index 0000000..f4e5715 Binary files /dev/null and b/doc/libdax_overview.gif differ