# 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 @ +