Chapter VII  CD-RTOS (Compact Disc Real-time Operating System)
  
  
  VII.1 Kernel
  
  1.1 General
  
  
  All application  programs issue  requests for  system services  
  through the CD-RTOS kernel. For detailed information about the  
  internal operations of the CD-RTOS  kernel, see Appendix VII.1  
  Chapters 1-4.
  
  Three types of  system services  are provided  by CD-RTOS. The  
  'user state' service requests provide application programs with 
  basic functions such as memory allocation, process scheduling,  
  and memory module management. The I/O service requests provide  
  device independent input/output facilities. Device drivers and  
  other operating system  components may use  the 'system state'  
  requests  to   perform  low-level   functions,  such   as  the   
  installation of  interrupt  service routines,  or  new service  
  requests.
  
  Chapters 16-18 of Appendix VII.1 contain detailed explanations  
  of all  the service  requests  available in  CD-RTOS.  A brief  
  summary of the service requests is presented here for reference. 
  Service requests in  Figure VII.1  indicated with  an asterisk  
  ('*') are explained in the following sections.
  
  
  
  
  1.1.1 CD-RTOS User State Service Request Summary
  
  
  All of the user state service requests available in CD-RTOS are 
  outlined in Figure VII.1 below.
  
                                                                                          
                           Figure VII.1                         
  _________________________________________________________________
  
  _        Name        _        Description        of        Use         
  _
  _________________________________________________________________
  
  _*F$Alarm _  Send  alarm signal  after  specified  time period  
  _
  _  F$AllBit   _  Allocate   bits   in  an   allocation  bitmap   
  _
  _ F$Chain _ Terminate the current  process and begin a new one  
  _
  _   F$CmpNam    _    Determine    if    two    strings   match    
  _
  _    F$CpyMem     _     Copy     a     block     of     memory     
  _
  _ F$CRC  _  Calculate a  24-bit  CRC  over a  block  of memory  
  _
  _ F$DatMod _ Create a named data module and return its address 
  _
  _  F$DelBit  _   Deallocate  bits  in   an  allocation  bitmap   
  _
  _ F$DExec  _ Execute  (n) instructions  in a  debugged program  
  _
  _    F$DExit     _     Terminate     a     debugged    program     
  _
  _ F$DFork _ Start a new  process under control of the debugger  
  _
  _    F$Exit     _     Terminate     the     current    process     
  _
  _    F$Fork    _    Start    a    new    concurrent    process     
  _
  _  F$GBlkMp   _   Return   system   free   memory   statistics   
  _
  _ F$GModDr  _ Return  a copy  of  the system  module directory  
  _
  _ F$GPrDBT  _  Return  a  copy  of  the  system process  table  
  _
  _ F$GPrDsc  _  Return a  copy  of a  given  process descriptor  
  _
  _ F$Gregor  _  Convert  date  and  time  to  Gregorian  format  
  _
  _   F$ID   _   Return   the   caller's   process   ID   number    
  _
  _ F$Icpt  _ Install  an intercept  routine to  process signals  
  _
  _  F$Julian  _  Convert   date  and  time   to  Julian  format   
  _
  _  F$Link  _  Return  the  address   of  a  module  in  memory   
  _
  _   F$Load   _    Load   memory   module(s)    from   a   file    
  _
  _*F$SigMask_   Enable    or    disable    signal    interrupts    
  _
  _  F$Mem  _  Change  the   caller's  primary  data  area  size   
  _
  _    F$PErr    _    Report     a    system    error    message     
  _
  _   F$PrsNam   _    Validate   and    parse   a    path   name    
  _
  _ F$RTE  _  Return  to main  program  after  signal processing  
  _
  _ F$SchBit  _ Search  for free  bits  in an  allocation bitmap  
  _
  _    F$Send    _    Send    a     signal    to    a    process     
  _
  _ F$SetCRC  _  Generate a  valid  CRC  in a  module  in memory  
  _
  _ F$SetSys  _  Examine  or  change  a  system  global variable  
  _
  _ F$Sleep _ Suspend  the calling process for  a period of time  
  _
  _    F$SPrior     _     Change     a     process's    priority     
  _
  _      F$SRqCMem_       Request      memory       by      type       
  _
  _    F$SRqMem    _     Allocate    a     block    of    memory     
  _
  _    F$SRtMem    _    Deallocate    a    block    of    memory     
  _
  _   F$STime    _    Set   the    current    date    and   time    
  _
  _ F$STrap  _  Install  a  routine  to  catch  execution errors  
  _
  _   F$SUser   _   Change   the   caller's   user   ID   number    
  _
  _ F$SysDbg  _ Invoke  the system  level debugger  (if present)  
  _
  _   F$Time   _    Return   the    current   date    and   time    
  _
  _________________________________________________________________
  
                      Figure VII.1 (cont'd)
  
  
  ________________________________________________________________
  _ Name   _               Description of Use                 _
  ________________________________________________________________
  _ F$TLink _ Install a trap handling library module            _
  _ F$UnLink_ Notify system that a memory module is not needed  _
  _ F$UnLoad_ Same as F$UnLink except by name instead of address _
  _ F$Wait _ Wait for forked process to terminate              _
  ________________________________________________________________
  
  
  
  
  1.1.2 CD-RTOS I/O Service Request Summary
  
  
  All of  the  I/O  service requests  available  in  CD-RTOS are  
  outlined in Figure VII.2 below.
  
  
                           Figure VII.2
  
           ____________________________________________
           _ Name  _      Description of Use      _
           ____________________________________________
           _I$Attach _ Attach I/O device             _
           _I$ChgDir _ Change default directory      _
           _I$Close _ Close path                    _
           _I$Create _ Create a new file             _
           _I$Delete _ Delete file                   _
           _I$Detach _ Detach I/O device             _
           _I$Dup _ Duplicate path                _
           _I$GetStt _ Get path status               _
           _I$MakDir _ Make directory file           _
           _I$Open _ Open existing file            _
           _I$Read _ Read data                     _
           _I$ReadLn _ Read line of text with editing _
           _I$Seek _ Change current file position  _
           _I$SetStt _ Set path status               _
           _I$Write _ Write data                    _
           _I$WriteLn_ Write line of text with editing_
           ____________________________________________
  
  
  
  
  
  1.1.3 CD-RTOS System State Service Request Summary
  
  All of the system state  service requests available in CD-RTOS  
  are outlined in Figure VII.3 below.
  
                           Figure VII.3
  _____________________________________________________________
  _ Name _             Description of Use                 _
  _____________________________________________________________
   _*F$Alarm_ Send alarm signal after specified time period   _
   _F$AllPD _ Allocate a process or path descriptor           _
  _F$AllPrc_ Allocate a process descriptor                   _
  _F$AProc _ Place a process in the active process queue     _
  _F$FindPD_ Find the address of a process or path descriptor _
  _F$IOQu _ Suspend the calling process in an I/O queue     _
  _F$IRQ  _ Install or remove a device from the IRQ table   _
  _F$Move _ Copy a block of data                            _
  _F$NProc _ Activate the next process in the active queue   _
  _F$RetPD _ Deallocate a process or path descriptor         _
  _F$SSvc _ Install system service request(s)               _
  _F$VModul_ Validate the CRC of a module in memory          _
  _____________________________________________________________
  
  1.1.4 Signal Handling Facilities
  
  In CD-RTOS, a process may install  a subroutine to be executed  
  when the process receives a  signal. This subroutine is called  
  the "signal  intercept  routine".  This  subroutine  is called  
  automatically when  the process  receives  the signal.  If the  
  process is sleeping, it is awakened.
  
  If a process has no signal intercept routine when it receives a 
  signal, it will  be aborted.  The signal  intercept routine is  
  installed by a process using the F$Icpt service request.
  
  If a process receives a signal  while it is processing another  
  signal, the new signal will be placed in a First In - First Out 
  (FIFO) queue for the process. As  soon as the signal intercept  
  routine executes the F$RTE service request, the second signal is 
  processed.
  
  A process may also elect to mask signals for a period of time.  
  Any signals received while signals are being masked are put into 
  the FIFO queue.  As soon as  signals are  unmasked, any queued  
  signals will be processed.
  
  
  
  
  The S$Wake signal is handled as a special case. It activates a 
  sleeping process but does not cause the intercept routine to be 
  executed and does not  abort a process  which has no intercept  
  routine. S$Wake  is never  queued  since the  presence  of any  
  signal insures that the process is awake.
  
  1.1.4.1 F$SigMask - Set Signal Mask
  
  F$SigMask is used to enable or disable signals from reaching the 
  calling process. If a signal is sent to a process whose mask is 
  set to a positive  value, the signal will  be queued until the  
  process mask  becomes cleared.  The process'  signal intercept  
  routine is executed with signals inherently masked.
  
  Two exceptions to this rule are the S$Kill and S$Wake signals.  
  S$Kill terminates the receiving process, regardless of the state 
  of its mask.  S$Wake ensures that  the process  is active, but  
  does not queue.
  
  When a process makes an F$Sleep or F$Wait system call its signal 
  mask is automatically cleared. If  a signal is already queued,  
  these calls return immediately (to the intercept routine).
  
  Note: Signals  are  similar  to  hardware  interrupts. Signals  
  should be masked sparingly, and intercept routines should be as 
  short and fast  as possible.  The signal  mask is  an unsigned  
  value. You cannot decrement below 0.
  
       Input:        d0.l = Reserved, must be zero
                      d1.l = Process signal level
                                0 = clear
                                1 = set/increment
                              -1 = decrement
       Output:       None
  
       Error Output: cc  = Carry bit set to one
                     d1.w = Error code
  
       Possible Errors:   E$Param
  
  1.1.4.2 F$Alarm - Set Alarm Clock (User State Call)
  
  The F$Alarm service request  may be used by  a user process to  
  create an asynchronous software alarm clock timer. The function 
  of the timer is to send a signal to the calling process when the 
  specified time period has elapsed. A process may have multiple  
  alarm requests pending.  The F$Alarm  call can  time intervals  
  within _1 system  clock tick. The  duration of  a system clock  
  tick is 0.01 second (see VIII.7.2).
  Several similar alarm functions are provided. A description of  
  each function is provided below.  The general parameter format  
  is:
  
  
       Input:   d0.l = Alarm ID (or zero)
            d1.w = Function code
            d2.w = Signal code
            d3.l = Time interval (or time)
            d4.l = Date (when using absolute time)
  
       Output:  d0.l = Alarm ID
  
       Error Output: cc  = Carry bit set to one
            d1.w = Error code
  
       Where the fields have the following meaning:
  
         Alarm ID:       Used to delete an alarm request
  
         Function Code:  The following functions are supported:
  
           $Delete -  remove a pending alarm request
          A$Set   -   send   a   signal   after   specified    time   
                         interval
           A$Cycle   -   send   a   signal   at   specified   time   
         intervals
           A$AtDate - send a signal at (Gregorian) date/time
           A$AtJul -  send a signal at (Julian) date/time
  
        Signal code:  This field  specifies the  alarm signal  to 
                         be sent to the calling process when the 
                         time interval expires.
  
         Time interval: The  number of  system clock  ticks (or  
                         256ths of a second)  to wait before an  
                         alarm signal is sent. If the high order 
                         bit  is  set,  the  low  31  bits  are   
                         interpreted as 256ths of a second. Note 
                         that all times  are rounded  up to the  
                         nearest 0.01 second.
  
         Error Output:  By  function,  a  list  of  error codes  
                         returned is  given.  The  system calls  
                         (e.g. F$SRqCMem) used by some of those  
                         functions are also  indicated, in this  
                         case all errors returned by the system  
                         calls are also possible. (See Appendix  
                         VII.1).
  
  A$Delete - Remove a Pending Alarm Request
  
       The A$Delete function is used to remove a cyclic alarm, or 
       any alarm that has not expired. If zero is passed as the 
       alarm ID, all pending alarm requests are removed.
  
       Input: d0.l = Alarm ID (or zero)
         d1.w = A$Delete function code
  
       Output: None
  
       Error output: cc  = Carry bit set to one
         d1.w = Error code
  
       Possible Errors: F$SRtMem
  
  A$Set - Send a Signal After Specified Time Interval
  
       The A$Set function is used to send one signal, after the  
       specified time interval  has elapsed.  The time interval  
       may be specified in  system clock ticks,  or 256ths of a  
       second. The minimum time interval  allowed is two system  
       clock ticks.
  
       Input: d0.l = Reserved, must be zero
         d1.w = A$Set function code
         d2.w = Signal code
         d3.l = Time interval
  
       Output: d0.l = Alarm ID
  
       Error Output: cc  = Carry bit set to one
         d1.w = Error code
  
       Possible Errors: F$SRqMem, E$Param
  A$Cycle - Send a Signal At Specified Time Intervals
  
       The A$Cycle  function is  similar  to the  set function,  
       except that  the alarm  is reset  after  it is  sent, to  
       provide a recurring periodic signal.
  
       Input: d0.l = Reserved, must be zero
         d1.w = A$Cycle function code
         d2.w = Signal code
         d3.l = Time interval
  
       Output: d0.l = Alarm ID
  
       Error output: cc  = Carry bit set to one
         d1.w = Error code
  
       Possible Errors: F$SRqMem, E$Param
  
  A$AtDate - Send a Signal at (Gregorian) Date/Time
  
       The A$AtDate function sends a signal  to the caller at a  
       specific date and time.
  
       Input: d0.l = Reserved, must be zero
         d1.w = A$AtDate function code
         d2.w = Signal code
         d3.l = Time (00hhmmss - BCD format)
         d4.l = Date (YYYYMMDD - BCD format)
  
       Output: d0.l = Alarm ID
  
       Error output: cc  = Carry bit set to one
         d1.w = Error code
  
       Possible Errors: F$SRqMem, E$Param
  A$AtJul - Send a Signal at (Julian) Date/Time
  
       The A$AtJul function sends  a signal to  the caller at a  
       specific julian date and time.
  
       Input: d0.l = Reserved, must be zero
         d1.w = A$AtJul function code
         d2.w = Signal code
         d3.l = Time (00hhmmss - BCD format)
         d4.l = Date (YYYYMMDD - BCD format)
                                 
       Output: d0.l = Alarm ID
  
       Error output: cc  = Carry bit set to one
         d1.w = Error code
  
       Possible Errors: F$SRqMem, E$Param
  
  The A$AtDate and A$AtJul functions  allow time to be specified  
  only to the nearest second. However, they do take into account  
  the fact that the  system's date and time  may be changed (via  
  F$STime). The  alarm  signal  is  sent  any  time  the  system  
  date/time becomes less than or equal to the alarm time.
  
  
  1.1.4.3 F$Alarm - Set Alarm Clock (system state call)
  
  When called from system state, F$Alarm call is used to cause the 
  execution of a (system state)  subroutine at a specified time.  
  It is provided for such functions  as turning off a disk drive  
  motor if the disk  is not accessed  for a period  of time. The  
  system state F$Alarm call does not send a signal, since in many 
  cases there is no  appropriate process expecting  to receive a  
  signal.
  System state  alarms are  not  associated with  any particular  
  process. It  is  the caller's  responsibility  to  insure that  
  alarms which are performed on behalf of a particular process are 
  removed if the process should terminate. In all other respects, 
  system state alarms function identically to user state alarms.
  
  Several similar alarm functions are provided and are identical  
  to the user state alarm functions described in VII.1.1.4.2. The 
  general parameter format is:
  
       Input: d0.l = Alarm ID (or zero)
         d1.w = Function code
         d2.l = Reserved, must be zero
         d3.l = Time interval (or time)
         d4.l = Date (when using absolute time)
         (a0)= Register image
       Output: d0.l = Alarm ID
  
       Error output: cc  = Carry bit set to one
         d1.w = Error code
  
  The register image pointed to by register (a0) contains an image 
  of the registers  to be  passed to  the alarm  subroutine. The  
  subroutine entry point must be placed in R$pc(a0). The register 
  image will be copied by the  F$Alarm request to another buffer  
  area, and may be re-used immediately for other purposes.
  
  System  state  alarm  subroutines  conform  to  the  following   
  conventions:
  
       Input: d0-d7 =  caller's registers,
               i.e. R$d0-R$d7(a5)
         a0-a3 =caller's registers,
               i.e. R$a0-R$a3(a5)
         (a4) = system process descriptor pointer*
         (a5) = pointer to register image
         (a6) = system global storage pointer
  
       Error output: cc   = Carry bit set to one
         d1.w = Error code
       
       Destroys: Registers d0-d7/a0-a3
  
  
  * Note: The user number in  the system process descriptor will  
      have been temporarily  changed to  the user  number of the  
      original F$Alarm request.
  
  Also, in the  case of cyclic  alarms, a "scratch"  copy of the  
  register image is passed to the alarm routine. This allows the  
  register image to be deleted as well.
  
  Note that since system state alarms run as the system process,  
  they must never perform any function that can result in any kind 
  of queueing, such as F$Sleep,  F$Wait, F$Load, F$Event (wait),  
  F$IOQU, or F$Fork. When such functions are required, the caller 
  must provide a process descriptor to be used for the function.
  
  1.2 CD-RTOS Startup Procedures
  
  The  general  outline   of  steps   performed  during  CD-RTOS   
  initialization (e.g. at power on or reset) are made up of three 
  distinct  parts.  The  first  part  consists  of  manufacturer   
  dependent routines executed prior to calling the CD-RTOS kernel. 
  The second part is made up of routines performed by the CD-RTOS 
  kernel itself. The final part consists of operations performed  
  by the manufacturer dependent initial process routines started  
  by CD-RTOS.
  
  The following is a description  of the start-up procedures for  
  CD-I players.
  
  Manufacturer dependent (bootstrap) routines
  
   1. Reset or initialize hardware
  
   2. Perform any necessary hardware diagnostics
  
   3. Locate  (and initialize  if necessary)  system RAM, ROM  and 
      NVRAM
  
   4. Locate and execute the CD-RTOS kernel
  
  CD-RTOS routines
  
   1. Build list of free RAM
  
   2. Locate modules in ROM and build module directory
  
   3. Initialize  internal system  global variables and  execution 
      vectors
  
   4. Link to Init module
  
   5. Start system clock
  
   6. Execute kernel customization module, if present in ROM
   7. Open system I/O paths
  
   8. Execute the initial process 
  
   9. Wait for all processes  to die and then execute the  F$Panic 
      system call installed  by the  os9p2 module.  This routine  
      should merely execute F$SysDbg on  base case systems. This  
      will cause the system to jump to point 1 of the Manufacturer 
      dependent (bootstrap) routines
  
  Example of manufacturer dependent initial process routines
  
  
   1. Optionally display manufacturer dependent image
  
   2. Wait for user to insert and play disc 
  
   3. If CD-DA disc play it and go back to 1
  
   4. Change default working and execution directories to the CD-I 
      disc
  
   5.  If  possible  read  Disc  Label  to  determine the  initial  
      application program name
  
   6. If no Disc Label  or no initial application program  present 
      on disc, display suitable message and go to 1
  
   7. Close all open paths to UCM and CDFM
  
   8. Chain to initial application (which must be loaded into bank 
      B of memory).
  
  
  
  
  
  Some CD-RTOS  system  modules in  ROM  may be  replaced  by an  
  application by  providing  a replacement  module  which  has a  
  revision number greater than the revision number of the module  
  that is being replaced.  All such replacement  modules must be  
  upward compatible with the modules that they are replacing.
  
  
  1.3 Hardware Configuration Status Descriptor
  
  1.3.1 General
  
  In order for an application program to be able to determine the 
  functional configuration of a CD-I system, CD-RTOS provides the 
  Configuration Status Descriptor.
  
  The  configuration  status  descriptor   (CSD)  describes  the   
  functional hardware configuration of a system. It contains one  
  entry for each device on the system  whether it is a Base Case  
  device or an optional extension.
  
  The CSD contains sufficient information  for an application to  
  identify the characteristics of every device in a CD-I system.  
  The  physical  capabilities  of  a  specific  device  must  be   
  determined by an examination  of the device  descriptor, or by  
  issuing appropriate I$GetStat requests.
  
  Each device is  represented in  the CSD  by its  Device Status  
  Descriptor (DSD). Each DSD  is made up  of 3 parts,  a name, a  
  type, and a list  of parameters which  describe the functional  
  capabilities of the device.
  
  1.3.2 Compilation of the CSD
  
  When the kernel starts up, it executes a special os9p2 module to 
  compile the CSD. Initially, this  csdinit module checks to see  
  if there is a file on the NVRAM device called "csd". If not, it 
  creates one. Next it searches through the module directory for  
  data modules  with  a type  byte  set to  CSDData.  These data  
  modules contain the actual DSD entries which go to make up the 
  CSD. Next, csdinit searches these  data modules for DSDs which  
  are not already in the  CSD file, adding new  ones as it finds  
  them. Finally, csdinit looks for the Montype constant in System 
  Memory to find out how to set up the monitor type as well as the 
  525/625 line parameter in the DSD for the video monitor.
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
              This page is intentionally left blank
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
              This page is intentionally left blank
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
              This page is intentionally left blank
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
              This page is intentionally left blank
  
  
  
  
  
  
  
  
  VII.2 File Managers
  
  2.1 General
  
  
  A File Manager  is a  system memory  module which  handles I/O  
  requests for a class of similar devices. File managers operate  
  at a high level, in a device independent way. Actual control of 
  device hardware is performed by a device driver at the request  
  of the file manager. The function of a file manager is to remove 
  as much device dependence as possible from the I/O stream, and  
  present a uniform I/O interface to higher levels of software.
  
  The concept of a file is provided by a file manager. A file is 
  made up of a  contiguous stream of  bytes, with no assumptions  
  about the organization of  these bytes being  made by the file  
  manager. When possible, the bytes are made randomly accessible. 
  On devices that support random access, files are organized into 
  directories.
  
  All file managers are organized as a collection of subroutines  
  called by  the  operating system  kernel  to  perform specific  
  functions. The interface is identical  for every file manager,  
  regardless of differences in device capabilities. If a function 
  cannot be accommodated by any particular class of devices, the  
  file manager simply returns an error.
  
  For a detailed  specification of  the file  manager interface,  
  refer to the Appendix VII.1.
  
  This section specifies  the Compact Disc  File Manager (CDFM),  
  User Communications  Manager (UCM)  and Non-volatile  RAM File  
  Manager (NRF).  For  details  of  the  Pipe  File  Manager see  
  Appendix VII.1.
  
  A summary of the  functions provided is  given in Figure VII.6  
  below along with a data flow model for CD-RTOS. 
  
                          Figure VII.6a
       
  __________________________________________________
  _ Name   _        Description                 _
  __________________________________________________
  _ Create _ Create a new file                   _
  _ Open   _ Open an existing file               _
  _ Makdir _ Create a new directory file         _
  _ Chgdir _ Change current working directory    _
  _ Delete _ Delete a file                       _
  _ Close  _ Close an open file                  _
  _ Seek   _ Reposition the current file pointer _
  _ Read   _ Read bytes or records               _
  _ Readln _ Read until end of line character    _
  _ Write  _ Write bytes or records              _
  _ Writeln _ Write until end of line             _
  _ Getstat _ Return device status (wildcard)     _
  _ Setstat _ Change device status (wildcard)     _
  __________________________________________________
                          Figure VII.6b                        
                                       
  
  
                          _______________
                         _ Application _
                          _______________
                                 _
                          _______________
                          _  Kernel   _
                          _______________
                                 _
      _______________________________________________    
      _               _               _          _
  ____________    ___________     ___________ ___________
  _  CDFM  _    _  UCM  _     _  NRF  _ _ Pipeman _ File
  ____________     ___________      ___________      ___________      
  Manager
      _               _               _          _
   ________    _________________       _          _
   _ CD _ _______________________ _______     ______
   _Driver_ _Video__ptrdvr__Kbdrvr_ _nvdrv_     _null_  Driver
   ________ _______________________ _______     ______
   ______     _      _      _       _          _
  __________ _______ ______  _____  ______      _______ Des-
  _/cd__/ap_ _/vid _ _/ptr_  _/kb_  _/nvr_      _/pipe_ criptor
  __________ _______ ______  _____  ______      _______
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  This page is intentionally left blank            2.2 Compact 
                     Disc File Manager (CDFM)
  
  2.2.1 Introduction
  
  
  The CDFM is a file manager module  that supports I/O to the CD  
  device driver. It  is written  as a  standard file  manager as  
  described in Appendix  VII.1. The function  of the  CDFM is to  
  convert high level user commands to low level CD device driver  
  commands. The CDFM is responsible for management and access of  
  the disc's tree structured file system, the raw data stream from 
  the disc, and scheduling of the disc's usage.
  
  Since the  Audio  Processor  is an  integral  part  of  the CD  
  interface hardware, CDFM also supports audio output and control.
  
  The CDFM is a collection of subroutines. The CDFM supports the  
  following subroutine  entry  points  referred  to  as  service  
  requests.
  
  
                           Figure VII.7
   
  ________________________________________________________________
  _ Name   _     Description                                  _
  ________________________________________________________________
  _ Open   _ Open path to specified device and/or file         _
  _ Chgdir _ Change user's default directories                 _
  _ Seek   _ Change current file position pointer              _
  _ Read   _ Read requested number of bytes from current file  _
  _        _   position                                       _
  _ ReadLn _ Read requested number of bytes from current file  _
  _        _   position until carriage return <CR> or maximum _ 
  _        _   specified                                      _
  _ GetStat _ Get specified status information                  _
  _ SetStat _ Set specified status information                  _
  _ Close  _ Close path to a specified device and/or file      _
  ________________________________________________________________
  
  
  
  2.2.2 Features and Concepts
  
  2.2.2.1 Execution Classes
  
  There are two execution classes for the service requests to the 
  CDFM. The first  class consists of  the asynchronous execution  
  service requests. These are service requests which, when called 
  from an application, start the  execution of the specified I/O  
  function and return to the application while the service request 
  is executing. This allows the  application and service request  
  to execute concurrently. These service requests include four of 
  the SetStat service  requests (defined  fully in VII.2.2.3.2):  
  SS_Play, SS_CDDA, SS_Seek and SM_Out (VII.2.2.4.1).
  
  Note: If an  asynchronous request is  currently executing, any  
        requests to access the disc from other processes will be  
        queued until the  disc becomes available.  If the second  
        request is an asynchronous request, it will not return to 
        the  application  until  that  request  actually  begins   
        execution.
  
     If the same process executes  a second disc access request  
     while its asynchronous  request is  still active,  it will  
     receive an error indicating  that the device  is busy. The  
     same process may not have two disc access requests pending  
     at the same time.
  
  The second class consists of the synchronous execution service  
  requests. These are  service requests which,  when called from  
  the application, complete their function before returning to the 
  application. The synchronous service requests include all other 
  functions not included in the asynchronous service requests.
  
  2.2.2.2 Scheduling
  
  The CDFM  schedules  the  use  of  the  CD-I  Disc Drive.  The  
  scheduling algorithm  used is  the  'elevator' or  'SCAN' seek  
  optimization strategy. This  is a strategy  that minimizes the  
  total seek times by moving the disc head back and forth across 
  the disc surface, servicing all requests in its path. The head  
  changes direction  only when  there  are no  more  requests to  
  service in  the  current direction.  As  service  requests are  
  received which require  disc I/O,  they are  scheduled in this  
  manner with the following rules.
  
  (1) A maximum of one I/O  request in scheduling queue per open  
      path.
  (2) Asynchronous operations are not scheduled. An asynchronous  
      operation is allowed only when the disc drive is not busy.
  2.2.2.3 File Security System
  
  File usage and security are based on file attributes. Each file 
  can have up to seven possible attributes (directories can have  
  eight).
  
  The term permission  is used  when one  of the  eight possible  
  attribute characters  is  set. Permission  determines  who can  
  access a file or directory and how it can be used.
  
  Permissions are based on a group and user number associated with 
  each file and with the process  trying to access the file. The  
  group number 0 is a special group called the "super user group". 
  A super user has access to any file in the system.
  
  For a description of the  different permissions bits and their  
  meaning, refer to III.21.
  
  In a CD-I system, each application will initially be executed as 
  user 1.1. That is, group 1, user  1. If that application is to  
  access a file, the file must have the permission bits set which 
  would allow that group/user to access it.
  
  If the disc developer wishes to limit access to various files on 
  the disc, the files should have permissions which restrict that 
  user from accessing the file. This may be done by changing the 
  group/user number on  the file  and resetting  to 0  the world  
  permission bits.
  
  It is possible, however, for an  application to change its own  
  user or group  number. Using  this mechanism,  the application  
  could access  different groups  of files  when it  wished. For  
  example, if  the  disc  contained  multiple  applications, the  
  primary application could ask for an access code and then change 
  its group/user  number  to allow  access  to the  files  for a  
  particular application on the disc.
  
  For more information on changing a process's group/user id, see 
  the F$SUser system call in Appendix VII.1.
  
  
  
  
  
  
  

2.2.3 CD Service Requests


This is a specification of the interface between the application 
program and the CDFM for the CD device.


2.2.3.1 I$GetStt - GetStat Functions


These functions are used to get specific status information.

The service requests performed by the GetStat entry point in the 
CDFM are specified  by a  function code  and are  described in  
Figure VII.8.


                         Figure VII.8

    _______________________________________________________
    _ Name    _            Description               _
    _______________________________________________________
    _ SS_Opt    _ Get options section of path descriptor _
    _ SS_EOF    _ Test for end of file                  _
    _ SS_Size   _ Return file size                      _
    _ SS_Pos    _ Return file position                  _
    _ SS_CDFD   _ Return file descriptor                _
    _ SS_Path   _ Return full pathlist                  _
    _______________________________________________________
                                    
Note: Any  function  codes  other than  the  above  are passed  
through CDFM  to  the  CD device  driver  GetStat  routine for  
possible action there. This allows  direct access to functions  
supported by the device driver (see VII.3.1.5.4 for more about  
GetStat in the device driver).

SS_Opt - Get Options Section of Path Descriptor

This call returns a 128-byte packet which contains the options 
section of the path  descriptor. The options  section of the  
path descriptor contains information  (see VII.3.1.4.2.3 and  
Appendix VII.1) which may be of use to the application. Some  
of the fields in  the options section may  be changed by the  
application. To do this, the options section is normally read 
(using this service request), the  changes are made, and the  
options section is rewritten using  the SS_Opt SetStat call.  
Changing PD_CNUM selects a different channel mask for the next 
synchronous CD disc I/O operation.
   
   
Input: d0.w = Path number
   d1.w = SS_Opt getstat code
   (a0) = Pointer to 128-byte packet

 Output: None

 Error Output: cc  = Carry bit set to one
   d1.w = Error code

 Possible Errors:  E$BPNum


SS_EOF - Test for End of File

This call is used to determine if the current file pointer is 
pointing at the end of  the file. If it is  at the end error  
code E$EOF is returned.

 Input: d0.w = Path number
   d1.w = SS_EOF getstat code

 Output: d1.l = 0 if not end of file

 Error Output: cc  = Carry bit set to one
   d1.w = Error code 

 Possible Errors:  E$BPNum, E$EOF
SS_Size - Return File Size

This call is used to get the total size, in bytes, of the file 
denoted by the path  number. The file  size returned is read  
from the file size in the file descriptor. This is originally 
determined by taking the  number of sectors  occupied by the  
file multiplied by 2048 less any  unused portion of the last  
sector of the file. The file size does not take into account 
the fact that form 2 sectors  actually contain 2324 bytes of  
data and CDDA tracks are also of a different size.


 Input: d0.w = Path number
   d1.w = SS_Size getstat code

 Output: d2.l = File size

 Error Output: cc  = Carry bit set to one
   d1.w = Error code

 Possible Errors:  E$BPNum


SS_Pos - Return File Position

This function returns the position of the next byte to be read 
from the file.

 Input: d0.w = Path number
   d1.w = SS_Pos getstat code

 Output: d2.l = Current file position

 Error Output: cc  = Carry bit set to one
   d1.w = Error code

 Possible Errors:  E$BPNum

SS_CDFD - Return File Descriptor

This call is used to read the file descriptor describing the  
path number. The file descriptor may be read for information  
purposes only as there are no user changeable parameters (see 
III.3.2 for a complete specification of the file descriptor).

 Input: d0.w = Path number
   d1.w = SS_CDFD getstat code
   d2.w = Number of bytes to copy
   (a0) = Pointer to buffer area for file 
                                           
                                          descriptor

 Output: None

 Error Output: cc  = Carry bit set to one
   d1.w = Error code

 Possible Errors: E$BPNum





























SS_Path - Get Full Pathlist to Open File

This call returns  the complete  pathlist to  the open file,  
including the device name, in a 128-byte buffer.

 Input: d0.w = Path number
   d1.w = SS_Path getstat code
   (a0) = Pointer to 128-byte buffer

 Output: None

 Error Output: cc  = Carry bit set to one
   d1.w = Error code

 Possible Errors:  E$BPNum






  
  




  

2.2.3.2 I$SetStt - SetStat Functions

Set specific status information.

The service requests performed by the SetStat entry point in the 
CDFM are specified by a function code and are outlined in Figure 
VII.9.

                         Figure VII.9
________________________________________________________________
_  Name       _             Description                    _
________________________________________________________________
_ SS_Seek      _ Issue a seek command to disc drive          _
_ SS_Abort     _ Abort asynchronous operation in progress    _
_ SS_CDDA      _ Play CD digital audio                       _
_ SS_Pause     _ Pause the disc drive                        _
_ SS_Eject     _ Issue door open command to disc drive       _
_ SS_Mount     _ Mount disc by disc number                   _
_ SS_Opt       _ Write the options section of the path       _
_              _  descriptor                                _
_ SS_Disable   _ Disable front panel buttons                 _
_ SS_Enable    _ Enable front panel buttons                  _
_ SS_Cont      _ Continue the disc after pause               _
_ SS_Stop      _ Stop the disc                               _
_ SS_Raw       _ Read Raw sectors                            _
_ SS_ReadTOC   _ Return TOC from Q channel                   _
_ SS_Play      _ Play real time records                      _
_ SS_CChan     _ Channel and Audio channel changing          _
________________________________________________________________

Note: Any function codes other than the above codes are passed  
through CDFM  to  the  CD device  driver  SetStat  routine for  
possible action there. This allows  direct access to functions  
supported by the device  driver (see VII.3.1.5.4.  of the CD-I  
Specification for more about SetStat in the device driver).


SS_Seek - Issue a Seek Command to Disc Drive 

This function causes the file position  pointer to be set to  
the new value. It  also causes the  disc drive to physically  
seek to the beginning of the sector containing the specified  
byte. The SS_Seek command uses a sector size of 2048 bytes to 
compute  the  new   file  position.  This   function  is  an   
asynchronous operation and therefore uses  a status block to  
keep the application informed of the status of the seek.

The format of the status block is given in Figure VII.10a.

                      Figure VII.10a
 ______________________________________________ 
 _Offset_Length_ Name _    Description    _
 ______________________________________________
 _ 0  _  2 _ASY_Stat_Current status of the_
 _     _     _       _ operation         _
 _ 2  _  2 _ASY_Sig _Signal to be sent on _
 _     _     _       _ termination       _
 ______________________________________________

 ASY_Stat:  This  field  contains  the  current  status  of  the  
           asynchronous operation. The status defines whether  
           the operation is finished and whether there was an  
           error during the operation. The system updates this 
           field  and  it  should  not   be  altered  by  the   
           application. The bit assignments for this field are 
           as follows.

   ___________________________________
   _ Bit # _  Description (if set) _
   ___________________________________
   _  0  _ Operation is finished  _
   _ 1-14 _ Reserved (must be zero) _
   _ 15  _ Error has occurred     _
   ___________________________________

ASY_Sig: This field contains the signal number to be sent to  
         the application when the operation is finished or an 
         error occurs. It is  initialized by the application  
         before the operation is started and may be changed by 
         the application during the operation. If this field  
         is set  to zero  then no  signal  is sent  when the  
         operation is finished or when an error occurs. If an 
         error occurs during the operation this field contains 
         the error code of the error.

Input: d0.w = Path number
   d1.w = SS_Seek setstat code
   d2.l = New head position byte position
   (a0) = Pointer to status block

Output: None

Error Output: cc  = Carry bit set to one
 d1.w = Error code

Possible Errors: E$BPNum

SS_Abort - Abort Operation in Progress

This function  is used  to abort  an operation  currently in  
progress. This is a privileged function call and may be used  
only by a process with a user ID of the super user or with the 
user ID of  the process  which started  the operation.  If a  
synchronous request  is  in  progress  an  E$Abort  error is  
returned. If  an  asynchronous request  is  in  progress any  
signal in PCB_Sig (or  ASY_Sig) will be  sent and an E$Abort  
error code is returned in PCB_Sig (or ASY_Sig). The SS_Abort  
function will return with carry clear.

Input:  d0.w = Path number
     d1.w = SS_Abort setstat code

Output:  None

Error Output:  cc  = Carry bit set to one
   d1.w = Error code

Possible Errors: E$BPNum


SS_CDDA - Play CD Digital Audio

This function is used to play CD-DA sectors on the disc. The 
play starts from the current file position and continues until 
an error occurs, the maximum number of sectors has been played 
or the end of the file has been reached. This function is an  
asynchronous operation and therefore uses  a status block to  
keep the application informed of  the status of the SS_CDDA.  
The format of the status is identical to the status block of 
SS_Seek. It  should be  noted  that when  playing  CD-DA the  
resolution of the current file position can only be guaranteed 
to _ 75 sectors, i.e. _ one second. 

Input:  d0.w = Path number
     d1.w = SS_CDDA setstat code
     d2.l = Maximum number of sectors to play
     (a0) = Address of status block

Output:  None

Error Output: cc  = Carry bit set to one
   d1.w = Error code

Possible Errors: E$BPNum, E$BMode, E$Read, E$EOF

SS_Pause - Pause the Disc Drive

This function is used to pause the  CD disc drive. This is a  
privileged function call and  may be used  only by a process  
with a user ID = 0.0 (see A VII.1) or with the user ID of the 
process which started an asynchronous operation currently in  
progress. On CD-I tracks and on  CD-DA tracks, the disc will  
pause at the position on the disc being played when the pause 
was returned.

Input:  d0.w = Path number
     d1.w = SS_Pause setstat code

Output:  None

Error Output: cc  = Carry bit set to one
   d1.w = Error code

Possible Errors: E$BPNum


SS_Eject - Issue Door Open Command to Disc Drive

This function is used to open the  CD disc drive door. If an  
operation is in progress, the effect  of an SS_Abort is done  
before the  eject command  is issued.  This is  a privileged  
function call and may be used only by a process with a user ID 
= 0.0.

Input:  d0.w = Path number
     d1.w = SS_Eject setstat code

Output:  None

Error Output: cc  = Carry bit set to one
   d1.w = Error code

Possible Errors: E$BPNum

SS_Mount - Mount Disc by Disc Number

This call  changes  the  default disc  to  use  in multidisc  
players. The disc  is referred to  by a  number with maximum  
range of 0 to 65535. On  single disc players the disc number  
used is 0. SS_Mount  also causes the drive  door to close if  
possible and spins up the disc.

Input:  d0.w = Path number
     d1.w = SS_Mount setstat code
     d2.w = Disc number

Output:  None

Error Output: cc  = Carry bit set to one
     d1.w = Error code

Possible Errors: E$BPNum


SS_Opt - Set Options Section of Path Descriptor

This call writes a 128-byte packet which contains the options 
section of the path  descriptor. The options  section of the  
path descriptor contains information which  may be of use to  
the application. Some of  the fields in  the options section  
are normally read using the GetStat function call. The changes 
are made and the options section is rewritten using the SS_Opt 
function call.  Currently,  only  PD_CNUM  may  be  changed.  
Changing PD_CNUM selects a different channel mask for the next 
synchronous CD disc I/O operation.

Input:  d0.w = Path number
     d1.w = SS_Opt setstat code
     (a0) = Pointer to 128-byte packet

Output:  None

Error Output: cc  = Carry bit set to one
     d1.w = Error code

Possible Errors: E$BPNum







SS_Disable - Disable Hardware Control Buttons on Player

This call disables any disc drive related user controls.

Input:  d0.w = Path number
    d1.w = SS_Disable setstat code

Output:  None

Error Output: cc  = Carry bit set to one
    d1.w = Error code

Possible Errors: E$BPNum

SS_Enable - Enable Hardware Control Buttons on Player

This call enables any disc drive related user controls.

Input:  d0.w = Path number
    d1.w = SS_Enable Setstat

Output:  None

Error Output: cc  = Carry bit set to one
    d1.w = Error code

Possible Errors: E$BPNum

SS_Cont - Continue the Disc Drive

This function continues the playing by the disc drive if the  
drive was paused.

Input:  d0.w = Path number
    d1.w = SS_Cont setstat code

Output:  None

Error Output: cc  = Carry bit set to one
    d1.w = Error code

Possible Errors: E$BPNum







SS_Stop - Stop the Disc Drive

This function is used to stop  the disc drive. This function  
works the same as the SS_Eject function, except that the drive 
door is not opened.

Input:  d0.w = Path number
    d1.w = SS_Stop setstat code

Output:  None

Error Output: cc  = Carry bit set to one
    d1.w = Error code

Possible Errors:  E$BPNum

SS_Raw - Read Raw Sectors

SS_Raw returns the sector contents from byte number 12 to byte 
number 2351 of the raw sector data. This includes the header, 
subheader, data, and  ECC/EDC, if  any. The  SS_Raw function  
works identically to the Read function with the exception that 
both Mode 1 and Mode 2, Form 1 and Form 2 sectors may be read 
and that the size  of the data returned  per sector is 2340.  
The current file position must be  on a sector boundary when  
this call is made. The  file position pointer is incremented  
by 2048 for every sector read.

 Input:  d0.w = Path number
     d1.w = SS_Raw setstat code
  d2.l  =  Maximum   number  of  bytes   to  read  (must  be   in  
     increments of 2340)
     (a0) = Buffer pointer

 Output:  d1.l = Number of bytes actually read

 Error Output: cc  = Carry bit set to one
     d1.w = Error code

 Possible Errors:  E$BPNum, E$BMode, E$Read, E$EOF
SS_Read_TOC - Return TOC from Q-Channel

SS_Read_TOC returns  the Table  Of  Contents (TOC)  from the  
Q-channel in the user's buffer.

Input:  d0.w = Path number
    d1.w = SS_Read TOC setstat code
    d2.l = Number of bytes to return (maximum 510)
    (a0) = Pointer to buffer for TOC
Output: None

Error Output: cc   
                    = 
                    Carry bit set to one
  d1.w = Error code

Possible Errors: E$BPNum, E$Read


                       Figure VII.10.1.a

     _____________________________________________________
     _ DISC TYPE    _   $A0.PMIN    _    $A0.PSEC   _
     _____________________________________________________
     _ CDI          _     >= 2      _     = $10     _
     _              _                _                _
     _ CD-ROM       _     >= 1      _     = $00     _
     _              _                _                _
     _ CD-ROM XA    _      = 1      _     = $00 or  _
     _              _      = 1      _     = $20     _
     _              _                _                _
     _ CD-DA        _     >= 1      _     = $00     _
 _____________________________________________________Table 
Of Contents (TOC) structure format                  
                        Figure VII.10.1
_________________________________________________________________

_Offset_Length_          Name           _          Description           
_
_________________________________________________________________

_  0 _ 1  _TOC_CTRL0_Control byte 0                       _
_      1       _      1       _TOC_A0       _Contains      $A0       
_
_  2 _ 1  _TOC_STN0 _PMIN of Point $A0                    _
_    3    _    1    _TOC_TYPE     _PSEC    of    Point    $A06     
_
_    4    _     1    _TOC_PBLK0_PFRAME     of    Point    $A06     
_
_------_------_---------_---------------------------------------_

_     5      _      1      _TOC_CTRL1_Control5      byte     1      
_
_      6       _      1       _TOC_A1       _Contains      $A1       
_
_    7    _    1    _TOC_LTN0     _PMIN    of    Point    $A16     
_
_    8     _     1    _TOC_PSEC1_PSEC     of     Point    $A16     
_
_    9    _     1    _TOC_PBLK1_PFRAME     of    Point    $A16     
_
_------_------_---------_---------------------------------------_

_     10      _     1      _TOC_CTRL2_Control5      byte     2      
_
_      11      _       1      _TOC_A2       _Contains      $A2       
_
_  12  _   1  _TOC_LMIN  _Start   minute  of   LEAD  OUT  area   
_
_  13  _   1  _TOC_LSEC  _Start   second  of   LEAD  OUT  area   
_
_  14  _   1  _TOC_LBLK   _Start  block   of  LEAD   OUT  area   
_
_------_------_---------_---------------------------------------_

_ 15  _ 1  _TP_CTRL  _Control5 byte  of first  track  entry in  
_
_     _     _        _TOC list                             _
_  16   _   1  _TP_TNO   _Track   number  in   2   digits  BCD   
_
_   _    _    _(8-4-2-1    code):    $01    for    track    01    
_
_ 17  _  1  _TP_$MIN  _Track 1  start  minute  (2  digits BCD)  
_
_ 18  _  1  _TP_$SEC  _Track 1  start  second  (2  digits BCD)  
_
_ 19  _  1  _TP_$BLK  _Track  1  start  block  (2  digits BCD)  
_
_---------------------------------------------------------------_

_ Contains 97 identical  packets (like offset  15-19), one for  
_
_   each    successive    track    entry    in    TOC    list7    
_
_---------------------------------------------------------------_

_       505       _        _TP_CTRL       _Control5       byte        
_
_       506        _        _TP_TNO        _Track       number        
_
_       507        _       _TP_$MIN        _Start       minute        
_
_       508        _       _TP_$SEC        _Start       second        
_
_       509        _        _TP_$BLK        _Start       block        
_
_________________________________________________________________

SS_Play - Play Real-time Records                               

SS_Play is used to play data off the disc. It can be used to 
'play' Mode 2 Form 1 and Mode  2 Form 2 sectors on the disc.  
The play function is normally used to play real time records. 
A play is  controlled by  information contained  in the play  
control block (PCB). The play control  block is built by the  
application. It  contains  information  such  as  number  of  
records to play, which channel numbers to select, which data  
types to select, what signal to send on Real-time events, etc. 
Play is  an  asynchronous  operation  (i.e.  the application  
continues  execution  at  the  same  time  as  the  play  is   
executing). The layout of the play control structures define  
the functionality of  play. The  play is  started using data  
pointed to by the  file position pointer.  The file position  
pointer is updated to  the new file  position after the play  
terminates.

Input: d0.w = Path number
    d1.w = SS_Play setstat code
  (a0) = Pointer to play control block (PCB)

Output: None

Error Output: cc  = Carry bit set to one
    d1.w = Error code
    
Possible Errors: E$BPNum, E$DcoBsy

The address of the play control block is passed as a parameter 
to the SS_Play function. The play control block contains the  
status of  the  play,  the  signal  to  send  when the  Play  
terminates, total number of records to play, channel numbers  
to select and pointers to lists  of Channel Index List (CIL)  
for each data type.














The values within the play control block, except PCB_Stat, can 
be changed at any time by the application. They will 
take effect  after the  next  selected sector  (according to  
previous PCB_Chan value) is retrieved from disc or after the  
reception of an EOR or Trigger bit.

If PCB_Rec  was set  to 0  by the  application, the  play is  
aborted after processing that sector.

Consequently, the effectiveness of channel selection switching 
by using PCB_Chan may be more or less immediate depending on  
the file organization: this uncertainty  is most of the time  
acceptable, especially for the  switch between various audio  
channels.

However, when  immediate  and precise  channel  switching is  
required (for instance synchronized on a trigger bit, between 
exclusive video or data channels) the channel selection switch 
can be made through one of two mechanisms. First, the SS_CChan 
setstat will cause  the PCB_Chan  and PCB_AChan  masks to be  
updated. Secondly, the CIL  can be used  to ignore data from  
specific channels.  Placing  a  zero  (instead  of  the  PCL  
pointer) into the  CIL entry  will cause  the data  for that  
channel to be discarded (see Figure VII.10d).

Play Control Block (PCB) Format:

                       Figure VII.10b
 
   ____________________________________________________________
   _Offset_Length_  Name  _         Description           _
   ____________________________________________________________
   _  0 _ 2  _PCB_Stat _Current status of the Play      _
   _  2 _ 2  _PCB_Sig  _Signal to be sent on termination _
   _  4 _ 4  _PCB_Rec  _Maximum number of records to play_
   _  8 _ 4  _PCB_Chan _Channel selection mask          _
   _ 12 _ 2  _PCB_AChan _Audio to audio processor channel _
   _     _     _         _selection mask                  _
   _ 14 _ 4  _PCB_Video _CIL pointer for video data      _
   _ 18 _ 4  _PCB_Audio _CIL pointer for audio data      _
   _ 22 _ 4  _PCB_Data _CIL pointer for computer data   _
   ____________________________________________________________

The PCB parameters are defined as follows.

  PCB_Stat: This field  contains the  current status  of the  
            Play.  It  should   be  set   to  zero   by  the   
            application. This field is updated by the system  
            at the time a sector is selected. The application 
            may review this field at any time during the Play 
            to determine the current status  of the Play but  
            should not modify the field during the Play. The  
            bits in PCB_Stat are defined as follows:
    
   Bit Number Description (if set to one)
    0  End of Record (EOR)
    1  Video sector last read
    2  Audio sector last read
    3  Data sector last read
   4  Trigger (T)
   5  Form 2
   6  Real-Time Sector (RT)
    7       End-of-File (EOF)
    8    Play is finished
   9-14    Reserved (must be zero)
   15   Error has occurred

   PCB_Sig: This field contains the signal number to be sent  
   to the application when the Play is finished, or on EOR or 
   trigger bit. It is initialized  by the application before  
   the Play is started and may


 be  changed  by  the  application  during  the  Play.  If  this  
    field is set to zero then no signal is sent when the Play  
    is finished or when  an error occurs.  If an error occurs  
    during the Play this field contains the error code of the  
    error.

   PCB_Rec: This field  contains the maximum  number of real  
   time records  left to  play. The  application initializes  
   this field to the maximum number  of real time records to  
   Play. The  system  decrements this  number  every  time a  
   record is Played until the field goes to zero at which time 
   the Play is terminated. This number may be changed by the  
   application during the execution of the Play.

   If PCB_Rec is set to 0, the play will be aborted after the 
   next selected sector is processed.

   PCB_Chan: This field contains the channel selection mask.  
   It defines which channels are  played. Any combination of  
   32  separate  channels  may  be  played  by  setting  the   
   corresponding bit in this
   field. This field may be changed by the application during 
   the execution of the Play. 
   
PCB_AChan: This is a channel  selection mask to select audio  
            sectors which go to the audio processor. If a bit 
            in this field is  set to one,  the audio sectors  
            with the corresponding channel number will be sent 
            to the audio processor. All channels included in  
            this field  must  also be  defined  in PCB_Chan.  
            Channel bits set  to one  which are  included in  
            PCB_Chan but not in this field will be handled by 
            the PCL for audio sectors if one exists.

PCB_Video: points to the Channel  Index List (CIL) for video  
            data. If  this field  contains zero,  video data  
            blocks are  ignored. This  field  is initialized  
            before the Play is started by the application. 

   PCB_Audio: This points to the Channel Index List (CIL) for 
   audio data. If this field contains zero, audio data blocks 
   are ignored. This field is initialized before the Play is  
   started by the application.





PCB_Data: This points to the  Channel Index List for program  
          related data. If this field contains zero, program  
          related  blocks   are  ignored.   This   field  is   
          initialized before  the  Play  is  started  by the  
          application. 

Channel Index List (CIL) Format:

There are three Channel Index List  pointers in the PCB, one  
each for audio, video, and  program related data blocks. The  
Channel Index List contains pointers to lists of Play Control 
Lists (PCLs),  according  to channel  numbers.  CIL  has two  
different formats, i.e. one is for  audio and another is for  
video or program related  data. This difference  is based on  
the difference of available channel numbers for each type of  
data.

               Figure VII.10c CIL for Audio data
 _______________________________________________________________ 
 _ Offset _ Length _  Name   _     Description             _
 _______________________________________________________________
 _   0  _   4  _ CIL_00   _ PCL pointer for channel = 0  _
 _   4  _   4  _ CIL_01   _ PCL pointer for channel = 1  _
 _   8  _   4  _ CIL_02   _ PCL pointer for channel = 2  _
 _  12  _   4  _ CIL_03   _ PCL pointer for channel = 3  _
 _  16  _   4  _ CIL_04   _ PCL pointer for channel = 4  _
 _  20  _   4  _ CIL_05   _ PCL pointer for channel = 5  _
 _  24  _   4  _ CIL_06   _ PCL pointer for channel = 6  _
 _  28  _   4  _ CIL_07   _ PCL pointer for channel = 7  _
 _  32  _   4  _ CIL_08   _ PCL pointer for channel = 8  _
 _  36  _   4  _ CIL_09   _ PCL pointer for channel = 9  _
 _  40  _   4  _ CIL_10   _ PCL pointer for channel = 10 _
 _  44  _   4  _ CIL_11   _ PCL pointer for channel = 11 _
 _  48  _   4  _ CIL_12   _ PCL pointer for channel = 12 _
 _  52  _   4  _ CIL_13   _ PCL pointer for channel = 13 _
 _  56  _   4  _ CIL_14   _ PCL pointer for channel = 14 _
 _  60  _   4  _ CIL_15   _ PCL pointer for channel = 15 _
 _______________________________________________________________








       Figure VII.10d CIL for Video/Program related data
 _______________________________________________________________ 
 _ Offset _ Length _  Name   _     Description             _
 _______________________________________________________________
 _   0  _   4  _ CIL_00   _ PCL pointer for channel = 0  _
 _   4  _   4  _ CIL_01   _ PCL pointer for channel = 1  _
 _   8  _   4  _ CIL_02   _ PCL pointer for channel = 2  _
 _  12  _   4  _ CIL_03   _ PCL pointer for channel = 3  _
 _  16  _   4  _ CIL_04   _ PCL pointer for channel = 4  _
 _  20  _   4  _ CIL_05   _ PCL pointer for channel = 5  _
 _  24  _   4  _ CIL_06   _ PCL pointer for channel = 6  _
 _  28  _   4  _ CIL_07   _ PCL pointer for channel = 7  _
 _  32  _   4  _ CIL_08   _ PCL pointer for channel = 8  _
 _  36  _   4  _ CIL_09   _ PCL pointer for channel = 9  _
 _  40  _   4  _ CIL_10   _ PCL pointer for channel = 10 _
 _  44  _   4  _ CIL_11   _ PCL pointer for channel = 11 _
 _  48  _   4  _ CIL_12   _ PCL pointer for channel = 12 _
 _  52  _   4  _ CIL_13   _ PCL pointer for channel = 13 _
 _  56  _   4  _ CIL_14   _ PCL pointer for channel = 14 _
 _  60  _   4  _ CIL_15   _ PCL pointer for channel = 15 _
 _  64  _   4  _ CIL_16   _ PCL pointer for channel = 16 _
 _  68  _   4  _ CIL_17   _ PCL pointer for channel = 17 _
 _  72  _   4  _ CIL_18   _ PCL pointer for channel = 18 _
 _  76  _   4  _ CIL_19   _ PCL pointer for channel = 19 _
 _  80  _   4  _ CIL_20   _ PCL pointer for channel = 20 _
 _  84  _   4  _ CIL_21   _ PCL pointer for channel = 21 _
 _  88  _   4  _ CIL_22   _ PCL pointer for channel = 22 _
 _  92  _   4  _ CIL_23   _ PCL pointer for channel = 23 _
 _  96  _   4  _ CIL_24   _ PCL pointer for channel = 24 _
 _ 100  _   4  _ CIL_25   _ PCL pointer for channel = 25 _
 _ 104  _   4  _ CIL_26   _ PCL pointer for channel = 26 _
 _ 108  _   4  _ CIL_27   _ PCL pointer for channel = 27 _
 _ 112  _   4  _ CIL_28   _ PCL pointer for channel = 28 _
 _ 116  _   4  _ CIL_29   _ PCL pointer for channel = 29 _
 _ 120  _   4  _ CIL_30   _ PCL pointer for channel = 30 _
 _ 124  _   4  _ CIL_31   _ PCL pointer for channel = 31 _
 _______________________________________________________________

CIL_##: This points to the next Play Control List for the data 
       whose channel number = ##. If this field contains zero, 
       the data blocks having that channel number are ignored. 
       This field is initialized before the Play is started by 
       the application and is updated by the system to point to 
       the next PCL in  the list as each  PCL is filled. This  
       field may be changed by the application.

The format of  each Play Control  List is  defined in Figure  
VII.11 and each field is further specified below.
                         
Play Control List (PCL) Format

There are Play Control List pointers  in the CIL, according to  
channel number and data type. Each  points to a structure list  
that controls the destinations of the data. This structure is a 
singly linked list of PCL's and may  be built as a circular or  
sequential list.

      
                         Figure VII.11
 _______________________________________________________________ 
 _ Offset _ Length _  Name   _     Description             _
 _______________________________________________________________
 _   0  _   1  _ PCL_Ctrl _ Control byte                 _
 _   1  _   1  _          _ Reserved                     _
 _   2  _   1  _ PCL_SMode _ Submode byte                 _
 _   3  _   1  _ PCL_Type _ Coding Information byte      _
 _   4  _   2  _ PCL_Sig  _ Signal to be sent on buffer  _
 _       _       _          _  full                       _
 _   6  _   4  _ PCL_Nxt  _ Pointer to next Play Control _
 _       _       _          _  List                       _ 
 _  10  _   4  _ PCL_Buf  _ Pointer to buffer            _
 _  14  _   4  _ PCL_BufSz _ Size of buffer               _
 _  18  _   4  _ PCL_Err  _ Pointer to error buffer      _
 _  22  _   2  _          _ Reserved                     _
 _  24  _   4  _ PCL_Cnt  _ Current offset               _
 _______________________________________________________________

PCL_Ctrl: This field is initialized to zero by the application 
          before the Play is started. 

   Bit 0 Buffer full

   If bit  0 is  set to  one, it  indicates that  the buffer  
   pointed to by this PCL is full. If the system needs to use 
   this buffer and the buffer full bit is set to one, then the 
   system terminates the Play and  returns an overrun error.  
   The system sets this bit to one if it determines that the 
   buffer of this PCL is full. 
  
   Bit 7 Data Error

   Bit 7 is set to one when an error has been detected in the 
   data transferred in the buffer. Additional information can 
   be provided: see description  of PCL_Err. The application  
   must then  clear  this  field before  the  buffer  can be  
   re-used.
 PCL_SMode: This field  is updated with  the value contained  in 
             the submode byte  of the  subheader of  the last  
             sector read into this PCL. This field must not be 
             changed at  any time  by the  application during  
             play.

 PCL_Type: This  field is  set by  the system  and contains  the 
           coding information byte of the subheader of the last 
           sector read into the buffer of this PCL. This field 
           should be used by the application for reference only 
           and should not be changed by the application.

 PCL_Sig:  This  field is  initialized  by  the application  and  
          contains the  signal  number  to  be  sent  to  the  
          application when the buffer of the PCL is full or an 
          error has been detected in  the data transferred in  
          the buffer. When the PCL and  PCB signals are to be  
          sent at the same time, the PCL signal is sent first, 
          followed by  the  PCB  signal.  This  field  may be  
          changed by the  application at any  time during the  
          execution of the Play. If this field contains zero,  
          then no signal is sent.

 PCL_Nxt:  This is  the pointer  to  the next  PCL element.  The  
          linked  list  of  PCLs,  which   is  built  by  the   
          application, contains at least one element. The list 
          may be circular or may be terminated by the entry of 
          a zero  in this  field. The  list  of PCL's  may be  
          manipulated by the application at any time during the 
          execution of the Play. 

   Note: When the buffer for a  PCL is full, the contents of  
   this field is placed in the CIL entry which references the 
   given PCL.

 PCL_Buf: This is  the address of the  buffer in which the  data 
          from  the  disc  is   to  be  stored.   It  is  the   
          responsibility of the application to make sure
 that this  points to  an allocated  data area  large enough  to 
    hold all the data requested for this PCL. If this pointer  
    is zero,  the data  is  not transferred  into  memory and  
    PCL_Cnt is not incremented. This  field is initialized by  
    the application and may be  changed by the application at  
    any time during the execution of the Play.

 PCL_BufSz: This specifies the  size, in sectors, of the  buffer 
             pointed to by PCL_Buf. This field is initialized  
             by the  application and  may  be changed  by the  
             application at any time  during the execution of  
             the Play. 

 PCL_Err: This field points  to the error information  structure 
          (shown in the table below). If this field contains a 
          zero, (No error information structure available) only 
          the "Data error" bit is  set in PCL_Ctrl, otherwise  
          information about the data in error is also returned 
          in the  given buffers.  These data  can be  used to  
          conceal errors in  video sectors  for instance (see  
          V.4.6.3).

   In both cases the buffer is filled and the Play continues: 
   it is  up  to the  application  to "abort"  the  play, if  
   necessary.
_________________________________________________________________

_Offset_Length_          Name           _          Description           
_
_________________________________________________________________

_  0   _   4   _Err_BufSiz  _Total   size   of   error  buffer   
_
_  4   _  1   _Err_Res  _Resolution   (b/w)  of   error  info.   
_
_         5          _          1          _         _Reserved          
_
_ 6  _  2  _Err_Cnt _No.  of  block(s)  containing  error(s) _  
_  8   _   2   _Err_Offset  _Offset   to   first   error  data   
_
_       _       _       _        block       (e.g.       26+N)        
_
_    10    _    8    _     _Reserved    for    system    use10     
_   _   18   _    8   _   _Reserved    for   application   use    
_
_     26     _     N     _Err_Blocks10_Block     error     Map      
_
_26+N    _     M     _     _First     error     data     block     
_
_________________________________________________________________

 Err_BufSiz: This field is used by the application to store the 
             total size of  the error  information structure.  
             The CD driver uses the  buffer size to determine  
             the maximum number of error data blocks to return. 
             It is possible to reserve no space for error data 
             blocks, in which case only one error flag bit per 
             block is returned.Err_Res:This byte is set by the 
             CD driver to the resolution size of one bit in the 
             error data block(s). The size of each error data  
             block is  dependent  on the  resolution,  so the  
             application must  determine the  resolution size  
             before allocating the error information structure. 
             It is  returned in  this  field as  a redundancy  
             check. Currently, this byte may  contain 1 or 2,  
             for byte or word resolution, respectively.

Err_Cnt: This word is set by the  CD driver to the number of  
         blocks that contain  any errors.  If no  errors are  
         encountered, this  field  contains  zero,  and  the  
         contents of the block error map and error data blocks 
         are undefined.

Err_Offset: This  field must  be set  by the  application to  
            contain the offset from the beginning of the error 
            information structure  to the  first  error data  
            block.  If  no  error  data  blocks  are  to  be   
            returned, this field may contain zero. The offset 
            of the first  error data  block must  be an even  
            number.

Err_Blocks: This field  is a  table built  by the  CD driver  
            containing a bitmap  of the blocks  read by this  
            play control list. Each block read is represented 
            by one bit in the table. If the bit is clear i.e. 
            zero, the block was read  without ANY ERRORS. If  
            the bit is set to one, at least one soft error was 
            detected in the block. The  amount of memory (in  
            bytes) reserved for the Err_Blocks table must be  
            at least the number of blocks to be read divided  
            by eight, rounded up to the nearest even integer. 
            The application needs to  clear the table before  
            passing it  to  CDFM.  If  NO  ERRORS  occur the  
            contents of the table are undefined.

Error data
 blocks: For each error bit set to one in the block error map, 
          an error data block may be returned (depending on the 
          size of the error information structure). The format 
          of the error data  block is a  bitmap. Each byte or  
          word (depending  on the  value  of Err_Res)  in the  
          sector containing errors is represented by one bit in 
          the error data block. If the bit is set to one, the 
          corresponding byte or word in  the data contains an  
          error. The bitmap contains error  bits for the sync  
          pattern, header, subheader, data and EDC (reserved)  
          fields of the sector.

   The size of  each error data  block is either  294 or 147  
   bytes long, depending on whether the resolution of the CD  
   controller is byte or word. Error data blocks are repeated 
   consecutively  to  the  end   of  the  error  information   
   structure. The CD driver stops producing error data block  
   information when the error  information structure becomes  
   too full to  store a complete  error data  block. In this  
   case, only the block  error map may  be used to determine  
   which sectors contain errors.
   
   The application does not need to clear the error data block 
   buffer area before passing it  to CDFM. Unused error data  
   blocks are not  initialized by  the CD  driver, and their  
   content is undefined.   

PCL_Cnt: This field  contains the  offset in  bytes into the  
         buffer of the next position to copy data. It should  
         be initialized to zero by the application before the 
         start of  a  Play.  This field  is  updated  by the  
         system, but it may be changed by the application at  
         any time during the execution of the Play.

 Play Termination:

 Play is terminated by any of the following conditions:
   1. EOF is encountered.
   2. PCB_Rec goes to zero.
   3. A software abort is received (SS_Abort, SS_Eject).
 4.  A  hardware  or  software  fatal  error  occurs  (error  in  
      header, etc.)













SS_CChan - Channel & Audio Channel Changing

This function causes a  change of channel  (PCB_Chan) or Audio  
channel (PCB_AChan)  selection  masks.  The  change  will take  
effect after the next selected sector (according to the previous 
PCB_Chan value) is retrieved from disc, regardless of the file  
contents (trigger, EOR, EOF bits).

Generally, this function is used  in conjunction with SS_Play.  
However, if there is also an SM_Out active during the SS_Play,  
this call will have no effect on the PCB_AChan mask until after 
the termination of the soundmap.

Input:  d0.w = Path number
    d1.w = SS_CChan setstat code

Output: None

Error Output: cc 
                 = Carry bit set to one
    d1.w = Error code

Possible Errors: E$BPNum


2.2.3.3 I$Seek - Change Path's Current File Position

This function causes the file position pointer to be set to the 
new value. This does not cause a  physical seek of the head on  
the player. The seek command uses  a sector size of 2048 bytes  
to compute the new file position.

Input:  d0.w = Path number
     d1.l = New file pointer byte position

Output: None

Error Output: cc  = Carry bit set to one
     d1.w = Error code

Possible Errors: 
E$BPNum



















             This page is intentionally left blank
2.2.3.4 I$Read  -  Read  Requested  Bytes  From  Current  File  
Position


Read reads the specified number of bytes from the file specified 
by the path number. Read can be used to read Mode 1 and Mode 2, 
Form 1  sectors. Mode  2 Form  2 audio  and video  sectors are  
skipped when reading a file. Read  returns only the first 2048  
bytes after: 

- the subheader for Mode 2 Form 1 sectors
- the header for Mode 1 sectors

Read makes use of the file and channel selection mechanisms to  
select the sectors to be read  from the disc. This file number  
is set to the file number  specified by the file descriptor of  
the open path. The  channel mask is set  to $FFFFFFFF when the  
file is opened. This causes the  selection of sectors with any  
channel mask in the subheader. The channel mask may be changed  
by rewriting the channel mask in the options section of the path 
descriptor using  the SetStat  system  call. If  there  is not  
enough data in the file to satisfy the Read request, fewer bytes 
are returned than requested. When all data in the file has been 
read, the next read  call on the  path returns an  end of file  
error.

Input: d0.w = Path number
 d1.l = Maximum number of bytes to read
   (a0) = Pointer to input buffer

Output: d1.l = Number of bytes actually read

Error Output: cc  = Carry bit set to one
   d1.w = Error code

Possible Errors: E$BPNum, E$BMode, E$Read, E$EOF







2.2.3.5 I$ReadLn - 
                  Read Requested Number of Bytes from Current 
                  File Position Until Character $OD or Maximum 
                  Requested

ReadLn functions the same as Read with the following exception: 
ReadLn reads data from the file until $OD is encountered or the 
requested number of bytes is read; whichever comes first.

Input: d0.w = Path number
 d1.l = Maximum number of bytes to read
   (a0) = Pointer to input buffer

Output: d1.l = Number of bytes actually read

Error Output: cc  = Carry bit set to one
 d1.w = Error code

Possible Errors: E$BPNum, E$BMode, E$Read, E$EOF


2.2.3.6 I$ChgDir - Change User's Default Directories


ChgDir changes one or both of the two default directories to the 
directory  specified  by  the  path   list.  The  two  default   
directories  are  the  execution  directory  and  the  working   
directory (see the RBF (Random  Block File manager) section of  
Appendix VII.1).  The access  mode byte  is used  to determine  
which of the two directories is being changed. Bit number 0 of 
the access mode denotes the working directory when set to one.  
Bit number 3 of the access mode denotes the execution directory 
when set to one.

 Input: d0.b = Access mode
   (a0) = Pointer to path list

 Output: (a0) = Updated past pathname

 Error Output: cc  = Carry bit set to one
   d1.w = Error code

 Possible Errors: 
E$BPNum, E$FNA,E$PNNA,E$BMode

2.2.4 Audio Functions

This section  specifies  the CDFM  Audio  Getstat  and Setstat  
functions.

2.2.4.1 Soundmap Control Functions

SM_Creat - Create Soundmap

SM_Creat creates a soundmap.

Input: d0.w = Path number
   d1.w = SS_SM setstat code
 d2.w = SM_Creat function code
   d3.w = Coding Information
   d4.w = Number of sound groups

Output: d0.w = Soundmap identifier
 (a0) = Soundmap address

Error Output: cc  = Carry bit set to one
   d1.w = Error code

Possible Errors: 
                 
                 E$BPNum, F$SRqMem, E$IllPrm

Coding Information Format:

           ________________________________________
           _          _           _ E _  AL _
           ________________________________________
       Bit 15                     4  3  2    0

    E = 1 - Emphasis ON
      0 - Emphasis OFF
     
   AL = Audio Level
   
     0 - Level A mono 
     1 - Level A stereo
     2 - Level B mono 
     3 - Level B stereo
     4 - Level C mono 
     5 - Level C stereo
   Soundmap descriptor
_________________________________________________________________

_Offset           Length            Name           Description            
_ 
_________________________________________________________________

_     0      2     SMD_Id      Id     of      the     soundmap      
_
_   2   2    SMD_StLoop   Start    of   Loop    for   loopback    
    _
_   4    2    SMD_EnLoop   End    of    Loop    for   loopback    
_
_       6        2       SMD_LpCnt        Loopback       count        
_    _     8     2    SMD_LCntr     Counter     for    looping     
_
_ 
_
_   10    4    SMD_SMAddr   Address    of    soundmap   itself    
_
_    14    4    SMD_SMSize    Actual    size    of    soundmap     
_  _   18   4   SMD_CurAddr   Current   address   of   playing   
_                          _                          soundmap                           
_
_    22     4    SMD_AysBlk     Pointer    to     ASY    block     
_
_   26   2   SMD_NoGrps   Number   of   soundgroups   in   map    
_
_   28   2    SMD_GrpNum   Group    which   started   sector's    
_
_                                                         play                                                          
_
_      30      1       SMD_Coding      Coding      information       
_      _      31      1       SMD_Res1      Reserved      Byte       
_
_    32    4     SMD_LpAddr    Start     address    of    Loop     
_
_          36           4           SMD_Res2          Reserved           
_
_          40           4           SMD_Res3          Reserved           
_
_          44           4           SMD_Res4          Reserved           
_
_________________________________________________________________

                                                                
SM_Out - Output Soundmap                                        

SM_Out causes the data  in the soundmap to  be output to the  
audio processor. If  another soundmap is  being output, then  
that output is discontinued after the current sector (18 sound 
groups) has finished playing, and the new soundmap is started.

If ADPCM audio is  being played from  the disc, the soundmap  
will override the audio from the disc for the duration of the 
soundmap. When  the soundmap  is  completed, the  audio will  
resume. Playing a  soundmap does not  interfere with sectors  
being transferred to memory.  If PCM audio  is being played,  
the SS_CDDA function is aborted before the soundmap is played.

SM_Out is an  asynchronous operation  and therefore  uses an  
asynchronous status block as described in Figure VII.10a.
  
Input: d0.w = Path number
   d1.w = SS_SM setstat code
   d2.w = SM_Out function code
   d3.w = Soundmap identifier
  (a0) = Pointer to asynchronous Status Block
Output: None

Error Output: cc  = Carry bit set to one
   d1.w = Error code
     
Possible Errors: E$BPNum, E$UnID

SM_Off - Turn Off Soundmap Output

SM_Off  causes  output  from  the  current  soundmap  to  be   
discontinued and the audio processor to be turned off.

Input: d0.w = Path number
   d1.w = SS_SM setstat code
   d2.w = SM_Off function code
  
Output: None

Error Output: cc  = Carry bit set to one
   d1.w = Error code
     
Possible Errors: E$BPNum

SM_Close - Close Soundmap

SM_Close de-allocates the memory associated with a soundmap.

Input: d0.w = Path number
    d1.w = SS_SM setstat code
    d2.w = SM_Close function code
    d3.w = Soundmap identifier

Output: None

Error Output: cc  = Carry bit set to one
    d1.w = Error code

Possible Errors: E$BPNum, F$SRtMem, E$UnID

SM_Cncl - Conceal Error in Soundmap

SM_Cncl will perform the error concealment function provided  
by the audio driver. 

Input: d0.w = Path number
   d1.w = SS_SM setstat code
   d2.w = SM_Cncl function code
   d3.w = Soundmap identifier
   (a0) = Pointer to error data
      
Output: None

Error Output: cc 
                 = Carry bit set to one
   d1.w = Error code

Possible Errors: E$BPNum, E$UnID

SM_Info - Return Pointer to Soundmap Descriptor

SM_Info returns  pointer  to  the  soundmap  descriptor  for  
information purposes.

Input: d0.w = Path number
  d1.w = SS_SM getstat code
    d2.w = SM_Info function code
   d3.w = Soundmap identifier

Output: (a0) = Pointer to Soundmap Descriptor

Error Output: cc  = Carry bit set to one
    d1.w = Error code

Possible Errors: E$BPNum, E$UnID
 
SM_Stat - Return Soundmap Status 

SM_Stat returns information about the soundmap currently being 
played. This call passes a buffer which is initialized by the 
driver.

Input: d0.w = Path number
   d1.w = SS_SM getstat code
   d2.w = SM_Stat function code
   (a0) = pointer to soundmap status block

Output: (a0) = 
               pointer to soundmap status block

  format of soundmap status block

  Offset Length  
                  Description
   0 2   sector number currently being played
   2 2   total sectors in soundmap
   4 2   loops remaining for this sector
   6 2   reserved

Error Output: cc 
                  
                 = 
                 Carry bit set to one
          d1.w 
                = 
                Error code

Possible Errors: 
                       E$BPNum 
                       

2.2.4.2 Sound Data Manipulation Functions


SD_MMix - Mix Monaural to Stereo

The data  from two  monaural input  soundmaps is  mixed into  
stereo and  placed in  the  output soundmap.  The  two input  
soundmaps must be of  the same level.  Mixing start point of  
input soundmap 1  is given by  input parameter.  The size of  
mixing is determined as the minimum size of three soundmaps.

Input: d0.w = Path number
    d1.w = SS_SD setstat code
    d2.w = SD_MMix function code
    d3.w = Input soundmap 1 identifier
  d4.w = Input soundmap 2 identifier
   d5.w = Output soundmap identifier
   d6.w = Mix start sector number for input soundmap 1

Output: None

Error Output: cc  = Carry bit set to one
    d1.w = Error code

Possible Errors: 
                E$BPNum, E$UnID


SD_SMix - Mix Stereo to Stereo

The left/right channel  data of  one channel  from the first  
specified soundmap is mixed with the left/right channel data  
of one channel from the second specified soundmap and placed  
in the output soundmap.  The two input  soundmaps must be of  
the same  level.  In  all cases,  the  data  from  the first  
soundmap is put in the left channel of the output soundmap and 
the data from the second soundmap is put in the right channel 
of the output soundmap. Mixing start point of input soundmap  
1 is  given  by  input  parameter.  The  size  of mixing  is  
determined as the minimum size of three soundmaps.










Input: d0.w = Path number
   d1.w = SS_SD setstat code
   d2.w = SD_SMix function code
   d3.w = Input soundmap 1 identifier
   d4.w = Input soundmap 2 identifier
   d5.w = Output soundmap identifier
   d6.w = Mix start sector number for input soundmap 1
   d7.w = Left/right selection
    0 = Left channels of both soundmaps
 1  =  Left  channel  of  soundmap  1  and  right  channel  of  
         soundmap 2  
 2  =  Right  channel  of  soundmap  1  and  left  channel  of  
         soundmap 2
    3 = Right channels of both soundmaps

Output: None

Error Output: cc  = Carry bit set to one
   d1.w = Error code

Possible Errors: E$BPNum, E$UnID

SD_Loop - Set Soundmap Loopback Points

SD_Loop sets  the loopback  points  for a  soundmap.  If the  
loopback points are  set when  this soundmap  is played (via  
SM_Out), only the portion of the soundmap between the starting 
and ending sound groups is played. This portion will play the 
number of times specified by the loop count parameter.

If the soundmap  is already being  output when  this call is  
made, output will continue until the audio processor reaches  
(or is past) the end sound group, at which time the loop count 
is decremented and the  looping section is  played again, if  
necessary.

The loopback points are specified in terms of sound groups but 
they will be rounded to sector boundaries (an integer multiple 
of 18  sound groups)  such  that the  sector  containing the  
starting sound group is played and the sector containing the  
end sound group is played.

Input: d0.w = Path number
   d1.w = SS_SD setstat code
   d2.w = SS_Loop function code
   d3.w = Soundmap identifier
 d4.w = Starting sound group number
   d5.w = Ending sound group number
  d6.w = Loop count

Output: None

Error Output: cc  = Carry bit set to one
 d1.w = Error code

Possible Errors: E$BPNum, E$UnID


2.2.4.3 Sound Control Functions

SC_Atten - Set Attenuation

The decoded left and right sound signals are both mixed into  
the final left and right output  signals of the CD-I player.  
This essentially results in four signal paths, right to right, 
left to right,  left to  left, and  right to  left. SC_Atten  
controls the amount of  signal attenuation in  each of these  
paths. This function's  uses include control  of the overall  
volume of  sound, adjust  balance for  stereo sound,  and to  
adjust the position of a sound in the stereo space.

Input: d0.w = Path number
   d1.w = SS_SC setstat code
   d2.w = SC_Atten function code
   d3.l = Attenuation values

Output: None

Error Output: cc  = Carry bit set to one
   d1.w = Error code

Possible Errors: E$BPNum, E$UnID

 Attenuation Values Format: _________________________________
      _       LLA       _      LRA       _       RRA      _       RLA       
_
                               
_________________________________
                bit 31                           0  
     LLA = Left input to left output attenuation
     LRA = Left input to right output attenuation
     RRA = Right input to right output attenuation
     RLA = Right input to left output attenuation
2.2.5  Open and Close Service Requests

This section specifies the I$Open and I$Close service requests  
used to  open  and  close  paths to  CD  files  and  the Audio  
Processor.

2.2.5.1 I$Open - Open Path to Specified Device/File

This call is used to get  all necessary information and set up  
all necessary data structures to be able to access a particular 
file or the Audio  processor. If successful,  a path number is  
returned which is used in subsequent I/O calls to identify the  
open file or device.

 Input:  d0.b = Access mode
    (a0) = Pointer to pathname

 Output:  d0.w = Path number
    (a0) = Update past pathname

 Error Output: cc  = Carry bit set to one
    d1.w = Error code

 Possible Errors: 
                  E$PthFul, E$BPNam, E$FNA, E$PNNF, E$BMode
    E$Share
 Access Mode Format:
    CD-DA files (see  p.III.21) must be  opened with "Access  
    Mode = 0"

         _____________________________________________
         _ Bit Number  _ Description (if set to one)_
         _____________________________________________ 
         _ 0       _ Read                      _
         _ 1       _ Write (audio only)        _
         _ 2       _ Execute                   _
         _ 3-5     _ Reserved                  _
         _    6       _ Non-shareable use         _
         _    7       _ Directory                 _
         _____________________________________________

When opening files on the CD-I disc, there is a measure of file 
security provided for by CDFM.  This is in the  form of a file  
owner and an  attribute field. Each  file has  a group/user ID  
that identifies the file's owner (see III.3.2 Owner ID/Attribute 
fields). The attribute field tells CDFM  in which modes a file  
may be accessed. These  fields indicate whether  a file may be  
opened for reading or for execution by the owner, by anyone in 
the owner's group, or by the public. Public means any user with 
a different group ID.


Whenever a file is opened, access permissions are checked on all 
directories specified  in the  pathlist, as  well as  the file  
itself. If  the  user  does  not  have  permission  to read  a  
directory, then  the  user  may not  read  any  files  in that  
directory. 
A super user (a user with a group ID of 0) may access any file  
in the system. Files containing modules  that are owned by the  
super user must also be  owned by the super  user. If not, the  
modules contained within the file will not be loaded.

In all of  these cases the  "user's ID" is  inherited from the  
process  which  spawned  (forked)  the  application  which  is   
currently running. However, if  the application primary module  
is owned by the super user, the application process may change  
its ID at any time (through F$SUser) thus making a different set 
of "protected" files available for access.

Opening a Raw Device

If a process has a super user ID  it may open a device for Raw  
I/O. This allows the process to  access the information on the  
device independently of  the file  structure. To  do this, the  
process would append the  "@" symbol to the  end of the device  
name when  executing I$Open,  e.g.  "/cd@". This  is  the only  
mechanism for accessing structures such as the disc label.

2.2.5.2 I$Close - Close a File

Close terminates the use  of the I/O path.  It causes the path  
number and all memory used to support the path to be returned to 
the system. If there is an asynchronous I/O function executing  
on this path the Close function aborts the asynchronous routine 
before returning to the application.

Input:  d0.w = Path number

Output:  None

Error Output: cc  = Carry bit set to one
    d1.w = Error code

Possible Errors: E$BPNum








2.3  User Communications Manager (UCM)

2.3.1  Introduction


This section  describes  the  functions  and  capabilities of  the    User 
Communications Manager  (UCM)  and  its  associated  drivers.   The    UCM 
provides the software interface  to a CD-I player's  video output   device 
and user input devices.  Content providers will use the UCM functions   in 
their application programs to provide meaningful and interactive    visual 
presentations to  the  users of  CD-I  players.  The  UCM  provides    the 
following functional capabilities:

Support  for  the  CD-I   system's  visual  effects  and   image    mixing 
capabilities.  Content providers have available to them well known  motion 
picture techniques  such  as  pans,  wipes,  fades,  mattes,  cuts,    and 
dissolves.

Ability to create and maintain many separate images in memory and to  copy 
and exchange parts of images in various ways.   This allows   applications 
to create a background image and images of  separate foreground   objects. 
The foreground images  can be  placed on the  background image  and   even 
moved around, creating an animation effect.

A set  of two  dimensional graphics  drawing functions  for  creating   or 
modifying images.  The drawing functions include line, arc, filled  areas, 
and a powerful form of the bit block transfer.

High quality text in multiple fonts, sizes, and  styles. Characters   sets 
for virtually all languages can be supported.

Functions for user input devices such as keyboards and mice are   provided 
so that content providers may create interactive applications.

The User  Communications  Manager  also  provides  hardware    independent 
support for  user  input-output functions.   It  will not  matter  to   an 
application whether  a particular  function is  emulated in  software   or 
executed by a hardware coprocessor.  The function set is also designed  to 
be executed efficiently in a real-time environment yet be powerful  enough 
to implement higher level functions.
UCM supports the following service requests:

_________________________________________________________________
_Name             _ Description                                 _
_________________________________________________________________
_Open             _  Open path  to specified  device (see           _    _ 
_ VII.2.3.3.1)                                _ _Read             _   Read 
characters  from  the  keyboard            _  _                  _    (see 
VII.2.3.6)                             _
_Write/WriteLn    _ Write text to the display (see VII.2.3.4.8) _
_Getstat          _ Get specified status information            _
_Setstat          _ Set specified status information            _
_Close            _ Close path to specified device (see         _
_                 _ VII.2.3.3.2)                                _
_________________________________________________________________

For a more detailed description see A VII.1.


2.3.2  Features and Concepts

This section of the specification describes the major features and   basic 
concepts upon which the User Communications subsystem is built.


2.3.2.1  Environment

The User Communications  Manager conforms  to the standard    input-output 
architecture used in CD-RTOS.  The diagram in Figure VII.12 shows how  the 
different parts (or levels) of the system are  related to each other   and 
the  application.    Any  input-output   subsystem  within   CD-RTOS    is 
implemented on three levels.  On the top level is the CD-RTOS kernel.   It 
defines the application interface to the input-output system.  The  lowest 
level is the driver  which interfaces to the  actual hardware    involved. 
The drivers  implement  a set  of  functions which  are  designed  for   a 
particular class of  hardware device.   For example, drivers  for   Random 
Block File  Manager  (for disks)  have  functions which  read  and   write 
sectors and  format  the disk  (see  Appendix VII.1).  Drivers  for    the 
Sequential Character  File Manager  (for CRT  terminals) read  and   write 
characters.  The file manager is at the intermediate  level.  One of   its 
responsibilities is to act as a
translator between kernel  functions and  driver functions.  The    kernel 
defines the input-output  functions to  be the same  for all  classes   of 
devices whereas the driver does not.  The file manager also performs   any 
house-keeping duties which are required for its class of device.
Figure VII.12

                                               _________________
                                            ____Keyboard Driver_
                                            _  _________________
____________   ___________   ____________   _
_   CD-I   _   _ CD-RTOS _   _   UCM    _   _  _________________
_  Appli-  _____ Kernel  _____   File   ________Pointer Driver _
_  cation  _   _         _   _  Manager _   _  _________________
____________   ___________   ____________   _
                                            _  _________________
                                            ____ Video Driver  _
                                               _________________


2.3.2.2  Display Architecture


An example of  the video  section of a  CD-I player  is shown  in   Figure 
VII.13.  There are three entities which perform the graphics functions,  a 
drawing processor,  a memory  access controller,  and a  video   real-time 
decoder.  The drawing processor (whose functions are performed by the  MPU 
in the example) executes all of the drawing and text functions and can  be 
implemented in hardware or emulated in software.  It is also   responsible 
for the creation and maintenance of images in the player's memory   (RAM). 
The memory access controller (MAC) retrieves pixel data  from the   memory 
and passes it  to the  video real-time decoder  for display.   The    CD-I 
system requires that two memory access controllers be used.  Each   memory 
access controller processes a  single image plane.  The  video   real-time 
decoder takes the pixel data given to it  by the MACs and converts it   to 
its representative  electrical signals.   For more  details see    Chapter 
V.4.1.


Figure VII.13

                  _____________  _____________
_____________  ____    RAM    ____    MAC    ____  _____________
_           _  _  _____________  _____________  ____   VIDEO   _
_    MPU    ____                                   _ REAL-TIME _
_           _  _  _____________  _____________  ____  DECODER  _
_____________  ____    RAM    ____    MAC    ____  _____________
                  _____________  _____________

2.3.2.3  Drawmaps

The primary data object  for the UCM and  video driver is  the   draw-map. 
Drawmaps are used to  store images.  Applications may  draw on    drawmaps 
using the  drawing  functions.  A  drawmap  may be  virtually  any   size, 
limited only by the memory space available.

The drawmap has two  formats, the rectangular array  format and the   list 
format.  In the  array format,  each element of  the array  represents   a 
single pixel.  The array is two dimensional and each element of the  array 
corresponds to a  single pixel.   The position of  the pixel  within   the 
array also corresponds to its position on the display screen.  Each   line 
of pixels in  the array  must be an  integral number  of long  words    in 
length.

The list format is  provided to support run-length  coding.  In the   list 
format drawmap, each element represents a sequence of  pixels which   have 
the  same  color  or   pixel  value.   Since  there   is  no    one-to-one 
correspondence between a pixel coordinate and its location  in the   list, 
graphics drawing functions  can not  be used on  a list  format   drawmap. 
Each line of pixels is represented in the  list by an integral number   of 
bytes.

Since  the  CD-I  video   hardware  allows  pixels  to   have    different 
representations, drawmaps have a data type.  The allowable data types  are 
four-bit CLUT, seven-bit CLUT, eight-bit CLUT, RGB 555, DYUV and (for  the 
extended case)  DYUV +  QHY.  Since  an individual  pixel's  color   value 
depends on the values of all previous pixels  in the line, the    graphics 
drawing functions may not be used on a DYUV type drawmap.  The DYUV   type 
drawmap may, however, be manipulated using the drawmap control functions.

When an  image comprises  two or  more differently  coded  subscreens,   a 
separate drawmap should be defined for each subscreen.

Every drawmap also has associated with it a line pointer table. This is  a 
linear array of pointers to the beginning of  each line in the    drawmap. 
An RGB 555 drawmap occupies two blocks of  memory and therefore   requires 
two line pointer tables.   List format drawmaps also  have line    pointer 
tables, but only the first entry is actually  initialized by the   driver. 
The line pointer  table may  be used to  eliminate the  need for   copying 
lines of the  drawmap around  when an error  in video  data needs  to   be 
concealed. It also helps simplify the setup of a display control   program 
for displaying the drawmap.

The drawing functions may be used on List Format (RL3 and RL7)   drawpmaps 
provided that the  application has  initialized the line  pointer   table. 
The application should be aware that unpredictable results may occur.
2.3.2.4  Display Control Program

Drawmaps and  their associated  functions are  concerned only  with    the 
management and manipulation  of images  in memory.  The  display   control 
program (DCP) determines  how those  images will appear  on the    display 
screen.  Application programs  use display  control programs to    perform 
functions such as matte, wipe, or scroll. The display control program   is 
essentially a  set  of instructions  which  are performed  by  the   video 
display hardware when it is not busy retrieving and displaying pixel  data 
(i.e. during vertical and horizontal retrace periods).

There are  two  Display Control  Programs,  one for  each  display   path, 
operating in  conjunction.   A display  control  program has  two    major 
components, the field  control table  (FCT) and the  line control    table 
(LCT).   The  field  control  table  is  a  one   dimensional  array    of 
instructions which are interpreted by the display hardware  during   every 
vertical retrace period.  The maximum length of the field control   table, 
available to the application, is 1024 instructions.

The line  control  table is  a  two dimensional  array  of   instructions. 
Successive  lines  of  instructions  in  the  line  control   table    are 
interpreted by the display hardware during successive horizontal   retrace 
periods prior to the display of lines of pixel data.  The maximum   number 
of instructions  that may  be interpreted  during a  horizontal    retrace 
period is eight in a Base Case CD-I system.  The maximum number of   lines 
in the line control table is 65535.  An  LCT is not required, if one    is 
used it has a minimum size requirement of two lines.

For RGB 555, which occupies both display paths, two LCTs and two FCTs  are 
needed.  These must  be independently  created, in separate  planes,   and 
written to.

The UCM provides many functions for manipulating field  and line   control 
tables.  For field control tables, functions are provided for reading  and 
writing any number of instructions.  For line control  tables,   functions 
are provided for reading and writing rectangular arrays  of any size   and 
single instructions.  The application is also able to create an  arbitrary 
number of these tables, load them with instructions,  and rapidly   switch 
between them for high speed special effects.

An example of a DCP and the sequence  of its interpretation is shown    in 
Figure VII.14.  At  the beginning  of the vertical  retrace period,    the 
display control hardware interprets the instructions in the selected  FCT. 
Interpretation of the FCT  is completed before the  start of the    active 
display period.

Figure VII.14

             ______________________________________
             _             FCT            _ Link  _
             ______________________________________
                           ____________________
                           _
                 ______________________
                 _                    _ Display line 0
                 ______________________       .
                 _                    _       .
                 ______________________       .
                 _                    _       .
                 ________  LCT ________       .
                 _          .         _       .
                 _          .         _       .
                 _          .         _       .
                 ______________________       .
                 _                    _       .
                 ______________________       .
                 _                    _ Display line Lmax
                 ______________________

Contained within the  field control  table is a  link to  a line   control 
table (set by the DC_FLnk function).  This link can point to any line   of 
the line control table, not just to the  beginning. Immediately prior   to 
the display of the  first line of pixels,  the display control    hardware 
will interpret the instructions contained in the line of the LCT   pointed 
to by this link.   For 625 and 525  line systems image  interchange,   the 
application can create a line control table whose length is equal to   the 
number of display lines (see A.V.2.2.2).

In the simplest case the display control hardware continues to   interpret 
successive lines of the LCT, along with its associated video data,   until 
the last line of the display is completed. The interpretation process   is 
then repeated  for the  next display  field.  For  interlaced  scan   high 
resolution the two halves of the LCT are interpreted in alternate fields.

A display control program may also have several line control tables  which 
can be linked together in a manner similar to the way an FCT links to   an 
LCT.  An example of a multiple LCT display  control program is shown    in 
Figure VII.15.  When the display control hardware sees a link in an   LCT, 
it will interpret instructions beginning with the line in the LCT  pointed 
to by the link at the next horizontal retrace period.  Multiple LCT's   in 
a
DCP may be used for the construction of  subscreens on the display.     By 
manipulation of  the links  between LCT's,  scrolling in  subscreens    is 
easily performed.

Figure VII.15

            ______________________________________
            _             FCT            _ Link  _
            ______________________________________
                   ___________________________
                   _
            _________________
             _               _                      Display line 0
            _________________                             .
            _               _                             .
            _________________     _________________       .
            _               _     _               _       .
            _________________     _________________       .
            _               _     _               _       .
            _______________________________________       .
            _               _     _               _       .
            _               _     _________________       .
            _     LCT 1     _     _               _       .
            _               _     _________________       .
            _________________     _               _       .
                                  _               _       .
                                  _               _       .
                                  _     LCT 2     _Display line
                                  _________________        Lmax


Video Events

A DCP  instruction is  available to  provide synchronization  to   Display 
Scanning (see V.5.6).  The video interrupt which occurs when the  selected 
display line is reached can be detected using the CD-RTOS F$Event   system 
call or the DC_SSig system call.

When the  video  driver  is  initialized  it  creates  an  event     named 
"line_event".  The  driver, when  a video  interrupt occurs,  pulses   the 
event to  the  value  one  using  Ev$Pulse.   To  access  the  event    an 
application must link to  it using the Ev$Link  function.  This   function 
returns an event identifier which is used as  a parameter to the   Ev$Wait 
and Ev$WaitR functions to wait for the video interrupt event.  Note   that 
Ev$Read cannot be used since the driver uses the Ev$Pulse function.   When 
finished with the event, the application should unlink it using  Ev$UnLnk. 
For more information see Appendix VII.1.

High Resolution (Extended Base Case)

High resolution  images  may  be  displayed  either  in  interlaced     or 
line-sequential mode. To ensure  that any high resolution  image may    be 
displayed in either mode without unacceptable constraints or overheads  it 
is recommended that the application should:

      1)   Create a drawmap with even and odd lines separated.
           This organization is suitable for either scan mode.

      2)         Create one high  resolution FCT which, for   interlaced 
            scan mode, may  need to be duplicated by the video driver.

      3)         Create one high  resolution LCT which, for   interlaced 
            scan displays, will  be physically  organized with   odd/even 
            lines separated.

     4)    Write display start address instructions in lines 0 and 1  of 
         the LCT for each display field.

Note:  If  the  application creates  a  drawmap and  LCT  organized    for 
line-sequential display, explicit line start pointers must be inserted  in 
every line of the LCT.  This is to allow interlace display.

DCP Instructions

The instructions which are contained in the display control programs   are 
all 32-bit  long  words.   These  instructions  consist of  an  op    code 
followed by a 24-bit parameter.  A summary of the available   instructions 
is provided in Figures VII.16-18 along with explanations of   restrictions 
on their use.  Complete  descriptions of these commands  can be found   in 
Chapter V.  Figure VII.16 describes the control table  entries   available 
for plane  0 only,  Figure VII.17  describes the  control  table   entries 
available for plane 1 only, and Figure VII.18 describes the control  table 
entries available for both planes.

The application is required to provide a display control program for  each 
image  plane.   These  two  display  control  programs  are    interpreted 
concurrently by the display control hardware.  The instructions   specific 
to each plane are controlled only by the display control program in   that 
plane.  Most global control  instructions must be placed  in the   display 
control program for path 0, however, some may be used in both planes.

Figure VII.16

    Control program instructions available for path 0 only
______________________________________________________________
_Code_            Action                      _ Parameter    _
______________________________________________________________
_$C0 _Select image coding methods             _ V 4.6.1      _
______________________________________________________________
_$C1 _Load transparency control information   _ V 5.7.3      _
______________________________________________________________
_$C2 _Load plane order                        _ V 5.7.1      _
______________________________________________________________
_$C4 _Load transparent color for plane A      _ V 5.7.2.2    _
______________________________________________________________
_$C7 _Load mask color for plane A             _ V 5.7.2.2    _
______________________________________________________________
_$CA _Load DYUV start value for plane A       _ V 4.6.2      _
______________________________________________________________
_$D8 _Load backdrop color                     _ V 5.13       _
______________________________________________________________
_$D9 _Load mosaic pixel hold factor for A     _ V 5.11.1.1   _
______________________________________________________________
_$DB _Load image contribution factor for A    _ V 5.9        _
______________________________________________________________

            Figure VII.17

     Control program instructions available for path 1 only
_______________________________________________________________
_Code_            Action                       _ Parameter    _
_______________________________________________________________
_$C6 _ Load transparent color for plane B      _ V 5.7.2.2    _
_______________________________________________________________
_$C9 _ Load mask color for plane B             _ V 5.7.2.2    _
_______________________________________________________________
_$CB _ Load DYUV start value for plane B       _ V 4.6.2      _
_______________________________________________________________
_$DA _ Load mosaic pixel hold factor for B     _ V 5.11.1.1   _
_______________________________________________________________
_$DC _ Load image contribution factor for B    _ V 5.9        _
_______________________________________________________________

Figure VII.18


     Control program instructions available for both paths


________________________________________________________________
_Code  _           Action                       _ Parameter    _
________________________________________________________________
_$10   _No operation                           *_      -       _
________________________________________________________________
_$20   _Load LCT pointer                       *_ Note 1       _
________________________________________________________________
_$40   _Load display line start pointer        *_ V 4.5.2.2    _
________________________________________________________________
_$60   _Signal when scan reaches this line     *_ V 5.6        _
________________________________________________________________
_$78   _Load display parameters                *_ V 4.6.1      _
________________________________________________________________
_$80-BF_Load CLUT color 0-63 (of current bank)  _ V 5.5        _
________________________________________________________________
_$C3   _Set CLUT bank                          *_ V 5.5        _
________________________________________________________________
_$DO-D7_Load matte register 0-7                 _ V 5.10.3     _
________________________________________________________________
_$80-87_Load QHY level 0-7                      _ V 4.4.3.4    _
________________________________________________________________
_$C3   _Set QHY bank                            _ V 4.4.3.4    _
________________________________________________________________

* = This action may be set independently in each path.


Note 1

This instruction may only be written by means  of the UCM calls    DC_LLnk 
and DC_FLnk.  It is the responsibility of the application to insure   that 
space is  left in  the LCT  or FCT  by  means of  this mechanism    before 
executing the DC_LLnk or DC_FLnk commands.










2.3.2.5  Coordinate Transformation


The User  Communications  Manager  uses  a  variation of  the    Cartesian 
Coordinate System  to  address  pixels  within  a  drawmap.   The    UCM's 
coordinate system differs  from Cartesian  coordinates in that    vertical 
coordinates increase in value from top to bottom, rather than from  bottom 
to top.  Horizontal coordinates, as in the Cartesian system, increase   in 
value from left to right.  The UCM also limits the range of   coordinates. 
The minimum possible coordinate is -32768 and the maximum is 32767.    The 
origin (point 0,0) is also variable for each drawmap.  The origin can   be 
set at the top-left corner of the drawmap, the center of the drawmap,   or 
even at  the outside  of the  drawmap.  The  UCM  also differs  from   the 
Cartesian system in that  the precision of coordinates  is not   infinite. 
Coordinates for UCM are restricted to integer values.

To maintain resolution independence, application programs need to 'see'  a 
single coordinate  space for  all drawmaps.   In other  words,  a   circle 
should appear to be  the same size on  the display screen  whether it   is 
drawn in a normal, double, or high resolution drawmap. The UCM fills  this 
need by having  applications treat  all drawmaps as  if they  were    high 
resolution drawmaps.  If the  drawmap is not a  high resolution    drawmap 
then the coordinates specified by the application are scaled according  to 
the actual resolution of the drawmap.

Consequently, coordinate values as well as dimensions (height, width)  are 
always expressed according to High Resolution conventions in this  chapter 
except when otherwise mentioned.



2.3.2.6 Regions


Regions divide the set  of points in the  UCM coordinate space  into   two 
disjoint sets of points.   Their main uses are  for graphics drawing   and 
construction of mattes.  When drawing, regions are used to limit the  area 
of drawing in a drawmap.  The shapes specified  by a region can also    be 
drawn.  The data in the region data structure  is also suitable for    use 
with the setup of mattes using the display control program functions.






Regions are  created  from the  basic  shapes of  rectangle,    elliptical 
cornered  rectangle,  polygon,  circle,  circular  wedge,  ellipse,    and 
elliptical wedge.   More complex  shapes are  created from  these    basic 
shapes using intersection, union, exclusive-or, and difference  functions. 
Regions may be  any shape  or size, however,  the region  data   structure 
itself is limited to 65536 bytes in length.

The region data structure  has three parts, the  region header, the   line 
offset table, and the transition data table.  The region header   contains 
general information about the region.  The line offset table is a list  of 
offsets to each line  of transition data in  the transition data    table. 
The transition data table has lists of horizontal points which   represent 
the transition points  in and  out of the  region for  each line  in   the 
region.  The data in the region is in UCM coordinate form.

The format of the region header is specified below.

Region Header Format
_________________________________________________________________
_Offset _ Length _                 Description                  _
_________________________________________________________________
_  0    _   2    _ Region identifier                            _
_  2    _   1    _ Region type (see VII.2.3.4.3)                _
_  3    _   3    _ Reserved                                     _
_  6    _   2    _ Length (in bytes) of region data structure   _
_  8    _    2    _  Horizontal coordinate of  upper left  corner of_    _ 
_        _ boundary rectangle                           _
_ 10    _    2    _  Horizontal coordinate of  lower right  corner  _    _ 
_        _ of boundary rectangle                        _
_ 12    _    2    _  Vertical coordinate of  upper left  corner of   _   _ 
_        _ boundary rectangle                           _
_ 14    _    2    _  Vertical coordinate of  lower right  corner of  _   _ 
_        _ boundary rectangle                           _
_________________________________________________________________

The line offset table,  which directly follows the  region header, is    a 
list of unsigned  16-bit integers  which have the  byte offset  from   the 
beginning of the  region data  structure to the  transition data  in   the 
transition data table for that line.  The first entry in the table  points 
to the transition data for the first line  in the region.  The    vertical 
coordinate of the upper left corner of the region's boundary rectangle  is 
the first line in the region. If there  is no transition data for a   line 
in a region, then  the corresponding entry in  the line offset  table   is 
zero.



The transition data table is a list of lists and immediately follows   the 
line offset table.  There is one sublist for each line in the region   for 
which there is transition  data.  The first 16-bit  word in each   sublist 
contains the number of transition pairs in that sublist.  Each  transition 
pair that follows is a pair of 16-bit words.  The first word in the   pair 
is the horizontal coordinate  of the transition into  the region and   the 
second word in the  pair is the horizontal  coordinate of the   transition 
out of the region.  Both transition points are  considered to be in    the 
region.




2.3.2.7  Graphics Drawing


Basic drawing functions  such as  line, rectangle, circle,  and arc    are 
provided by the UCM and video driver.  It is also possible to draw   these 
elements using different sizes and patterns of lines.  Arbitrary   bounded 
regions of drawmaps may also be filled using  a pattern.  A form of    the 
bit block transfer is also provided.  All of the drawing primitives   also 
perform logical or arithmetic operations between the drawing data and  the 
drawmap data.




2.3.2.8  Pattern Indirect Drawing


Pattern Indirect  Drawing  is  the  method  used  by  graphics     drawing 
operations to transfer  pixel data  to the drawmap.   The pattern  is    a 
sixteen by sixteen pixel  bitmap.  Like drawmaps, patterns  also have    a 
data type.  The allowable data types are the  same as those for   drawmaps 
except that DYUV  is not  allowed.  Patterns can  also have    single-bit, 
double-bit, and quad-bit data types.  When these data types are used,  the 
pixels are expanded using a set of color  registers to obtain the   actual 
data that  will be  drawn in  the drawmap.   The  pattern's pixel    value 
selects which color register  the drawing data is  obtained from.     This 
compression technique is also very useful for fonts, which could take   up 
a large amount of space if actual pixel data were to be used.


To determine which pixel in a pattern is used to draw a specific pixel  in 
a drawmap, a correspondence is made between the  pixels in a drawmap   and 
the pixels  in a  pattern.  Since  a drawmap  is  usually larger  than   a 
pattern, many pixels in  the drawmap correspond to  a single pixel  in   a 
pattern.  In most cases, pixel (0,0) in the  drawmap correspond to   pixel 
(0,0) in the pattern. Pixels (16,0), (32,0), and  (48,0) also   correspond 
to pixel (0,0)  of the  pattern.  Likewise, pixels  (0,16), (0,32),    and 
(0,48)  also   correspond  to   pixel  (0,0)   of  the   pattern.     This 
correspondence, which  is  called alignment,  is  also adjustable.     For 
example, pixel (0,0) of the drawmap can be  made to correspond to    pixel 
(1,1) of the pattern.

2.3.2.9  Character Output Encoding

Due to the international use of CD-I, the UCM and the video driver do  not 
support any one character code standard for their text output   functions. 
They only  provide  the basic  mechanisms  so that  all  character    code 
standards may  be supported.   The UCM  and the  video  driver only    use 
character codes to  select glyphs  from a font  module.  A  glyph is   the 
bitmap image of a symbol.  For example, the  bitmap image for the   letter 
'a' is a glyph for the letter 'a'.

All of the glyphs in a font module are numbered using an unsigned  sixteen 
bit integer.  This glyph number is required to access a glyph in a   font. 
Since some  character  code standards  have  codes which  are  eight   bit 
quantities and some have codes which are sixteen bit quantities, the   UCM 
provides three  methods  of  interpreting  (e.g.  translating  to    glyph 
numbers) the character  data passed  to the text  functions, eight    bit, 
seven/fifteen bit, and sixteen bit.  The eight bit  method is usable   for 
most alphanumeric type languages.   When the eight bit  method is    being 
used only those glyphs  in a font which  are numbered from  0 to 255   are 
accessible.  In the seven/fifteen method, the most significant  bit of   a 
character code is checked to determine whether the  code is a seven    bit 
quantity (one byte) or a fifteen bit quantity (two byte).  When the   most 
significant bit is reset  (i.e. to zero), then  a seven bit  quantity   is 
represented.  All seven bit quantities map to glyph numbers 0 to 127   and 
all fifteen bit quantities  map to glyph numbers  32768 to 65535.     This 
method is useful because  it can support ISO  646 (or ISO  8859-1: $00   - 
$7F) code and shifted  JIS Kanji code in  the same data  stream.  In   the 
sixteen bit mode, all character codes map directly to glyph numbers.   The 
text output functions  are also  able to select  glyphs from  up to   four 
different fonts based on the character code passed to the function.   Each 
font supports a subrange of the possible range  of glyph numbers.    Since 
all character codes map uniquely to glyph numbers, each font, in   effect, 
supports a subrange of character codes.  The glyph  is selected from   the 
font that supports the required subrange.  If two  or more fonts   contain 
glyphs with the  same glyph  number(s), the font  with the  lowest    font 
number will be used.
2.3.2.10  Text Fonts


Text in virtually any size, style, or font is supported by the   software. 
These attributes are controlled by a font module, which is a CD-RTOS  data 
module that contains the bitmap images for each displayable character.

A font module  consists of  six parts, a  module header,  the font    data 
section, the glyph offset table, the glyph data  table, the font   bitmap, 
and the module CRC.  The module header and module CRC are standard   parts 
of a CD-RTOS memory module and are defined in Appendix VII.1.

At the module's entry point (which is declared  in the module header)   is 
the font  data  section.   The  font  data  section  is  usually    placed 
immediately following the module header and contains general   information 
about the font.  The format of the font data section is as follows.

Figure VII.19
_________________________________________________________________
_Offset_Length_   Name     _          Description               _
_________________________________________________________________
_   0  _  2   _fnt_type,   _Font type & flags                   _
_   2  _  2   _fnt_width,  _Maximum Glyph cell width           _
_   4  _  2   _fnt_height, _Glyph cell height1 (ascent+descent) _
_   6  _  2   _fnt_ascent, _Ascent1 of character cell above     _
_      _      _            _  baseline                          _
_   8  _  2   _fnt_descent,_Descent1 of character cell below    _
_      _      _            _  baseline                          _
_  10  _  2   _fnt_pxlsz,  _Pixel size in bits                  _
_  12  _  2   _fnt_frstch, _First character value of font       _
_  14  _  2   _fnt_lastch, _Last character value of font        _
_  16  _  4   _fnt_lnlen,  _Line length of first font bitmap    _
_      _      _            _  in bytes3                         _
_  20  _  4   _fnt_offstbl,_Offset to glyph offset table       _
_  24  _  4   _fnt_databl, _Offset2 to glyph  data table         _ _    28 
_  4   _fnt_map1off,_Offset2 to first bitmap            _
_  32  _  4   _fnt_map2off,_Offset2 to second bitmap3 (RGB only)_
_________________________________________________________________

Font Data Type/Flags Format:
 _________________________________
_P_           _         _  DT   _
_________________________________
           bit  15                             0
               P  = Proportional/mono-spaced flag
                    0 = Monospace
                    1 = Proportional spaced
               DT = Data type
                    0 = Single-bit
                    1 = Double-bit
                    2 = Quad-bit
                    3 = CLUT4
                    4 = CLUT7
                    5 = CLUT8
                  6-8 = Reserved
        9 = RGB555
           10-15 = Reserved
The glyph offset table is usually placed immediately  following the   font 
data section.  This table is required in all  fonts.  It is merely a   one 
dimensional array of sixteen bit integers which represent the   horizontal 
distance in pixels from the left edge of the font bitmap to the left  edge 
of the glyph.  There must be one entry in the glyph offset table for  each 
glyph in the range  specified by the first  glyph number and  last   glyph 
number in the font data section.  If a  particular glyph number in    that 
range is not displayable, then its entry in the glyph offset table  should 
be set to -1.

The glyph data table  is usually placed immediately  following the   glyph 
offset table.   There must be one entry in the glyph data table for   each 
glyph in  the  range  specified  by  the  font  data  section,     whether 
displayable or not.  Each entry in the glyph  data table is formatted   as 
shown in Figure VII.20.

Figure VII.20
________________________________________________________________
_ Offset _ Length _                 Description                _
________________________________________________________________
_    0   _    1   _ Character width in pixels                  _
_    1   _    3   _ Reserved                                   _
________________________________________________________________

The font bitmap is  usually placed immediately following  the glyph   data 
table.  The font bitmap is a rectangular array of pixels of the same  form 
as a drawmap.  Its height is the same  as the character cell height    and 
its width is equal to the sum of all of the widths of the glyphs in    the 
font.  All of the glyphs for the font  are placed in the font bitmap    in 
sequential order from left to right.

When a glyph is drawn, the pixel data  is used in a similar way to     the 
pixel data in a  pattern when used for  graphics drawing    (VII.2.3.2.8). 
Fonts have the same data types as patterns.  If a font has single,  double 
or quad-bit data type, each pixel is expanded to color data via the  color 
registers.  For single-bit  pixels only  entries 0 and  1 of  the    color 
registers are used. Quad-bit pixels can use all 16 entries.

If the font  contains actual  color data then  that data  is   transferred 
directly to the drawmap, so long as the  data types of the font and    the 
drawmap are the same.

  2.3.3 General UCM Service Requests
  
  
  This section specifies the service requests and functions which 
  apply to all UCM devices.
  
  By function,  a list  of error  codes  returned is  given. The  
  system calls (e.g. F$SRqCMem) used  by some of those functions  
  are also indicated:  in this case  all errors  returned by the  
  system calls are also possible (see Appendix VII.1).
  
  
  2.3.3.1 I$Open - Open Path to Specified UCM Device
  
  
  This call is used to get  all necessary information and set up  
  all necessary data structures to be able to access a particular 
  device. If successful, a path number is returned which is used  
  in subsequent I/O  calls to identify  the open  device. If the  
  device to be opened is not  available an error is returned. If  
  two paths are opened to the same device, function calls to the 
  different paths have identical effects  (e.g. a drawmap can be  
  created through one path and then closed through the other).
  
       Input:   d0.b = Access mode
            (a0) = Pointer to pathname of device 
  
       Output:  d0.w = Path number
            (a0) = Pointer to updated pathname of device
  
       Error Output: cc  = Carry bit set to one
            d1.w = Error code
  
     Possible    Errors:   E$BPNum,    E$BPNam,   E$MNF,    E$Share,    
  E$BMode,
             F$SRqMem, I$Attach, I$Detach
  
       Access Mode Format:
          _____________________________________________
          _ Bit Number  _ Description (if set to one)_
           _____________________________________________ 
          _ 0       _ Read                      _
           _    1       _ Write                     _
          _ 2-5     _ Reserved                  _
           _    6       _ Non-shareable use         _
           _    7       _ Reserved                  _
           _____________________________________________
                                       
  
  2.3.3.2 I$Close - Close a UCM Device
  
  
  Close terminates the use  of the I/O path.  It causes the path  
  number and all memory used to support the path to be returned to 
  the system. If there is an asynchronous I/O function executing  
  on this path the Close function  waits until completion of the  
  asynchronous routine before returning to the application.
  
       Input:   d0.w = Path number
  
       Output:  None
  
       Error Output: cc  = Carry bit set to one
            d1.w = Error code
  
     Possible   Errors:    F$SRtMem,   E$BPNum,   F$IRQ,    F$Event,   
                          F$UnLink, I$Detach, E$UnID
  
  
  
  2.3.3.3 SS_SLink - Link Subroutine Module
  
  
  This function is used as a generalized method of expanding the  
  command set of  UCM. It  utilizes a  special subroutine module  
  which is linked into UCM. When UCM receives an unknown Getstat  
  or Setstat  service  request, it  will  pass the  call  to the  
  subroutine module. If it is  unknown to the subroutine module,  
  the subroutine module should then pass the call to the driver.
  
  There are  four significant  entry  points into  this external  
  Subroutine Module: Init, Setstat, Getstat and Close.
  
  Init will be called when the module is first linked to by UCM.  
  It is provided to allow the module to initialize data structures 
  and variables. Likewise, the Close  entry point will be called  
  when the path  to UCM is  closed. At this  time the subroutine  
  module should free any  memory which was  allocated during its  
  execution.
  
  The Setstat and Getstat entry points are provided to actually do 
  the main work of the subroutine module.
  
  The mechanism for this dispatching should be similar to the one 
  currently used  by  CD_RTOS  File  Managers  and  drivers. The  
  execution entry point of the module points to the primary jump  
  table. This jump table contains the relative addresses for the  
  Init, SetStat,  GetStat and  Close  routines (in  that order).  
  These offsets are two byte entries.
  
  When UCM wishes to  pass control to one  of these functions it  
  will retrieve the appropriate address  from the jump table and  
  jump through to that code.
  
  Space is reserved  in the UCM  device static  storage for this  
  subroutine module to use. Eighty bytes are available beginning  
  at the offset $3E.
  
  CAUTION: Because this space is global to all paths open to UCM, 
  it is impossible  for two  different subroutine  modules to be  
  linked at the same time. This applies even when they are linked 
  by different processes. However, more  than one process may be  
  linked to the same subroutine module.
  
  For more information, see Appendix VII.1
  
  
       Input:   d0.w = Path number
            d1.w = SS_SLink setstat code
            (a0) = Pointer to name of file manager
                     subroutine module
  
       Output:  None
  
       Error Output: cc  = Carry bit set to one
            d1.w = Error Code
  
       Possible Errors: E$KwnMod, F$Link, E$BPNum2.3.4 Video and 
       Graphics Functions
  
  All of  the functions  defined  in this  section  control what  
  appears  on   the  display.   Throughout  this   section  many   
  parameters, such  as the  end  point of  a line,  have  both a  
  horizontal and vertical component. Whenever a notation such as  
  S:D     (Source:Destination     for      identifiers),     H:V      
  (Horizontal:Vertical for coordinates) or W:H (Width:Height for  
  sizes) is used, the source, horizontal or width component will  
  be placed in  the high-order  word of  the register  or memory  
  location and the destination, vertical  or height component in  
  the low-order word.
  
  2.3.4.1 Drawmap Control Functions
  
  Virtually any number of drawmaps (up to the limit of memory) may 
  be allocated. Functions are also  provided to copy or exchange  
  data between drawmaps.
  
  The following functions are not allowed with RunLength drawmaps. 
  DM_Copy, DM_Exch, DM_TCpy, DM_TExc, DM_Read, DM_Write, DM_IrWr, 
  DM_RdPix, DM_WrPix and DM_Cncl.
  DM_Creat - Create Drawmap
       DM_Creat creates a drawmap comprised of one or two blocks 
       of memory  used  to  store  and/or  display  images. The  
       allowable data types are CLUT 4, CLUT 7, CLUT 8, RGB 555, 
       DYUV, DYUV + QHY (extended case),  RL3 and RL7. The size  
       of  the  memory   block(s)  allocated   depends  on  the   
       two-dimensional size specified in d5.l and on the length  
       specified in d6.l. The video driver calculates the amount 
       of memory required by the specified size and selects the  
       greater of the calculated amount and the specified length.
  
       Note: When  calculating  the size  of  the  drawmap, the  
       driver first normalizes the width and height parameters as 
       per as resolution specified, then compares that with the  
       length parameter. Width and height may not be 0 (or 1 in 
       normal resolution).
  
       In the case of  RL3 and RL7 data  types, only the length  
       parameter is used in calculating  the size of the memory  
       blocks. However, the  height parameter is  still used to  
       calculate the size of the associated line pointer table,  
       and must  be  greater  than  0  (or  1  in normal/double  
       resolution). In this case only, width is ignored and may  
       be 0.
  
       In the  case of  RGB 555,  which  creates two  blocks of  
       memory, the  driver  calculates  the  amount  of  memory  
       required for each block  and creates two  blocks of that  
       size.
  
       In the case of DYUV +  QHY, (extended case) the size and  
       length are used to create a standard DYUV drawmap block in 
       one plane. The  length parameter  in d7.l  specifies the  
       length of a QHY drawmap block in the other plane.
  
       When video is transferred from a Real Time Record directly 
       to the drawmap, the data is  transferred one sector at a  
       time. When this occurs, the size  of the drawmap must be  
       an integral number of 2324 byte sectors. When the "lines  
       separated" flag is used, if the total size of the drawmap 
       is n, the beginning of the second line starts at n/2.
  
       The plane number specifies  the memory bank  (plane 0 or  
       plane 1) that the memory block  is allocated from. It is  
       possible to allocate a drawmap in a plane that will not be 
       able to display it (i.e. CLUT 8 in plane B). In the case  
       of RGB 555, the plane paramater is ignored and the driver 
       creates one memory block in each plane. For a list of the 
       permissible display combinations see section V.4.4.8.
  
       The DM_Creat function returns the drawmap identifier and  
       the address of  the drawmap  descriptor. This  should be  
       used for information purposes only.
  Drawmap Descriptor Format:
  
  Offset Length Name    Description
  
   0  2   MD_DNum   Drawmap identifier
    2 2  MD_DType Data type and flags
   4  4  MD_Mapl Pointer to primary drawmap memory
   8  4  MD_LnATbl1 Pointer to primary line pointer table
   12  4  MD_MapSz1 Size of primary drawmap in bytes
   16  2  MD_Plane Plane number
   18  2  MD_PxlSz Size of a pixel in bits
   20  2  MD_PMapW Physical width of drawmap in pixels
   22  2  MD_PMapH Physical height of drawmap in pixels
    24   2  MD_XOrg   Origin   offset  in   X   direction  in   UCM   
                     coordinates
    26   2  MD_YOrg   Origin   offset  in   Y   direction  in   UCM   
                     coordinates
    28  2  MD_CMinX  Minimum  X  of  default  clipping  region   in  
                     pixels
    30  2  MD_CMaxX  Maximum  X  of  default  clipping  region   in  
                     pixels
    32  2  MD_CMinY  Minimum  Y  of  default  clipping  region   in  
                     pixels
    34  2  MD_CMaxY  Maximum  Y  of  default  clipping  region   in  
                     pixels
   36  2  MD_PenW Pen width in pixels minus one
   38  2  MD_PenH Pen height in pixels minus one
   40  4  MD_PSStr Pen style bit string
   44  2  MD_PSCnt Pen style repeat count
   46  2  MD_TCol1 Transparency color for primary drawmap
   48  4  MD_Patt Pointer to current pattern
   52  2  MD_PMode Pattern mode
    54  2  MD_POffX   X  offset  to   pattern  bit  point  in   UCM  
                     coordinates
    56  2  MD_POffY   Y  offset  to   pattern  bit  point  in   UCM  
                     coordinates
   58    32  MD_CRTbl Color register table
   90  2  MD_MpMthd Mapping method for graphics text
   92  2  MD_AFBeg0  Beginning glyph  value  for  1st active  font  
                       for graphics text
   94  2  MD_AFEnd0 Ending glyph value for 1st active font
            for graphics text
   96  4 MD_AFData0  Pointer  to beginning  of  first active  font  
                       data for graphics text
  100 2  MD_AFBeg1 Beginning  glyph  value for  2nd  active font  
                       for graphics text
  102  2  MD_AFEnd1 Ending glyph value for 2nd active font
            for graphics text
  continued
  Drawmap Descriptor Format: continued
  
  Offset Length Name    Description
  
  104 4  MD_AFData1  Pointer  to beginning  of  2nd  active font  
                       data for graphics text
  108 2  MD_AFBeg2 Beginning  glyph  value for  3rd  active font  
                        for graphics text
  110 2 MD_AFEnd2  Ending glyph  value for  3rd active  font for  
                        graphics text
  112 4  MD_AFData2  Pointer  to beginning  of  3rd  active font  
                       data for graphics text
  116 2  MD_AFBeg3 Beginning  glyph  value for  4th  active font  
                        for graphics text
  118 2 MD_AFEnd3  Ending glyph  value for  4th active  font for  
                        graphics text
  120 4  MD_AFData3  Pointer  to beginning  of  4th  active font  
                       data for graphics text
  124  2  MD_RgnId  Region identifier of user clipping region
  126  4  MD_Map2   Pointer to secondary drawmap memory
  130  4  MD_LnATbl2 Pointer to secondary line pointer table
  134  4  MD_MapSz2  Size of secondary drawmap in bytes
  138  2  MD_TCol2  Transparency color for secondary drawmap
  140   116 Reserved 
  Data Type/Flags Format:
  
          _________________________________
          _F_       _       _RS _ DT  _
          _________________________________
       bit 15                           0
                
       F = Line pointer table format
            0 = Even/odd lines interleaved
            1 = Even/odd lines separated*
   
         RS = Resolution
              0 = Normal resolution
              1 = Double resolution
           2 = Reserved
              3 = High resolution (extended case)
  
         DT = Data type
            0-2 = Reserved 
              3 = CLUT4    8 = DYUV
              4 = CLUT7    9 = RGB555
          5 = CLUT8  10 = Reserved
              6 = RL3 11 = DYUV+QHY
              7 = RL7         12-15 = Reserved
  
  * Even/odd lines  separated is intended  for error concealment  
      and high resolution display. Separation  of the two fields  
      facilitates interlaced display  of high  resolution images  
      without inhibiting the use of line-sequential scanning.
  
   For graphics drawing UCM uses the line pointer table to locate 
   lines.
   Resolution/Data Type Combination Restrictions:
  
              _____________________________________
              _ _ Normal _ Double _ High _
              _____________________________________
              _ CLUT4   _   -  _   B  _  B _
              _ CLUT7   _   B  _   -  _  E _
              _ CLUT8   _   B  _   -  _  E _
              _ RL3     _   -  _   B  _  B _
              _ RL7     _   B  _   -  _  E _
              _ DYUV    _   B  _   -  _  E _
              _ DYUV+QHY _   -  _   -  _  E _
              _ RGB555  _   B  _   -  _  - _
              _____________________________________
                         - = Not specified
                         B = Base Case
                         E = Extended Case
  DM_Org - Set Drawing Origin
  
   DM_Org changes the position of the drawmap in the coordinate  
   space. The default origin when the  drawmap is created is at  
   the upper left  hand corner  of the  drawmap. The  origin is  
   specified as  an  offset from  the  top left  corner  of the  
   drawmap.
  
   Input:    d0.w = Path number
           d1.w = SS_DM setstat code
           d2.w = DM_Org function code
           d3.w = Drawmap identifier
          d4.l = Origin offset (H:V) in UCM coordinates
  
   Output:   None
  
   Error Output: cc  = Carry bit set to one
           d1.w = Error code
  
   Possible Error:  E$UnID,  E$BPNumDM_Copy -  Copy  Drawmap to  
   Drawmap
  
   DM_Copy copies a rectangular shaped area from one drawmap to  
   another. The two drawmaps must have  the same data type. The  
   source drawmap identifier is placed in the high-order word of 
   register d3 and the destination drawmap identifier is placed  
   in the low-order word. If the specified size would result in  
   data being copied from outside the  source drawmap or to the  
   outside of  the  destination drawmap,  the  size  is reduced  
   accordingly. 
   
   Input:     d0.w = Path number
            d1.w = SS_DM setstat code
            d2.w = DM_Copy function code
            d3.l = Drawmap identifiers (S:D)
           d4.l = Destination (H:V) coordinate
            d5.l = Source (H:V) coordinate
            d6.l = Size (W:H) in UCM coordinates
  
   Output:    None
  
   Error Output: cc  = Carry bit set to one
            d1.w = Error code
  
   Possible Errors: E$BadMod, E$UnID, E$BPNum, E$IllPrmDM_Exch - 
   Exchange Data Between Drawmaps
  
   DM_Exch exchanges  the  data in  a  rectangular  shaped area  
   between two drawmaps.  The two  drawmaps must  have the same  
   data type. The  source drawmap  identifier is  placed in the  
   high-order word of  register d3 and  the destination drawmap  
   identifier is placed in the low-order word. If the size would 
   result in data being exchanged between the outsides of the two 
   drawmaps, this size is reduced accordingly.
  
   Input:    d0.w = Path number
            d1.w = SS_DM setstat code
            d2.w = DM_Exch function code
            d3.l = Drawmap identifiers (S:D)
            d4.l = Destination (H:V) coordinate
           d5.l = Source (H:V) coordinate
           d6.l = Size (W:H) in UCM coordinates
  
   Output:    None
  
   Error Output: cc  = Carry bit set to one
            d1.w = Error code
  
   Possible Errors: E$BadMod, E$UnID, E$BPNum, E$IllPrmDM_TCpy - 
   Copy with Transparency Check
  
   DM_TCpy, like DM_Copy, copies the data in a rectangular shaped 
   area from one drawmap to another. As it copies it checks each 
   source  pixel  value   for  equivalence   to  the  specified   
   transparent color. If  the pixel  value and  the transparent  
   color are equal, then the pixel  is not copied. This call is  
   usable only on CLUT and  RGB555 drawmaps. The source drawmap  
   identifier is placed in the high-order word of register d3 and 
   the destination drawmap identifier is placed in the low-order 
   word. If the specified size would result in data being copied 
   from outside the  source drawmap  or to  the outside  of the  
   destination drawmap,  the  size is  reduced  accordingly. It  
   should be noted  that the  transparent color  is interpreted  
   according to the data type of the drawmap and is identical to 
   the pixel data formats (see V.6.5).
  
   Input:    d0.w = Path number
            d1.w = SS_DM setstat code
            d2.w = DM_TCpy function code
            d3.l = Drawmap identifiers (S:D)
           d4.l = Destination (H:V) coordinate
            d5.l = Source (H:V) coordinate
            d6.l = Size (W:H) in UCM coordinates
            d7.w = Transparent color
  
   Output:    None
  
   Error Output: cc  = Carry bit set to one
            d1.w = Error code
  
   Possible Errors: E$BadMod, E$UnID, E$BPNum, E$IllPrm
  DM_TExc - Exchange with Transparency
  
   DM_TExc, like DM_Exch,  exchanges the data  in a rectangular  
   shaped area between two drawmaps. As it exchanges pixels, it  
   checks each  source  pixel  value  for  equivalence  to  the  
   specified transparent  color.  If the  pixel  value  and the  
   transparent color are  equal, the pixels  are not exchanged.  
   This function is usable only on CLUT and RGB555 drawmaps. The 
   source drawmap identifier is placed in the high-order word of 
   register d3 and the destination drawmap identifier is placed  
   in the low-order word. If the specified size would result in  
   data being exchanged  between the outsides  of the drawmaps,  
   then the size is reduced accordingly.
  
   Input:    d0.w = Path number
            d1.w = SS_DM setstat code
           d2.w = DM_TExc function code
            d3.l = Drawmap identifiers (S:D)
           d4.l = Destination (H:V) coordinate
            d5.l = Source (H:V) coordinate
            d6.l = Size (W:H) in UCM coordinates
            d7.w = Transparent color
  
   Output:    None
  
   Error Output: cc  = Carry bit set to one
           d1.w = Error code
  
   Possible Errors: E$BadMod, E$UnID, E$BPNum, E$IllPrm
  DM_Write - Write Drawmap
  
   DM_Write writes a rectangular array  of pixels, specified by  
   the application  and residing  in its  space, to  a drawmap.  
   Writing starts at the specified  coordinate. The UCM assumes  
   that the rows in the array, which correspond each to a line in 
   a drawmap, are an  integral number of  long words in length.  
   The number  of  pixels  on  each  line  are  transferred  as  
   specified. However, when the UCM has finished writing a line  
   of pixels, it skips to the next long word boundary and starts 
   reading pixels there for the next line. The UCM also assumes  
   that all of the bits for a pixel reside in a contiguous string 
   of bits in the  input array. If  the application specifies a  
   coordinate or  size  which will  cause  writing  outside the  
   drawmap an error (E$IllPrm) will be returned
  
   Input:    d0.w = Path number
            d1.w = SS_DM setstat code
            d2.w = DM_Write function code
            d3.w = Drawmap identifier
           d4.l = Start (H:V) coordinate
            d5.l = Size (W:H) of array in UCM coordinates
          (a0) = Pointer to input pixel array
  
   Output:    None
  
   Error Output: cc  = Carry bit set to one
           d1.w = Error code
   
   Possible Errors: E$BadMod, E$IllPrm, E$UnID, E$BPNum
  
  DM_IrWr - Irregular Write
  
   DM_IrWr is used to write a series of lines of varying length 
   to differing  horizontal positions  in the  drawmap. Writing  
   begins at the  specified vertical position.  The UCM assumes  
   that each line in the input  buffer is an integral number of  
   long words in length. The specified number of pixels on each  
   line are transferred; however, when UCM has finished writing a 
   line of pixels, it skips to  the next long word boundary and  
   starts reading pixels there for the  next line. The UCM also  
   assumes that  all  of  the  bits for  a  pixel  reside  in a  
   contiguous string of bits in the input array.
  
   If the application specifies a coordinate or size which will  
   cause writing  outside  the  drawmap  the  size  is  reduced  
   accordingly.
  
   Input:    d0.w = Path number
           d1.w = SS_DM setstat code
          d2.w = DM_IrWr function code
          d3.w = Drawmap identifier
          d4.w = Starting vertical coordinate
          d5.w = Number of lines in UCM coordinates
          (a0) = Pointer to data to write
           (a3) = Pointer to transfer specifier array4
  
   Output:    None
  
   Error Output: cc  = Carry bit set to one
           d1.w = Error code
  
   Possible Errors: E$BadMod, E$UnID, E$BPNum, E$IllPrm
  
   Transfer Specifier Format:
  
          _____________________________________________
          _ HC         _        PC         _
          _____________________________________________
       bit 31                16 15                 0 
  
                 HC = Horizontal coordinate
     PC    =    Number    of    pixels    to    transfer   in    UCM    
                       coordinates
  DM_Read - Read Drawmap
  
   DM_Read reads a rectangular area of pixels from a drawmap to a 
   two dimensional array buffer in the application program's data 
   space. Reading starts at the specified coordinate. As in the  
   DM_Write function,  the UCM  assumes that  each line  in the  
   output array is an integral number  of long words in length.  
   Also DM_Read  packs  all  of  the bits  of  a  pixel  into a  
   contiguous string  of  bits  in  the  output  array.  If the  
   application specifies a coordinate or  size which will cause  
   reading outside  the  drawmap an  error  (E$IllPrm)  will be  
   returned.
  
   Input:    d0.w = Path number
            d1.w = SS_DM setstat code
            d2.w = DM_Read function code
           d3.w = Drawmap identifier
           d4.l = Start (H:V) coordinate
           d5.l = Size (W:H) of area in UCM coordinates
            (a0) = Pointer to output area
  
   Output:    None
  
   Error Output: cc  = Carry bit set to one
           d1.w = Error code
   
   Possible Errors: E$BadMod, E$IllPrm, E$UnID, E$BPNum
  DM_WrPix - Write Pixel
  
   DM_WrPix writes  the  specified  data to  the  pixel  at the  
   specified  coordinate.  If   the  application   specifies  a   
   coordinate which would cause writing outside the drawmap, the 
   data is not written and no error is returned. The pixel data 
   written is in the lowest part of d5.w (e.g. for CLUT 4).
  
   Input:    d0.w = Path number
            d1.w = SS_DM setstat code
            d2.w = DM_WrPix function code
            d3.w = Drawmap identifier
           d4.l = Pixel (H:V) coordinate
           d5.w = Write data
  
   Output:    None
   
   Error Output: cc  = Carry bit set to one
           d1.w = Error code
  
   Possible Errors: E$BadMod, E$UnID, E$BPNum, 
  DM_RdPix - Read Pixel
  
   DM_RdPix reads the pixel data at the specified coordinate. If 
   the application  specifies  a  coordinate  which  will cause  
   reading outside  the drawmap,  an  error (E$IllPrm)  will be  
   returned.
  
   The pixel data read is put in the lower part of d0.w (e.g. for 
   CLUT 4).
  
   Input:    d0.w = Path number
            d1.w = SS_DM setstat code
            d2.w = DM_RdPix function code
           d3.w = Drawmap identifier
            d4.l = Pixel (H:V) coordinate
  
   Output:    d0.w = Pixel data
  
   Error Output: cc  = Carry bit set to one
            d1.w = Error code
  
   Possible Errors: E$BadMod, E$IllPrm, E$UnID, E$BPNum
  
  DM_Cncl - Conceal Error in Drawmap
  
   DM_Cncl will perform the error concealment function provided  
   by the video driver. This will usually consist of replacement 
   of an erroneous line of pixels by the previous line (this is 
   actually done by copying the pointer from the previous entry  
   in the line pointer table). If the first line is in error it  
   is replaced by the first  non-erroneous line in the drawmap.  
   The error data input to the DM_Cncl function is in the form of 
   a bit string. There is  one bit in this  bit string for each  
   line in the drawmap. If a particular  bit is set to one then  
   the line corresponding to that bit is in error.
  
   Input:    d0.w = Path number
            d1.w = SS_DM setstat code
            d2.w = DM_Cncl function code
            d3.w = Drawmap identifier
            (a0) = Pointer to error data
  
   Output:    None
  
   Error Output: cc  = Carry bit set to one
            d1.w = Error code
   
   Possible Errors: E$BadMod, E$IllPrm, E$UnID, E$BPNum
  DM_Close - Close Drawmap
  
   DM_Close de-allocates the memory associated with a drawmap.
  
   Input:    d0.w = Path number
            d1.w = SS_DM setstat code
            d2.w = DM_Close function code
           d3.w = Drawmap identifier
   
   Output:    None
  
   Error Output: cc  = Carry bit set to one
            d1.w = Error code
  
   Possible Errors: E$UnID, F$SRtMem, E$BPNum
  
  
  DM_DMDup - Create Duplicate Drawmap Descriptor
  
   DM_DMDuP creates  a  drawmap  descriptor  for  the specified  
   drawmap and  copies  the contents  of  the  original drawmap  
   descriptor into the new one. It does not create a new drawmap 
   or line pointer table.
  
   Input:    d0.w = Path number
           d1.w = SS_DM setstat code
           d2.w = DM_DMDuP function code
           d3.w = Drawmap identifier
  
   Output:    d0.w = New drawmap identifier
           (a0) = Address of new drawmap descriptor
  
   Error Output: cc  = Carry bit set to one
           d1.w = Error code
  
   Possible  Errors:  E$IdFull,  E$UnID,  F$SRqCMem,  F$SRtMem,   
                    E$BPNum
  
  2.3.4.2 Graphics Cursor Functions
  
  
  GC_Pos - Position Graphics Cursor
  
   GC_Pos changes the position of the hardware graphics cursor on 
   the display. The hit point coordinate specifies where the hit 
   point of the graphics cursor  will be positioned relative to  
   the cursor origin.
  
   Input:    d0.w = Path number
           d1.w = SS_GC setstat code
           d2.w = GC_Pos function code
           d3.l = Hit point (H:V) coordinate
  
   Output:    None
  
   Error Output: cc = Carry bit set to one
           d1.w = Error code
  
   Possible Errors: E$BPNum
  GC_Show - Show Graphics Cursor
  
   GC_Show causes the hardware graphics cursor to appear on the  
   screen.
  
   Input:    d0.w = Path number
           d1.w = SS_GC setstat code
           d2.w = GC_Show function code
  
   Output:    None
  
   Error Output: cc = Carry bit set to one
           d1.w = Error code
  
   Possible Errors: E$BPNum
  
  
  
  
  GC_Hide - Hide Graphics Cursor
  
   GC_Hide causes the hardware graphics cursor to disappear from 
   the screen.
  
   Input:    d0.w = Path number
           d1.w = SS_GC setstat code
           d2.w = GC_Hide function code
  
   Output:    None
  
   Error Output: cc = Carry bit set to one
           d1.w = Error code
  
   Possible Errors: E$BPNum
  
  
  GC_Ptn - Set Graphics Cursor Pattern
  
   GC_Ptn controls the shape of  the graphics cursor. The shape  
   of the graphics cursor is specified using a bitmap, which can 
   be of any size, limited by  hardware capability. In the Base  
   Case, the  cursor is  16 x  16 pixels.  Those pixels  in the  
   bitmap which are set to one will appear on the display in the 
   cursor color (specified by the GC_Col function). Those pixels 
   that are set to zero will  be transparent. The first word of  
   the cursor pattern represents the first 16 pixels of the top  
   line. Each line of pixels of the cursor is represented by an 
   integral number of words in the cursor pattern input.
  
   Input:    d0.w = Path number
           d1.w = SS_GC setstat code
           d2.w = GC_Ptn function code
    d3.l  =  Hit  point  (H:V)  position  (relative  to  top   left  
                   of cursor pattern)
          d4.l = Pattern (W:H) size in UCM coordinates
           d5.w = Cursor resolution
              0 = Normal
              1 = Double
              2 = High (extended case)
           (a0) = Pointer to graphics cursor pattern
  
   Output:    None
  
   Error Output: cc = Carry bit set to one
           d1.w = Error code
  
   Possible Errors: E$BPNum
  
  
  
  
  GC_Col - Set Graphics Cursor Color
  
   GC_Col sets the color  of the graphics  cursor. The color is  
   specified in terms  of its  Intensity, Red,  Green, and Blue  
   components at eight bits per component. If the resolution is  
   less than eight bits then the most significant bits are used. 
   In the  Base  Case,  the  resolution  is  only  one bit  per  
   component, thus only the most significant bit is used.
   
   Note that to  obtain the Base  Case set of  colors, when the  
   resolution is 8 bits, the intensity must have the values $7F  
   and $FF only and the other components must have the values $00 
   and $FF only (see V.5.12).
  
   However, other values will  not be regarded  as errors, this  
   guarantees compatibility with future possible extensions (more 
   bits per color component).
  
   Input:    d0.w = Path number
           d1.w = SS_GC setstat code
           d2.w = GC_Col function code
           d3.l = Color
  
   Output:   None
  
   Error Output: cc = Carry bit set to one
           d1.w = Error code
  
   Possible Errors: E$BPNum
  
  
   Color Format:
     _________________________________________________________
     _ Intensity _    Red    _   Green   _    Blue   _
     _________________________________________________________
  bit 31        24 23        16 15         8 7           0
  
  
  GC_Org - Set Graphics Cursor Origin
  
   GC_Org sets the origin of the graphics cursor relative to the 
   top left corner of the full screen image.
  
   Input:    d0.w = Path number
           d1.w = SS_GC Setstat code
           d2.w = GC_Org function code
           d3.l = (H:V) origin (UCM) coordinates
  
   Output:    None
  
   Error Output: cc = Carry bit set to one
           d1.w = Error code
  
   Possible Errors: E$BPNum
  
           GC_Blnk - Set Graphics Cursor Blink Rate and Type
  
   The cursor is in its programmed color during the 'on' period, 
   and the complementary color or  transparent during the 'off'  
   period. For 60Hz  displays and  50Hz displays,  the 'on' and  
   'off' periods are multiples of 200ms and 240ms respectively.
  
   GC_Blnk sets the blink rate of the graphics cursor.
  
   Input:    d0.w = Path number
           d1.w = SS_GC setstat code
           d2.w = GC_Blnk function code
           d3.w = Blink constants
  
   Output:    None
  
   Error Output: cc = Carry bit set to one
           d1.w = Error code
  
   Possible Errors: E$BPNum
  
  
  
   Blink Constants Format:
                                     
                 __________________________________
                 _B_     _     ___ BON ___ BOFF_
                 __________________________________
             bit 15                              0
  
              B   = Normal/Complement Blink
                         0 = Normal
                       1 = Complement
  
                 BON = Blink on period
                      Period = 12 * BON fields * frame time6
             BON   = 0 is not allowed
  
          BOFF = Blink off period
              Period = 12 * BOFF fields * frame time
              If BOFF = 0, the cursor is on indefinitely
                     
  
          
  

2.3.4.3 Regions


Regions divide  a drawmap  into two  disjoint sets  of pixels.  
Their primary use is to limit the area of drawing in a drawmap. 
Regions can also  be drawn.  Regions may  be of  any arbitrary  
shape or size.  Regions are created  from the  basic shapes of  
rectangle,  polygon,  circle,  circular  wedge,  ellipse,  and   
elliptical wedge. More  complex shapes are  created from these  
basic shapes  using  intersection,  union,  exclusive-or,  and  
difference operations. (see VII.2.3.2.6 for more information).


RG_Creat - Create Region

  RG_Creat creates a region using one of the basic shapes.

  Input: d0.w = Path number
      d1.w = SS_RG setstat code
        d2.w = RG_Creat function code
        d3.w = Region type (rectangle, polygon, etc.)
      d4.l = Region type dependent
        d5.l = Region type dependent
        d6.l = Region type dependent
        d7.l = Region type dependent
      (a0) = Region type dependent


  Region Type Codes:
      -1 = Null region: cannot be 
          used in RG_Creat
       0 = Rectangle            
                                6 = Elliptical wedge
        1 = Elliptical Cornered 
                                7 = Predefined
            Rectangle 8 = Border Fill
       2 = Polygon      
                                          
                                 (see DR_BFil)
       3 = Circle            
                             9 = Flood Fill
       4 = Circular wedge           
                                    (see DR_FFil)
       5 = Ellipse           10 = Complex result of a
              mix function: cannot
              be used in RG_Creat

  Parameters for Rectangular Region:
        d4.l = Initial corner (H:V) coordinate
       d5.l = Opposite corner (H:V) coordinate

  Parameters for Elliptical Cornered Rectangle:
       d4.l = Initial corner (H:V) coordinate
       d5.l = Opposite corner (H:V) coordinate
       d6.l = Radii (H:V) of corner curvature
  Parameters for Polygon Region:
        d4.w = Number of vertices in input array
      (a0) = Pointer to input array

  Parameters for Circular Region:
        d4.l = Center point (H:V) coordinate
      d5.w = Radius

 Parameters for Circular Wedge Region:
        d4.l = Start angle (H:V) coordinate
      d5.l = End angle (H:V) coordinate
        d6.l = Center point (H:V) coordinate
       d7.w = Radius

  Parameters for Elliptical Region:
        d4.l = Center point (H:V) coordinate
        d5.l = Radii (H:V)

  Parameters for Elliptical Wedge Region:
        d4.l = Start angle (H:V) coordinate
      d5.l = End angle (H:V) coordinate
        d6.l = Center point (H:V) coordinate
      d7.l = Radii (H:V)

  Parameters for Predefined Region:
       (a0) = Address of Region Data Structure
       
  Parameters for Border Fill Region:
       d3.l = Drawmap Identifier : Region Type
       d4.l = Interior (H:V) Coordinate
       d5.w = Boundary Color

  Parameters for Flood Fill Region:
       d3.l = Drawmap Identifier : Region Type
       d4.l = Interior (H:V) Coordinate


 Output: d0.w = Region identifier
  (a0) = Address of region data structure
       
Error Output: cc  = Carry bit set to one
 d1.w = Error code

Possible Errors:  E$BadMod,  E$StkOvf,  E$IllPrm,  E$IdFull,  
                   E$RgFull,  F$SRqMem,   F$SRtMem,  E$UnID,   
                   E$BPNum

RG_Isect - Region Intersection

RG_Isect creates a new region which contains the set of points 
that are common  to both  of the  input regions. If  the two  
input regions have no common points then the new region will  
be empty.

Input: d0.w = Path number
   d1.w = SS_RG setstat code
   d2.w = RG_Isect function code
   d3.w = First region identifier
 d4.w = Second region identifier

Output: d0.w = New region identifier
  (a0) = Address of region data structure

Error Output: cc  = Carry bit set to one
  d1.w = Error code

Possible  Errors:  E$UnID,   F$SRqMem,  E$RgFull,  E$IdFull,   
                   E$BPNum

RG_Union - Region Union

RG_Union creates  a new  region which  combines the  sets of  
points in both of the input regions.

Input: d0.w = Path number
  d1.w = SS_RG setstat code
   d2.w = RG_Union function code
   d3.w = First region identifier
 d4.w = Second region identifier

Output: d0.w = New region identifier
  (a0) = Address of region data structure

Error Output:  cc = Carry bit set to one
  d1.w = Error code

Possible  Errors:  E$UnID,   F$SRqMem,  E$RgFull,  E$IdFull,   
                   E$BPNum
  







RG_Diff - Region Difference

RG_Diff creates a new region which contains the set of points 
in the first region with the set of points which are common to 
both regions  removed. This  implies that  if the  two input  
regions are equivalent then the output region will be empty.


Input: d0.w = Path number
   d1.w = SS_RG setstat code
  d2.w = RG_Diff function code
   d3.w = First region identifier
   d4.w = Second region identifier
Output: d0.w = New region identifier
  (a0) = Address of region data structure
  
Error Output:  cc = Carry bit set to one
  d1.w = Error code

Possible  Errors:  E$UnID,   F$SRqMem,  E$RgFull,  E$IdFull,   
                   E$BPNum

RG_XOR - Region Exclusive Or

RG_XOR creates a new region which contains the set of points  
in the two source regions that are not common to both of the  
input regions.

Input:  d0.w = Path number
         d1.w = SS_RG setstat code
         d2.w = RG_XOR function code
         d3.w = First region identifier
       d4.w = Second region identifer

Output:   d0.w = New region identifer
        (a0) = Address of region data structure

Error Output: cc  = Carry bit set to one
         d1.w = Error code

Possible Errors:  E$UnID, F$SRqMem, E$RgFull, E$IdFull
         E$BPNumRG_Move - Move Region

RG_Move changes the position of the upper-left corner of the  
region's boundary rectangle to the specified coordinate. The  
boundary rectangle is a  rectangle which completely encloses  
the region.

Input:  d0.w = Path number
         d1.w = SS_RG setstat code
         d2.w = RG_Move function code
         d3.w = Region identifier
       d4.l = New (H:V) coordinate

Output:   None


Error Output: cc  = Carry bit set to one
         d1.w = Error code

Possible Errors: E$UnID, E$BPNum

RG_Del - Delete Region

RG_Del releases the memory space associated with a region.

Input:  d0.w = Path number
         d1.w = SS_RG setstat code
       d2.w = RG_Del function code
         d3.w = Region identifier

Output: None

Error Output: cc  = Carry bit set to one
       d1.w = Error code

Possible Errors: E$UnID, F$SRtMem, E$BPNum













2.3.4.4 Drawing Parameter Functions

This set of functions change variables such as pattern and color 
which are used by the graphics drawing functions. All graphics  
display devices are  required to support  these functions. All  
parameters are set for each drawmap individually.

DP_Ptn - Set Drawing Pattern

DP_Ptn sets the drawing pattern which is used for most drawing 
operations. The pattern may contain actual pixel data or from 
one to four  bits per pixel.  In the latter  mode, the pixel  
value is used as an index into a set of color registers which 
contain the actual data which will be written to the drawmap. 
For more  information,  refer  to  Pattern  Indirect Drawing  
(VII.2.3.2.8).

Input:  d0.w = Path number
         d1.w = SS_DP setstat code
         d2.w = DP_Ptn function code
         d3.w = Drawmap identifier
       d4.w = Data type
         (a0) = Pointer to pattern

Output:   None

Error Output: cc  = Carry bit set to one
         d1.w = Error code

Possible  Errors:  E$BadMod,  E$UnID,  F$SRqCMem,  F$SRtMem,   
                   E$BPNum

Data type Codes:
         0 = Single-bit    4 = CLUT7
         1 = Double-bit    5 = CLUT8
       2 = Quad-bit  6-8 = Reserved
         3 = CLUT4     9 = RGB555
            10-15 = Reserved











DP_PAln - Set Pattern Alignment

DP_PAln controls the correspondence between pattern pixels and 
drawmap pixels.  The  correspondence is  made  by specifying  
which pixel in the  pattern corresponds to  the pixel at the  
coordinate (0,0) in the drawmap. The input pattern alignment  
coordinates are taken modulo 16. For more information, refer  
to Pattern Indirect Drawing (VII.2.3.2.8).

Input:  d0.w = Path number
         d1.w = SS_DP setstat code
         d2.w = DP_PAln function code
         d3.w = Drawmap identifier
       d4.l = Pattern alignment (H:V) position

Output:   None

Error Output: cc  = Carry bit set to one
         d1.w = Error code

Possible Errors: E$UnID, E$BPNum

DP_SCMM - Set Character Code Mapping Method

DP_SCMM sets the way that  the DR_Text and DR_JTxt functions  
will interpret the character codes  passed to them (e.g. how  
they will  translate them  to  glyph numbers).  The possible  
methods are the eight bit, seven/fifteen bit, and sixteen bit 
methods (0 = eight bit, 1 = seven/fifteen bit, and 2 = sixteen 
bit; see VII.2.3.2.9).

Input:  d0.1 = Path number
        d1.w = SS_DP setstat code
        d2.w = DP_SCMM function code
        d3.w = Drawmap identifier
        d4.w = Mapping method

Output:   None

Error Output: cc  = Carry bit set to one
        d1.w = Error code

Possible Errors: E$IllPrm, E$UnID, E$BPNum





DP_SCR - Set Color Register

DP_SCR sets color data in one  color register to be used for  
pixel  expansion  (see   VII.2.3.2.8).  There   are  sixteen   
registers available numbered 0 to 15. The format of the color 
data is variable depending on the data type of the associated 
drawmap and  is identical  to  the pixel  data  formats (See  
V.6.5).

Input:  d0.w = Path number
         d1.w = SS_DP setstat code
         d2.w = DP_SCR function code
         d3.w = Drawmap identifier
       d4.w = Color register number
         d5.w = Color data

Output:   None

Error Output: cc  = Carry bit set to one
         d1.w = Error code

Possible Errors: E$IllPrm, E$UnID, E$BadMod, E$BPNum

DP_GFnt - Get Font

DP_GFnt  makes  a  font  module  available  for  use  by  an   
application using the text  functions. It will  first try to  
link to the font module in  memory. If this is unsuccessful,  
it will  attempt  to  load it  from  the  process' execution  
directory on the disc.

Input:  d0.w = Path number
         d1.w = SS_DP setstat code
         d2.w = DP_GFnt function code
         (a0) = Pointer to font module name

Output:   d0.w = Font identifier

Error Output: cc  = Carry bit set to one
         d1.w = Error code

Possible Errors: E$MNF, F$Link,  F$Load, F$UnLink, F$SRqMem,  
                   F$SRtMem, E$BPNum, E$IdFull
The name of the standard CD-I  font module, according to the  
ISO 8859-1 character set, is font8x8.
 
DP_AFnt - Activate Font

DP_AFnt sets the fonts that the DR_Text and DR_JTxt functions 
will select glyphs  from. Since  these functions  may select  
from up  to  four  fonts,  each font  set  by  this  call is  
associated with an active font number in the range of 0 to 3.

Input:  d0.w = Path number
        d1.w = SS_DP setstat code
        d2.w = DP_AFnt function mode
        d3.w = Drawmap identifier
        d4.w = Font identifier
        d5.w = Active font number

Output:   None

Error Output: cc  = Carry bit set to one
        d1.w = Error code

Possible Errors: E$IllPrm, E$UnID, E$BadMod, E$BPNum

DP_DFnt - Deactivate Font

DP_DFnt deactives a font activated  by the DP_AFnt function.  
The font which is associated  with the specified active font  
number is deactivated.

Input:  d0.w = Path number
        d1.w = SS_DP setstat code
        d2.w = DP_DFnt function code
        d3.w = Drawmap identifier
        d4.w = Active font number

Output:   None

Error Output: cc = Carry bit set to one
        d1.w = Error code

Possible Errors: E$UnID, E$BPNum, E$IllPrm
DP_RFnt - Release Font

DP_RFnt releases the memory space occupied by a font module.

Input:  d0.w = Path number
         d1.w = SS_DP setstat code
         d2.w = DP_RFnt function code
         d3.w = Font identifier

Output:   None

Error Output: cc  = Carry bit set to one
       d1.w = Error code

Possible Errors: E$UnID, F$UnLink, E$BPNum

DP_Clip - Set Clipping Region

DP_Clip sets  the  clipping region  for  subsequent graphics  
drawing. No drawing will  be allowed outside  of the region.  
Setting the  region  identifier  to  0  causes  the original  
boundary rectangle  of the  drawmap  to be  restored  as the  
clipping region for the drawmap.

Input:  d0.w = Path number
         d1.w = SS_DP setstat code
       d2.w = DP_Clip function code
         d3.w = Drawmap identifier
       d4.w = Region identifier

Output:   None

Error Output: cc  = Carry bit set to one
         d1.w = Error code

Possible Errors: E$UnID, E$IdFull, F$SRqMem, F$SRtMem
           E$BPNumDP_PnSz - Set Pen Size

This function is used to set the height and width of the lines 
that are  drawn.  This  includes  the  'lines'  for unfilled  
rectangles, circles, arcs, etc.

Input:  d0.w = Path number
         d1.w = SS_DP setstat code
       d2.w = DP_PnSz function code
         d3.w = Drawmap identifier
       d4.l = Pen (W:H) size

Output:   None

Error Output: cc  = Carry bit set to one
         d1.w = Error code

Possible Errors: E$IllPrm, E$UnID, E$BPNum

DP_PStyl - Set Pen Style

DP_PStyl is  used to  define  dash styling  for  lines. This  
includes, the "lines" for unfilled rectangles, circles, arcs, 
etc. The dash styling  is represented by  a bit string which  
determines the size of a dash  and a number which represents  
the number of pixels each bit in the bit string represents.

Input:  d0.w = Path number
       d1.w = SS_DP setstat code
         d2.w = DP_PStyl function code
         d3.w = Drawmap identifier
       d4.l = Dash style bit string
         d5.w = Pixel count

Output:   None

Error Output: cc  = Carry bit set to one
         d1.w = Error code

Possible Errors: E$UnID, E$BPNum 
DP_TCol - Set Transparent Color

DP_TCol sets  the  color  value that  will  be  used  in the  
transparency check  by  the graphics  drawing  functions. It  
should be  noted  that  the format  of  the  color  value is  
dependent on the data type of the drawmap and is identical to 
the pixel data formats (see V.6.5).

Input:  d0.w = Path number
        d1.w = SS_DP setstat code
          d2.w = DP_TCol function code
          d3.w = Drawmap identifier
        d4.w = Transparent color

Output:   None

Error Output: cc  = Carry bit set to one
          d1.w = Error code

Possible Errors: E$UnID, E$BadMod, E$BPNum
2.3.4.5 Graphics Drawing Functions

This set of functions execute graphics drawing such as line and 
circle. All of  these functions  have an  operation code  as a  
parameter, which causes  them to  behave in  various ways. The  
operation code determines whether  clipping will be performed,  
how shapes such as circles and polygons will be filled, and how 
pixels will be combined. Most functions in this section specify 
that a drawmap identifier and the operation code are placed in  
one register. The operation  code is placed  in the high-order  
word and the drawmap identifier is placed in the low-order word. 
The operation code  is a sixteen  bit word whose  format is as  
follows (binary values).
                                                                        
__________________________________________________
       _CF_FM_PM_DS_DT_ _ _TM_    CR   _    CWM     _
       __________________________________________________
   bit 15                    8 7                   0

       CF - Clipping Flag
          0 = Clipping off
         1 = Clipping on
     FM - Fill Mode
         0 = Outlined
         1 = Filled 
   PM - Pattern Mode
        0 = Solid
       1 = Patterned
   DS - Dash Styling 
   
        0 = Not dashed
        1 = Dashed
   DT - Dash transparency
        0 = off
        1 = on (transparent)
   TM - Transparency Writing Mode
         0 = No transparency
         1 = Transparency
     CR - Color register number for solid color
     CWM - Combinatorial Writing Modes  
        00000 = Write 0's
        00001 = Source AND Destination
        00010 = Source AND (NOT Destination)
         00011 = Replace
         00100 = (NOT Source) AND Destination
         00101 = Don't Modify
         00110 = Source XOR Destination
         00111 = Source OR Destination
        01000 = NOT (Source OR Destination)
         01001 = NOT (Source XOR Destination)
         01010 = NOT Destination
         01011 = Source OR (NOT Destination)
         01100 = NOT Source
         01101 = (NOT Source) OR Destination
         01110 = NOT (Source AND Destination)
         01111 = Write 1's
         10000 = Source + Destination
         10001 = Source - Destination
         10010 = Destination - Source
        10011 to 11111 are Reserved

Not all drawing functions use all these operation code fields. 
The bits of any unused fields must be set to zero.

Note: When using Combinatorial Writing modes except Replace, it 
     is not  guaranteed that  a  "closed figure"  is actually  
     closed.

DR_Dot - Draw a Dot

DR_Dot draws a dot using the current pen size and pattern at 
the specified coordinate.

Input: d0.w = Path number
         d1.w = SS_DR setstat code
         d2.w = DR_Dot function code
         d3.l = Drawmap identifier and Operation code
       d4.l = Drawing (H:V) coordinate

Output:   None

Error Output: cc  = Carry bit set to one
        d1.w = Error code

Possible Errors: E$UnID, E$BPNum

Operation code fields not used : FM
DR_Line - Draw a Line

DR_Line draws a line from  the specified start coordinate to  
the specified end coordinate. The pixel at the end coordinate 
is not drawn.

Input:  d0.w = Path number
         d1.w = SS_DR setstat code
       d2.w = DR_Line function code
         d3.l = Drawmap identifier and Operation code
       d4.l = Start (H:V) coordinate
         d5.l = End (H:V) coordinate

Output:   None

Error Output: cc  = Carry bit set to one
          d1.w = Error code

Possible Errors: E$UnID, E$BPNum

Operation code fields not used : FM

DR_PLin - Draw a Polyline

DR_PLin draws  a  series  of  lines  starting  at  the first  
coordinate in  the  input  array  and  ending  at  the  last  
coordinate in the input array. The input array is an array of 
16-bit  integers.  Each  pair   of  integers  specifies  the   
horizontal and  vertical  coordinates  of  a  vertex  of the  
polyline. The pixel at the last specified point is not drawn.

Input:  d0.w = Path number
       d1.w = SS_DR setstat code
       d2.w = DR_PLin function code
         d3.l = Drawmap identifier and Operation code
         d4.w = Number of vertices in input array
         (a0) = Input array pointer

Output:   None

Error Output: cc  = Carry bit set to one
          d1.w = Error code

Possible Errors: E$IllPrm, E$UnID, E$BPNum

Operation code fields not used : FM

DR_CArc - Draw a Circular Arc

DR_CArc draws  a circular  arc. The  arc  is specified  by a  
center point, a  radius, and  two angle  points. All  of the  
points on the arc are  equidistant (specified by the radius)  
from the specified center point. The video driver determines  
the starting point of the arc  from a line which passes from  
the center point  through the start  angle point.  It is the  
intersection of this line and a circle of the specified radius 
and the specified center point  that is the calculated start  
point. The end point  is calculated in  exactly the same way  
from the line  that starts  at the  center point  and passes  
through the end angle point. Arcs are always drawn clockwise  
from the start to the end point.

Input:    d0.w = Path number
        d1.w = SS_DR setstat code
          d2.w = DR_CArc function code
          d3.l = Drawmap identifier and Operation code
          d4.l = Start angle (H:V) coordinate
        d5.l = End angle (H:V) coordinate
          d6.l = Center point (H:V) coordinate
         d7.w = Radius in UCM coordinates

Output:    None

Error Output: cc  = Carry bit set to one
          d1.w = Error code

Possible Errors: E$IllPrm, E$UnID, E$BPNum

Operation code fields not used : FM


DR_EArc - Draw an Elliptical Arc

DR_EArc draws an elliptical  arc. The arc  is specified by a  
center point, two  radii, and two  angle points.  All of the  
points on the arc lie on an ellipse with the specified center 
point and specified  radii. The video  driver determines the  
starting point of the arc from  a line which passes from the  
center point  through  the  start  angle  point.  It  is the  
intersection of this  line and  an ellipse  of the specified  
radii and the specified center  point that is the calculated  
start point. The end point is calculated in exactly the same  
way from the line that starts at the center point and passes 
through the end angle point. Arcs are always drawn clockwise  
from the start to the end point.

Input:    d0.w = Path number
        d1.w = SS_DR setstat code
          d2.w = DR_EArc function code
          d3.l = Drawmap identifier and Operation code
          d4.l = Start angle (H:V) coordinate
        d5.l = End angle (H:V) coordinate
        d6.l = Center point (H:V) coordinate
          d7.l = Radii (H:V)

Output:    None

Error Output: cc  = Carry bit set to one
          d1.w = Error code

Possible Errors: E$IllPrm, E$UnID, E$BPNum

Operation code fields not used : FM

DR_Rect - Draw a Rectangle

DR_Rect draws a  rectangle, one  corner of  which is  at the  
initial corner coordinate, the opposite corner at the opposite 
corner coordinate.

Input:    d0.w = Path number
        d1.w = SS_DR setstat code
          d2.w = DR_Rect function code
          d3.l = Drawmap identifier and Operation code
        d4.l = Initial corner (H:V) coordinate
          d5.l = Opposite corner (H:V) coordinate

Output:    None


Error Output: cc  = Carry bit set to one
          d1.w = Error code

Possible Errors: E$UnID, E$BPNum

DR_ERect - Draw an Elliptical Corner Rectangle

DR_ERect draws a rectangle which has its corners replaced by  
ninety degree arcs of an ellipse with the specified radii. The 
rectangle is placed in the same  way as a regular rectangle.  
The rectangle must be minimally twice as wide as the specified 
horizontal radius and twice as high as the vertical radius.

Input:    d0.w = Path number
         d1.w = SS_DR setstat code
         d2.w = DR_ERect function code
         d3.l = Drawmap identifier and Operation code
         d4.1 = Initial corner (H:V) coordinate
         d5.1 = Opposite corner (H:V) coordinate
         d6.1 = Radii (H:V) of corner curvature

Output:    None

Error Output: cc  = Carry bit set to one
         d1.w = Error code

Possible Errors: E$IllPrm, E$UnID, E$BPNum

DR_PGon - Draw a Polygon

DR_PGon draws  a  polygon.  The  lines  of  the  polygon are  
calculated in the same way as the lines in DR_PLin.

Input:    d0.w = Path number
        d1.w = SS_DR setstat code
          d2.w = DR_PGon function code
          d3.l = Drawmap identifier and Operation code
        d4.w = Number of vertices in input array
          (a0) = Pointer to input array

Output:    None

Error Output: cc  = Carry bit set to one
          d1.w = Error code

Possible  Errors:  E$UnID,   F$SRqCMem,  F$SRtMem,  E$BPNum,   
                  E$IllPrm

DR_Circ - Draw a Circle

DR_Circ draws a circle of  the specified radius whose center  
point is at the specified coordinate.

Input:    d0.w = Path number
        d1.w = SS_DR setstat code
          d2.w = DR_Circ function code
          d3.l = Drawmap identifier and Operation code
        d4.l = Center point (H:V) coordinate
          d5.w = Radius in UCM coordinates

Output:    None

Error Output: cc  = Carry bit set to one
          d1.w = Error code

Possible Errors: E$IllPrm, E$UnID, E$BPNum

DR_CWdg - Draw a Circular Wedge

DR_CWdg draws a circular wedge. The arc part of the circular  
wedge is calculated in  the same way as  the circular arc in  
DR_CArc.

Input:    d0.w = Path number
        d1.w = SS_DR setstat code
          d2.w = DR_CWdg function code
          d3.l = Drawmap identifier and Operation code
        d4.l = Start angle (H:V) coordinate
          d5.l = End angle (H:V) coordinate
        d6.l = Center point (H:V) coordinate
         d7.w = Radius in UCM coordinates

Output:    None

Error Output: cc  = Carry bit set to one
          d1.w = Error code

Possible Errors: E$IllPrm, E$UnID, E$BPNum

DR_Elps - Draw an Ellipse

DR_Elps draws  an  ellipse  whose  center  point  is  at the  
specified coordinate. The size  and shape of  the ellipse is  
specified by  the  ellipse's  radii  on  the  horizontal and  
vertical axes.

Input:    d0.w = Path number
        d1.w = SS_DR setstat code
          d2.w = DR_Elps function code
          d3.l = Drawmap identifier and Operation code
        d4.l = Center point (H:V) coordinate
          d5.l = Radii (H:V)

Output:    None

Error Output: cc  = Carry bit set to one
          d1.w = Error code

Possible Errors: E$IllPrm, E$UnID, E$BPNum

DR_EWdg - Draw an Elliptical Wedge

DR_EWdg draws  an  elliptical  wedge. The  arc  part  of the  
elliptical wedge  is  calculated  in  the  same  way  as the  
elliptical arc in DR_EArc.

Input:    d0.w = Path number
        d1.w = SS_DR setstat code
          d2.w = DR_EWdg function code
          d3.l = Drawmap identifier and Operation code
        d4.l = Start angle (H:V) coordinate
          d5.l = End angle (H:V) coordinate
        d6.l = Center point (H:V) coordinate
          d7.l = Radii (H:V)

Output:    None

Error Output: cc  = Carry bit set to one
          d1.w = Error code

Possible Errors: E$IllPrm, ESUnID, E$BPNum
DR_DRgn - Draw a Region

DR_DRgn draws  a region  which was  created with  the region  
functions.

Input:    d0.w = Path number
        d1.w = SS_DR setstat code
          d2.w = DR_DRgn function code
          d3.l = Drawmap identifier and Operation code
        d4.w = Region identifier

Output:    None

Error Output: cc  = Carry bit set to one
          d1.w = Error code

Possible Errors: E$UnID, E$BPNum

DR_BFil - Fill a Bounded Area with a Pattern

DR_BFil will  fill  an  area  which  contains  the specified  
coordinate and  is bounded  by  all pixels  which  match the  
specified color.

Input:    d0.w = Path number
        d1.w = SS_DR setstat code
          d2.w = DR_BFil function code
          d3.l = Drawmap identifier and Operation code
        d4.l = Interior (H:V) coordinate
          d5.w = Boundary color

Output:    None

Error Output: cc  = Carry bit set to one
          d1.w = Error code

Possible Errors:  E$StkOvf,  E$IllPrm,  F$SRqCMem, F$SRtMem,  
                  E$BadMod, E$BPNum, E$UnID

Operation code fields not used : FM, DS


DR_FFil - Flood Fill

DR_FFil changes the pixel at the specified coordinate and all 
pixels of the same color connected directly or indirectly to  
it using the pattern defined for the drawmap.

Input:    d0.w = Path number
        d1.w = SS_DR setstat code
          d2.w = DR_FFil function code
          d3.l = Drawmap identifier and Operation code
        d4.l = Fill start (H:V) coordinate

Output:    None

Error Output: cc  = Carry bit set to one
          d1.w = Error code

Possible Errors:  E$StkOvf,  E$IllPrm,  F$SRqCMem, F$SRtMem,  
                  E$BPNum, E$UnID

Operation code fields not used : FM, DS

DR_Copy - Copy Data from Drawmap to Drawmap

DR_Copy copies a rectangular area of pixels from one drawmap  
to another (or the same) drawmap. 

Input:    d0.w = Path number
        d1.w = SS_DR setstat code
          d2.w = DR_Copy function code
          d3.l = Source/Destination drawmap identifiers
        d4.l = Destination (H:V) coordinate
          d5.l = Source (H:V) coordinate
        d6.l = Source area (W:H) size
          d7.w = Operation code

Output:    None

Error Output: cc  = Carry bit set to one
          d1.w = Error code

Possible Errors: E$BadMOd, ESUnID, E$BPNum

Operation code fields not used : FM, PM, DS, CR





DR_Text - Output Graphics Text

DR_Text generates text using the  activated fonts. If two or  
more activated fonts include characters  with the same glyph  
number, the font with the lowest font number will be used. The 
baseline of the cell of the first character is placed at the 
specified coordinate.  Undrawable  characters  are  ignored.  
DR_Text continues to draw characters until either a NUL ($00) 
is found in the text string or until the number of characters 
specified (in bytes) in  d5.l has been  written or until the  
edge of  the  drawmap  is  reached,  whichever  condition is  
satisfied first.

Input:  d0.w = Path number
       d1.w = SS_DR setstat code
         d2.w = DR_Text function code
         d3.l = Drawmap identifier and Operation code
       d4.l = Placement (H:V) coordinate
        d5.w = Number of character bytes to draw
       (a0) = Text pointer

Output:   None

Error Output: cc  = Carry bit set to one
       d1.w = Error code

Possible Errors: E$IllPrm, E$UnID, E$NoFont, E$BPNum

Operation code fields not used : FM, PM, DS, CR
DR_JTxt - Output Justified Graphics Text

DR_JTxt is  similar  to DR_Text  except  that  an additional  
parameter is used  to specify the  length the text  is to be  
justified to. DR_JTxt  expands the  text by  inserting extra  
space between characters.  If there are  too many characters  
DR_Txt displays only those characters which will fit. Control 
characters are ignored and  the string is  terminated by the  
same conditions as for DR_Text.

Input:  d0.w = Path number
       d1.w = SS_DR setstat code
         d2.w = DR_JTxt function code
         d3.l = Drawmap identifier and Operation code
       d4.l = Placement (H:V) coordinate
        d5.w = Justification length (UCM coordinates)
         d6.w = Number of character bytes to draw 
        (a0) = Text pointer

Output:   None

Error Output: cc  = Carry bit set to one
         d1.w = Error code

Possible Errors: E$IllPrm, E$UnID, E$NoFont, E$BPNum

Operation code fields not used : FM, PM, DS, CR

2.3.4.6 Display Control Functions


This set of functions  create, write instructions  to and read  
field and line control tables. In this section the term "Plane" 
is used instead of "Channel".

Important addressing conventions

Parameters defining lines of instructions (line number, number  
of lines)  are  in  UCM  coordinates  except  where  otherwise  
mentioned. When addressing  Normal/Double resolution  LCTs the  
parameter  is  consequently  divided  by  2  and  rounded  off   
downwards.

DC_CrFCT - Create Field Control Table 

DC_CrFCT allocates a field control  table (FCT) and fills it  
with No-Operation instructions. The FCT contains instructions 
which the display  control hardware will  execute during the  
vertical retrace  period. The  maximum  length of  the Field  
Control  Table,  available  to   the  application,  is  1024   
instructions.

Input:    d0.w = Path number
        d1.w = SS_DC setstat code
          d2.w = DC_CrFCT function code
          d3.w = Plane number (0 or 1)
          d4.w = FCT length in instructions
         d5.b = Resolution (0 = Normal/Double
                   1 = High)

Output:    d0.w = FCT identifier

Error Output: cc  = Carry bit set to one
          d1.w = Error code

Possible Errors:  E$IllPrm,  E$IdFull,  F$SRqMem,  F$SRtMem,  
                  E$BPNum
DC_RdFCT - Read Field Control Table

DC_RdFCT reads the specified number of instructions contained 
in the specified FCT into the applications buffer. 
If d5.w = 0, the driver will return the error code (E$IllPrm) 
and no instructions are read.

Input:    d0.w = Path number
        d1.w = SS_DC setstat code
          d2.w = DC_RdFCT function code
          d3.w = FCT identifier
         d4.w = Starting instruction number
         d5.w = Number of instructions to read
          (a0) = Buffer pointer
Output:    None

Error Output: cc  = Carry bit set to one
          d1.w = Error code

Possible Errors: E$IllPrm, E$UnID, E$BPNum
DC_WrFCT - Write Field Control Table 

DC_WrFCT writes the specified number of instructions from the 
applications buffer into the specified FCT. 

Input:    d0.w = Path number
        d1.w = SS_DC setstat code
          d2.w = DC_WrFCT function code
          d3.w = FCT identifier
         d4.w = Starting instruction number
         d5.w = Number of instructions to write
          (a0) = Buffer pointer

Output:    None

Error Output: cc  = Carry bit set to one
          d1.w = Error code

Possible Errors: E$IllPrm, E$UnID, E$BPNum


DC_RdFI - Read Field Control Table Instruction    

DC_RdFI reads a  single instruction  from the  field control  
table.

Input:    d0.w = Path number
          d1.w = SS_DC setstat code
        d2.w = DC_RdFI function code
          d3.w = FCT identifier
        d4.w = Instruction number

Output:    d0.l = Instruction

Error Output: cc  = Carry bit set to one
          d1.w = Error code

Possible Errors: E$IllPrm, E$UnID, E$BPNum

DC_WrFI - Write Field Control Table Instruction
DC_WrFI writes  a single  instruction  to the  field control  
table.

Input:   d0.w = Path number
        d1.w = SS_DC setstat code
          d2.w = DC_WrFI function code
          d3.w = FCT identifier
        d4.w = Instruction number
        d5.1 = Instruction to write

Output:   None

Error Output: cc  = Carry bit set to one
          d1.w = Error code

Possible Errors: E$IllPrm, E$UnID, E$BPNum

DC_DlFCT - Delete Field Control Table
DC_DlFCT deletes the specified FCT, freeing the memory space  
associated with it.

Input:   d0.w = Path number
        d1.w = SS_DC setstat code
          d2.w = DC_DlFCT function code
          d3.w = FCT identifier

Output:   None

Error Output: cc  = Carry bit set to one
          d1.w = Error code

Possible Errors: E$UnID, F$SRtMem, E$BPNum
DC_CrLCT - Create Line Control Table
DC_CrLCT allocates a line  control table (LCT)  and fills it  
with No-Operation  instructions. The  LCT  contains instruc-  
tions which the display control hardware will execute during  
horizontal retrace periods. The  size of the  created LCT is  
dependent on its resolution.

If the resolution flag indicates  normal resolution, the LCT  
will be created with only half as many lines as indicated. The 
even and odd lines will be interleaved and will be referenced 
starting with line 0. If the flag indicates high resolution,  
the LCT will be created with the given number of lines and the 
even and odd lines will be separated. The even numbered lines 
will be placed before the odd numbered lines.

Input:   d0.w = Path number
        d1.w = SS_DC setstat code
          d2.w = DC_CrLCT function code
        d3.w = Plane number (0 or 1)
        d4.w = Number of lines (in UCM coordinates)
         d5.b = Resolution (0= Normal/Double, 1= High)

Output:   d0.w = LCT identifier

Error Output: cc  = Carry bit set to one
          d1.w = Error code

Possible Errors: E$IdFull, F$SRqMem, F$SRtMem, E$BPNum,
           E$IllPrm

DC_RdLI - Read Line Control Table Instruction

DC_RdLI reads a single instruction from the LCT.

Input:   d0.w = Path number
        d1.w = SS_DC setstat code
          d2.w = DC_RdLI function code
          d3.w = LCT identifier
        d4.w = Line number (in UCM coordinates)
          d5.w = Column number       

Output:   d0.l = Instruction

Error Output: cc  = Carry bit set to one
          d1.w = Error code

Possible Errors: E$IllPrm, E$UnID, E$BPNum
DC_WrLI - Write Line Control Table Instruction

DC_WrLI writes a single instruction to the LCT.

Input:   d0.w = Path number
        d1.w = SS_DC setstat code
          d2.w = DC_WrLI function code
          d3.w = LCT identifier
        d4.w = Line number (in UCM coordinates)
          d5.w = Column number
        d6.1 = Instruction

Output:   None

Error Output: cc  = Carry bit set to one
          d1.w = Error code

Possible Errors: E$IllPrm, E$UnID, E$BPNum

DC_DlLCT - Delete Line Control Table

DC_DlLCT deletes the specified LCT, freeing the memory space  
associated with it.

Input:   d0.w = Path number
        d1.w = SS_DC setstat code
          d2.w = DC_DlLCT function code
          d3.w = LCT identifier
  
Output:   None

Error Output: cc  = Carry bit set to one
          d1.w = Error code

Possible Errors: E$UnID, F$SRtMem, E$BPNum
DC_RdLCT - Read Line Control Table 

DC_RdLCT reads the specified lines and columns of instructions 
from the specified line control table into the application's  
buffer. 

If the LCT was created in normal resolution, the driver will  
in general fill up two lines in the application's buffer for  
each  line  in  the  LCT:  the  instructions  put  into  the   
application's buffer for a line n will come from line (n/2) in 
the physical LCT, where n/2 is always rounded down. 
The application specifies the number of buffer lines to fill  
from data in the physical LCT. 
If the LCT was created for  high resolution, the driver will  
reconstruct a contiguous array of lines for the application's 
buffer.

Input:  d0.w = Path number
       d1.w = SS_DC setstat code
         d2.w = DC_RdLCT function code
         d3.w = LCT identifier
       d4.w = Starting line number (in UCM coordinates)
         d5.w = Starting column number
       d6.w = Number of buffer lines to fill from the LCT
        d7.w = Number of columns to read
         (a0) = Buffer pointer

Output:  d0.w = Number of instructions read

Error Output: cc  = Carry bit set to one
         d1.w = Error code

Possible Errors: E$IllPrm, E$UnID, E$BPNum
DC_PRdLCT - Read Physical Line Control Table

DC_PRdLCT  reads   the  specified   lines  and   columns  of   
instructions from the specified Line  Control Table into the  
application's buffer.

DC_PRdLCT reads the physical LCT  directly without regard to  
resolution or separation of lines. The application references 
an absolute line number (as  opposed to UCM coordinates) and  
specifies the absolute number of lines to read.

Input:  d0.w = Path number
       d1.w = SS_DC setstat code
         d2.w = DC_PRdLCT function code
         d3.w = LCT identifier
       d4.w = Starting line number (in absolute value)
         d5.w = Starting column number
       d6.w = Number of lines to read (in absolute value)
        d7.w = Number of columns to read
         (a0) = Buffer pointer

Output:  d0.w = Number of instructions read

Error Output: cc  = Carry bit set to one
         d1.w = Error code

Possible Errors: E$IllPrm, E$UnID, E$BPNum
DC_PWrLCT - Write Physical Line Control Table

DC_PWrLCT writes a list of instructions from the application's 
buffer to the specified  lines and columns  of the specified  
Line Control Table.

DC_PWrLCT writes to the physical LCT directly without regard  
to  resolution  or  separation  of  lines.  The  application   
references an  absolute  line  number  (as  opposed  to  UCM  
coordinates) and specifies  the absolute number  of lines to  
write.

Input:  d0.w = Path number
       d1.w = SS_DC setstat code
         d2.w = DC_PWrLCT function code
         d3.w = LCT identifier
       d4.w = Starting line number (in absolute value)
         d5.w = Starting column number
       d6.w = Number of lines to write (in absolute value)
        d7.w = Number of columns to write
         (a0) = Buffer pointer

Output:  None

Error Output: cc  = Carry bit set to one
         d1.w = Error code

Possible Errors: E$IllPrm, E$UnID, E$BPNUM
DC_WrLCT - Write Line Control Table

DC_WrLCT writes a list of instructions from the application's 
buffer to the specified  lines and columns  of the specified  
LCT.

If the LCT was created in normal resolution, the driver will  
in general write two lines  from the application's buffer to  
the same line of the LCT: the  instructions in line n of the  
application's buffer will be written  into line (n/2) of the  
physical LCT, where n/2 is always rounded down. The lines are 
written into the physical LCT in increasing order.
The application specifies the number of buffer lines to write 
into the physical LCT. 
If the LCT was created for  high resolution, the driver will  
separate the instructions for the application to assure that  
the proper instructions are placed in the appropriate lines of 
the physical LCT.

Input:  d0.w = Path number
       d1.w = SS_DC setstat code
         d2.w = DC_WrLCT function code
         d3.w = LCT identifier
       d4.w = Starting line number (in UCM coordinates)
         d5.w = Starting column number
 d6.w  = Number  of  lines in  the buffer  to  write into  the  
               physical LCT
        d7.w = Number of columns to write
         (a0) = Buffer pointer

Output:  None

Error Output: cc  = Carry bit set to one
       d1.w = Error code

Possible Errors: E$IllPrm, E$UnID, E$BPNum
DC_NOP - Write No Operation Instructions to LCT

DC_NOP writes  No  Operation instructions  to  the specified  
locations in the LCT.

Input:  d0.w = Path number
        d1.w = SS_DC setstat code
        d2.w = DC_NOP function code
        d3.w = LCT identifier
        d4.w = Starting line number (in UCM coordinates)
        d5.w = Starting column number
        d6.w = Number of lines to write (in UCM coordinates)
        d7.w = Number of columns to write

Output:  None

Error Output: cc  = Carry bit set to one
         d1.w = Error code

Possible Errors: E$IllPrm, E$UnID, E$BPNum

DC_SSig - Send Signal on Video Interrupt

DC_SSig sets up a  signal to be sent  to the calling process  
after a specified  number of video  interrupts. (see V.5.6).  
This is done only once,  after which another DC_SSig request  
must be issued.

Input:   d0.w = Path number
         d1.w = SS_DC setstat code
         d2.w = DC_SSig function code
         d3.w = Signal code
         d4.w = Number of interrupts to ignore
              (d4.w = 0 means next interrupt)

Output:   None

Error Output: cc = Carry bit set to one
         d1.w = Error code

Possible Errors: E$BPNum

         





DC_Relea - Release Signal on Video Interrupt

DC_Relea cancels any previous DC_SSig function which is still 
active.

Input:   d0.w = Path Number
         d1.w = SS_DC setstat code
         d2.w = DC_Relea function code

Output:   None

Error Output: cc = Carry bit set to one
        d1.w = Error code

Possible Errors: E$BPNum

         
DC_SetCmp - Set Display Compatibility Mode

DC_SetCmp permits the display of different image formats which 
are different from  the display format.  The Resolution mode  
must be set to one if  the horizontal dimensions are not the  
same.

The difference between the origin of the full screen image and 
the origin of the full screen display is returned; it can be 
fed directly to PT_Org.

Input:  d0.w = Path number
        d1.w = SS_DC setstat code
        d2.w = DC_SetCmp function code
        d3.w = Resolution mode
            0 = Same resolution
           1 = Different resolution

Output:  d0.l = Offset (H:V) coordinate

Error Output: cc  = Carry bit set to one
        d1.w = Error code

Possible Errors: E$BPNum







         
DC_Intl - Set Display Interlace Mode

DC_Intl sets the display interlace mode.

Input:  d0.w = Path number
        d1.w = SS_DC setstat code
        d2.w = DC_Intl function code
        d3.w = Interlace mode
          0 = No interlace
                          1 = Interlace 

Output:  None

Error Output: cc  = Carry bit set to one
        d1.w = Error code

Possible Errors: E$BPNum, E$IllPrm

DC_FLnk - Link LCT to FCT

DC_FLnk links the specified LCT to the specified FCT.

Input:  d0.w = Path number
       d1.w = SS_DC setstat code
        d2.w = DC_FLnk function code
        d3.w = FCT identifier
        d4.w = LCT identifier
        d5.w = LCT line number (in UCM coordinates)

Output:  None

Error Output: cc  = Carry bit set to one
        d1.w = Error code

Possible Errors: E$IllPrm, E$UnID, E$BPNum
 DC_LLnk - Link LCT to LCT

DC_LLnk links the second specified LCT to the first one. The  
link  causes  the  display   control  hardware  to  retrieve   
instructions from the second LCT. It should be noted that if  
the application  program  is  using  the  maximum  number of  
instructions in the specified line of the first LCT, the link 
will replace the last instruction  contained in that line of  
the LCT.

Input:  d0.w = Path number
       d1.w = SS_DC setstat code
        d2.w = DC_LLnk function code
        d3.w = First LCT identifier
        d4.w = First LCT line number (in UCM coordinates)
        d5.w = Second LCT identifier
        d6.w = Second LCT line number (in UCM coordinates)

Output:  None

Error Output: cc  = Carry bit set to one
        d1.w = Error code

Possible Errors: E$IllPrm, E$UnID, E$BPNum

DC_Exec - Execute Display Control Program

DC_Exec causes the display  control hardware to continuously  
execute the  display  control programs  associated  with the  
specified FCTs in planes A and B. If either FCT identifier is 
zero, the default FCT is executed in the specified plane. This 
will switch the display off in that plane.

Input:  d0.w = Path number
       d1.w = SS_DC setstat code
        d2.w = DC_Exec function code
        d3.w = FCT identifier (Plane A)
        d4.w = FCT identifier (Plane B)
            
Output:  None

Error Output: cc  = Carry bit set to one
        d1.w = Error code

Possible Errors: E$IllPrm, E$UnID, F$RqMem, F$SRtMem, E$BPNum
2.3.4.7 Video Inquiry Functions


This is a general class of functions which are used to determine 
the characteristics of  the graphics  device. Device dependent  
factors such as display resolution, display size, or displayed  
text length  can  be  determined  or  calculated  using  these  
functions.


VIQ_TxtL - Calculate Length of Text

VIQ_TxtL calculates the length of  a character string in UCM  
coordinates if it  were to be  drawn using  DR_Text. It also  
calculates the number of characters  in the passed parameter  
string which will fit in the  specified length. It is useful  
for the text  placement functions  DR_Text and  DR_JTxt. The  
number of  characters  used  is the  minimum  of  the number  
specified in d5.l and the number of characters which precede a 
NUL character.
If there is no active font, E$NoFont will be returned.

Input:  d0.w = Path number
       d1.w = SS_VIQ getstat code
         d2.w = VIQ_TxtL function code
         d3.w = Drawmap identifier
       d4.w = Possible length (UCM coordinates)
         d5.w = Number of characters in text string
       (a0) = Text pointer

Output:  d0.w = Length of string (UCM coordinates)
       d1.w = Number of characters that will fit

Error Output: cc  = Carry bit set to one
       d1.w = Error code

Possible Errors: E$UnID, E$NoFont, E$BPNum
VIQ_CPos - Return Relative Character Positions

VIQ_CPos takes a string of characters and returns in a buffer 
the relative horizontal position (in UCM coordinates) of each 
character, starting  from  the  first,  from  the  placement  
coordinate if it were to be drawn using the DR_Text function. 
Each entry in  the returned list  is a  16-bit signed value.  
VIQ_CPos continues to process characters until either a null  
is found in the text string or until the number of characters 
specified in  d4.l  are  processed,  whichever  condition is  
satisfied first. If there is no active font, E$NoFont will be 
returned.

Input:  d0.w = Path number
       d1.w = SS_VIQ getstat code
         d2.w = VIQ_CPos function code
         d3.w = Drawmap identifier
         d4.w = Number of text characters in string
       (a0) = Text pointer
        (a3) = Pointer to buffer for relative
                          
                         positions list

Output:  None

Error Output: cc  = Carry bit set to one
       d1.w = Error code

Possible Errors: E$UnID, E$NoFont, E$BPNum

VIQ_JCPs - Return Character Positions for Justified text

VIQ_JCPs takes a string of characters and returns in a buffer 
the relative horizontal position of each character, as defined 
for VIQ_CPos,  if  it were  to  be drawn  using  the DR_JTxt  
function. If  there  is  no active  font,  E$NoFont  will be  
returned.

Input:  d0.w = Path number
        d1.w = SS_VIQ getstat code
        d2.w = VIQ_JCPs function code
        d3.w = Drawmap identifier
        d4.w = Justification length (in UCM coordinates)
        d5.w = Number of text characters 
        (a0) = Text pointer
        (a3) = Pointer to buffer for relative 
          positions list

Output:  None

Error Output: cc  = 
              Carry bit set to one
        d1.w = Error code

Possible Errors: E$UnID, E$NoFont, E$BPNum

VIQ_FDta - Return Font Data

VIQ_FDta returns the font data section of the specified font  
(see VII.2.3.2.10). 

Input:  d0.w = Path number
        d1.w = SS_VIQ getstat code
        d2.w = VIQ_FDta function code
        d3.w = Font identifier
        (a0) = Pointer to buffer for font data 
                                                
                                               section

Output:  None

Error Output: cc  = 
              Carry bit set to one
        d1.w = Error code

Possible Errors: E$UnID, E$BPNum
VIQ_GDta - Return Glyph Data

VIQ_GDta returns the glyph data table entry for the specified 
glyph in the specified font. (see VII.2.3.2.10).


Input:  d0.w = Path number
        d1.w = SS_VIQ getstat code
        d2.w = VIQ_GDta function code
        d3.w = Font identifier
        d4.w = Glyph number
        (a0) = Pointer to buffer for glyph data

Output:  None

Error Output: cc  = 
              Carry bit set to one
        d1.w = Error code

Possible Errors: E$IllPrm, E$UnID, E$BPNum

VIQ_RGInfo - Return Pointer to Region Data Structure

VIQ_RGInfo returns a pointer to the Region Data Structure for 
information purposes only (see VII.2.3.2.6).

Input:  d0.w = Path number
        d1.w = SS_VIQ getstat code
        d2.w = VIQ_RGInfo function code
        d3.w = Region identifier

Output:  (a0) = Pointer to region data structure

Error Output: cc  = Carry bit set to one
        d1.w = Error code

Possible Errors: E$UnID, E$BPNum
VIQ_PntR - Test if Point in Region

VIQ_PntR tests whether the specified coordinate is contained  
in the specified region or not.

Input:  d0.w = Path number
        d1.w = SS_VIQ getstat code
        d2.w = VIQ_PntR function code
        d3.w = Region identifier
        d4.1 = Point (H:V) coordinate

Output:  d0.w = Non-zero if true, zero if false

Error Output: cc  = Carry bit set to one
        d1.w = Error code

Possible Errors: E$UnID, E$BPNum

VIQ_RLoc - Inquire Region Location

VIQ_RLoc returns  the boundary  rectangle for  the specified  
region.

Input:  d0.w = Path number
       d1.w = SS_VIQ getstat code
         d2.w = VIQ_RLoc function code
         d3.w = Region identifier

Output:  d0.l = Coordinate (H:V) of upper-left corner
       d1.l = Coordinate (H:V) of lower-right corner

Error Output: cc  = Carry bit set to one
         d1.w = Error code

Possible Errors: E$UnID, E$BPNum
VIQ_DMInfo - Return Pointer to Drawmap Descriptor

VIQ_DMInfo returns a  pointer to the  drawmap descriptor for  
information purposes only (see VII.2.3.4.1).

Input:  d0.w = Path number
        d1.w = SS_VIQ getstat code
        d2.w = VIQ_DMInfo function code
        d3.w = Drawmap identifier

Output:  (a0) = Pointer to drawmap descriptor

Error Output: cc = Carry bit set to one
        d1.w = Error code

Possible Errors: E$UnID, E$BPNum
2.3.4.8 Character Output Functions

The UCM also provides the capability  of treating a drawmap in  
much the same way as the display screen of a CRT terminal. The  
standard CD-RTOS system calls I$Write and I$WriteLn are used to 
write text  in this  manner. Since  the UCM  supports multiple  
images (multiple drawmaps)  and multiple  fonts, functions are  
described in  this section  to set  the  drawmap and  font for  
character output for  a particular  path before  I$WriteLn and  
I$Write can be used.

For any particular drawmap the active fonts must be monospaced  
and have the same character cell size. The number of characters 
per line and lines per screen  are determined by the character  
cell size of the  active fonts. If new  fonts with a different  
character cell size are activated all active fonts must first be 
deactivated. UCM will then recalculate the number of characters 
per line and lines per drawmap.

I$WriteLn - Write Line

I$WriteLn is a standard CD-RTOS service request. It writes a  
string of characters until either a carriage return ($0D) is  
found or the specified number of characters is written.

If a carriage return (code $OD) is found, UCM appends a cursor 
down (code $OA, also named line feed). 

 Input:  d0.w = Path number
       d1.l = Number of bytes to write
         (a0) = Text string pointer

 Output:  d1.l = Number of characters written

 Error Output: cc  = Carry bit set to one
       d1.w = Error code

Possible Errors: E$NoFont, E$NoDM, E$BPNum
I$Write - Write

I$Write is a standard  CD-RTOS service request.  It writes a  
string of the specified number of characters.

 Input:  d0.w = Path number
       d1.l = Number of bytes to write
         (a0) = Text string pointer

 Output:  d1.l = Number of characters written

 Error Output: cc  = Carry bit set to one
       d1.w = Error code

Possible Errors: E$NoFont, E$NoDM, E$BPNum
CO_COD - Set Character Output Drawmap

CO_COD sets the drawmap that will be used for character output 
by I$Write or I$WriteLn for the specified path.

 Input:  d0.w = Path number
       d1.w = SS_CO setstat code
         d2.w = CO_COD function code
         d3.w = Drawmap identifier
 
 Output:  None

 Error Output: cc  = Carry bit set to one
       d1.w = Error code

Possible Errors: E$UnID, E$BPNum


CO_SCMM - Set Character Mode Mapping Method

CO_SCMM sets the way that the I$Write and I$Writeln function  
will interpret the character codes  passed to them (e.g. how  
they will  translate them  to  glyph numbers).  The possible  
methods are the eight bit, seven/fifteen bit, and sixteen bit 
methods (0 = eight bit, 1 = seven/fifteen bit, and 2 = sixteen 
bit; see VII.2.3.2.9). 

Input:  d0.w = Path number
        d1.w = SS_CO setstat code
        d2.w = CO_SCMM function code
        d3.w = Mapping method

Output:  None

Error Output: cc = Carry bit set to one
        d1.w = Error code

Possible Errors: E$IllPrm, E$BPNum
CO_AFnt - Activate Font

CO_AFnt sets  the  fonts  that  the  I$Write  and  I$WriteLn  
functions will select glyphs from. Since these functions may  
select from up to four fonts, each  font set by this call is  
associated with an active font number in the range of 0 to 3. 
The fonts activated with this  call must be monospaced fonts  
and have that same character cell size. To change cell size,  
all currently activated fonts must first be deactivated using 
the  CO_DFnt  function.   Only  if  all   active  fonts  are   
de-activated and then one new one is activated, CO_AFnt will  
reposition the cursor to the upper left corner of the display.

Input:  d0.w = Path number
        d1.w = SS_CO setstat code
        d2.w = CO_AFnt function code
        d3.w = Font identifier
        d4.w = Active font number

Output:  None

Error Output: cc = Carry bit set to one
        d1.w = Error code

Possible Errors: E$IllPrm, E$NoFont, E$UnID, E$BPNum

CO_DFnt - Deactivate Font

CO_DFnt deactivates a font activated by the CO_AFnt function. 
The font which is associated  with the specified active font  
number is deactivated.

Input:  d0.w = Path number
        d1.w = SS_CO setstat code
        d2.w = CO_DFnt function code
        d3.w = Active font number

Output:  None

Error Output: cc = Carry bit set to one
        d1.w = Error code

Possible Errors: E$IllPrm, E$BPNum





2.3.4.9 CRT Terminal Emulation Control Codes

This section describes character codes that are to be used for  
such functions as  cursor addressing,  backspace, and carriage  
return.

In this section a "space character"  is defined as a rectangle  
with color value of color register 0 of the color register table 
in the drawmap descriptor (set by DP_SCR).

All character positions (e.g. top and bottom line and first and 
last column)  in  this  section are  related  to  the complete  
character output drawmap, not to the visible screen.

Cursor Up - Code $0B

This character causes the cursor to  be moved up one line in  
the same column. If the cursor is on the top line then it is 
not moved.

Cursor Down - Code $0A

This character causes the cursor to be moved down one line in 
the same column. If  the cursor is  positioned on the bottom  
line, this code will cause the screen or window to scroll up 
one line and the bottom line is cleared to space characters.  
This code is also known as a line feed

Cursor Right - Code $0C

This character causes the cursor to move one position to the  
right. If the cursor is positioned on the last column and the 
auto wrap mode is on, it moves  to the first position of the  
next line. If the cursor is on the last column of the bottom  
line and the auto wrap mode is  on, this code will cause the  
screen or window to scroll up one line and the cursor moves to 
the first position  of the bottom  line which  is cleared to  
space characters.

Cursor Left - Code $08

This character causes the cursor to move one position to the  
left. If the  cursor is positioned  on the  first column, it  
moves to  the last  position of  the  previous line.  If the  
cursor is on the first  column of the top  line, it does not  
move. This code is also known as backspace.



Cursor Home - Code $1E

This character causes  the cursor to  be moved  to the first  
column of the top line.

Carriage Return - Code $0D

This character causes the cursor to move to the first position 
of the current line.

Cursor Address - Code Sequence $1B $30 CC RR

This sequence moves the cursor to  a new position. CC and RR  
above represent  the  column and  row  numbers respectively,  
biased by $1F. For example, CC and RR for column 1(left-most  
column), row 1 (top row) would be $20 $20.

Delete Line - Code Sequence $1B $31

This sequence  causes  the  line  on  which  the  cursor  is  
positioned to be  replaced by the  line below  it. All lines  
following the deleted line are scrolled  up by one line. The  
bottom line is cleared to space characters.

Insert Line - Code Sequence $1B $32

This sequence  causes  the  line  on  which  the  cursor  is  
positioned and all lines following it to be scrolled down by  
one line.  The line  on which  the  cursor is  positioned is  
cleared to space characters.

Show Cursor - Code Sequence $1B $33

This sequence causes the cursor to appear on the screen.

Hide Cursor - Code Sequence $1B $34

This sequence causes the cursor to disappear from the screen.

Clear to End of Line - Code Sequence $1B $35

This sequence causes all characters from the cursor position  
to the end of the line to be cleared to space characters.

Clear to End of Screen - Code Sequence $1B $36

This sequence causes all characters from the cursor position  
to the end of the drawmap to be cleared to space characters.
Start Reverse Video - Code Sequence $1B $37

All characters written following this sequence will appear on 
the display with each pixel in the glyph complemented before  
it is used  to select  color data  from a color  register or  
written to the drawmap.

End Reverse Video - Code Sequence $1B $38

All characters following this sequence will appear normally on 
the display.  This  sequence reverses  the  previous control  
sequence. 

Start Underlining - Code Sequence $1B $39

All characters written following this sequence will appear on 
the display with an underline.

End Underlining - Code Sequence $1B $3A

All characters written following this sequence will appear on 
the display without an underline.

Clear Screen - Code Sequence $1B $3B

This sequence causes all character positions to be cleared to 
space characters. It does not cause the cursor to move.

Insert Character - Code Sequence $1B $3C

This sequence causes the character  under the cursor and all  
characters to the right of it on the line to be moved to the 
right one character position. The character under the cursor  
is cleared to a space character.  If there is a character in  
the last column, it is removed.

Delete Character - Code Sequence $1B $3D

This sequence causes all characters to the right of the cursor 
on the line to be moved  to the left one character position.  
The character  under the  cursor is  destroyed and  the last  
character position  on  the  line  is  cleared  to  a  space  
character.

Turn On Auto Wrap - Code Sequence $1B $3E

After this sequence is given, when any character is written to 
the last character position of a line, the carriage return and 
cursor down functions will automatically be performed.
Turn Off Auto Wrap - Code Sequence $1B $3F

After this sequence is given, when any character is written to 
the last character position of a line, the cursor will not be 
moved as it would be if  characters were written to previous  
character positions.
2.3.5 Pointer Input Functions

This set of functions is provided to access pointer type devices 
such as  mice and  graphics tablets.  Several pointers  may be  
accessed by an  application simply  by opening  a path  to the  
device associated with the pointer. 

PT_Coord - Obtain Pointer Coordinates

PT_Coord returns the current coordinate of the pointer (with  
respect to  the origin),  the pointer  state and  the button  
state.  The  pointer  active  bit  indicates,  for  graphics   
tablets, touch screens etc  that the pointer  is active. For  
pointers which are always active this bit will always be set  
to one. 

Input: d0.w = Path number
 d1.w = SS_PT getstat code
   d2.w = PT_Coord function code

Output: d0.w = Pointer and Button state
    Meaning (when set to one):
       Bit 0 = 1: Button 1 depressed
       Bit 1 = 1: Button 2 depressed
       Bits 2 to 14 reserved
       Bit 15 = 1: Pointer active
  d1.l = Pointer (H:V) coordinate

Error Output: cc  = Carry bit set to one
   d1.w = Error code

Possible Errors: E$BPNum
PT_SSig - Send Signal on Pointer Change

PT_SSig sets up a  signal to be sent  to the calling process  
when the pointer is moved or when one of its triggers changes 
state.

Input: d0.w = Path number
 d1.w = SS_PT setstat code
   d2.w = PT_SSig function code
 d3.w = User defined signal code

Output: None

Error Output: cc  = Carry bit set to one
   d1.w = Error code

Possible Errors: E$PBNum, E$NotRdy

PT_Relea - Release Device

PT_Relea releases the pointer from a PT_SSig request that was 
made.

Input: d0.w = Path number
 d1.w = SS_PT setstat code
 d2.w = PT_Relea function code

Output: None

Error Output: cc  = Carry bit set to one
   d1.w = Error code

Possible Errors: E$BPNum

PT_Org - Set Pointer Origin

PT_Org adjusts the origin of  the pointing device within its  
coordinate space. The new  origin is specified  as an offset  
from the default origin which is the upper left corner of the 
full screen display. 

Input: d0.w = Path number
  d1.w = SS_PT setstat code
  d2.w = PT_Org function code
  d3.l = New origin (H:V)
     (High Resolution coordinates)

Output: None

Error Output: cc  = Carry bit set to one
  d1.w = Error code

Possible Errors: E$BPNum

PT_Pos - Set Pointer Position

PT_Pos adjusts  the  position  of  the  pointer  of relative  
pointing devices with respect to  the origin of the pointing  
device. This call  adjusts the  coordinates returned  by the  
pointer. 

Input: d0.w = Path number
  d1.w = SS_PT setstat code
  d2.w = PT_Pos function code
  d3.l = New position (H:V) (High Resolution coordinates)
Output: None

Error Output: cc  = Carry bit set to one
  d1.w = Error code

Possible Errors: E$BPNum

2.3.6 Keyboard Input Functions


Data from the  keyboard is retrieved  using CD-RTOS's standard  
input function I$Read. Additional functions are provided to get 
more information and inquire about and control the status of the 
keyboard.


I$Read - Read String

I$Read reads a string of characters from the keyboard device  
until the specified number of characters has been read. Note  
that UCM does not write these characters to the display.

 Input: d0.w = Path number
 d1.l = Number of bytes to read
 (a0) = Buffer pointer

 Output: d1.l = Number of characters read

 Error Output: cc  = Carry bit set to one
  d1.w = Error code

Possible Errors: E$BPNum, E$BMode, E$Read, E$EOF, E$NotRdy

KB_Rdy - Check for Data Ready

KB_Ready returns the number of characters in the input buffer. 
These characters may relate to either key down or auto-repeat 
events; key-up events are ignored as far as this function is  
concerned.

Input: d0.w = Path number
 d1.w = SS_KB getstat code
  d2.w = KB_Rdy function code

Output: d1.l = Number of characters available

Error Output: cc  = Carry bit set to one
   d1.w = Error code

Possible Errors: E$BPNum, E$NotRdy (if no data available)

This function can be used to read all available keyboard data 
at one go, by using the returned value as the "count" argument 
to I$Read.KB_Read - Read Keyboard Event

KB_Read allows access to extended information about keyboard  
events. Events are queued and  returned individually for key  
down, key up and auto repeat. 

Input: d0.w = Path number
  d1.w = SS_KB getstat code
  d2.w = KB_Read function code
  d3.w = mode
    bit 0 = sleep mode if set
    bit 1 = unstack mode if set

Output: d0.w = character code
  d1.b = data type
    Meaning (when set to one):
    Bit 0 : key down
    Bit 1 : auto-repeat
    Bit 2 : key up
  
Error output: cc  = Carry bit set to one
  d1.w = Error code

Possible Errors: E$BPNum, E$Read, E$NotRdy

If the buffer  is empty  when this  function is  called, the  
action taken depends on the 'sleep mode' bit in d1; if it is  
zero, the function will return immediately with d1 = 0; if it 
is one,  the caller  will  be put  to sleep  until  an event  
arrives.

The unstack bit indicates whether the event is to be removed  
from the  input buffer;  hence, if  this bit  is not  set, a  
subsequent identical call  to KB_Read  will return  the same  
event again.

Important Notes

Once KB_Read has been called, the driver will assume that the 
application intends to read all subsequent keyboard data using 
KB_Read, not I$Read. This affects the working of the function 
KB_SSig as described below.

An application wishing to process all events currently in the 
input buffer may use repeated KB_Read  calls until a zero is  
returned in d1; KB_Ready  should not be  used to 'count' the  
buffer since this ignores key-up events.


KB_SSig - Send Signal on Keyboard data ready

KB_SSig sets up a  signal to be sent  to the calling process  
when data from the  keyboard is available.  Normally, only a  
key-down or auto-repeat event  will result in  a signal; if,  
however, KB_Read has previously  been called on  the path, a  
key-up event will also cause a signal.

Input: d0.w = Path number
 d1.w = SS_KB setstat code
  d2.w = KB_SSig
   d3.w = User defined signal code

Output: None

Error Output: cc  = Carry bit set to one
   d1.w = Error code

Possible Errors: E$BPNum, E$NotRdy

KB_Rel - Release device

KB_Rel releases the keyboard from a KB_SSig request that was  
made.

Input: d0.w = Path number
 d1.w = SS_KB setstat code
  d2.w = KB_Rel function code

Output: None

Error Output: cc  = Carry bit set to one
   d1.w = Error code

Possible Errors: E$BPNum





KB_Repeat - Set Keyboard Latency and Repeat Times

KB_Repeat allows an  application to alter  the keyboard auto  
repeat latency and repeat times to suit the preferences of a  
user. The times are specified in units of one system tick (10 
milliseconds) unless the high order bit is set, in which case 
the rest of  the long  word specifies  how many 256ths  of a  
second.

Input: d0.w = Path number
  d1.w = SS_KB setstat code
  d2.w = KB_Repeat function code
  d3.l = Latency time
  d4.l = Repeat time

Output: None

Error output: cc  = carry bit set to one
  d1.w = Error code

Possible Errors: E$BPNum

If the latency time is specified as zero, no auto repeat will 
be generated.

If the latency and repeat times are respectively non-zero and 
zero, only one auto repeat will be generated.
KB_Stat - Determine Status of Keyboard

KB_Stat returns information  about the current  state of the  
keyboard, including the state of the special keys.

Input: d0.w = Path number
  d1.w = SS_KB getstat code
  d2.w = KB_Stat function code
  
Output: d0.w = character code
  d1.b = special keys state
    Bit 0 : shift depressed when set
    Bit 1 : caps depressed when set
    Bit 2 : supershift depressed when set
    Bit 3 : control depressed when set
    
If the character code is 0, then no keys are being pressed.

Error Output: cc  = Carry bit set to one
   d1.w = Error code

Possible Errors: E$BPNum

Warning

This function relates to the actual keyboard state and doesn't 
affect the  input  buffer  in any  way.  Hence,  even  if an  
application wishes to  use exclusively  KB_Stat for keyboard  
polling, it should  flush the  buffer occasionally  (e.g. by  
using KB_Read in "unstack but don't sleep mode" until no event 
is returned) to avoid input over-run.







2.4  Non-volatile RAM File Manager (NRF)

2.4.1  General


The non-volatile RAM file manager (NRF) provides file  level support   for 
battery backed up system memory.  NRF offers an alternative to RBF's  'RAM 
disks' when the amount of non-volatile RAM is  small.  NRF provides   less 
functionality than  RBF and  slower throughput  than pipes,  however,   it 
consumes a much smaller amount of memory for file structure overhead.

Non-volatile RAM  is  often a  very  precious system  resource.   NRF   is 
specifically customized to  use as  little of this  memory as    possible. 
Applications needing to keep small files in memory should always use   RAM 
disk files or named pipes in preference to NRF files when possible.


2.4.2  I$Create - Creating NRF Files


The I$Create service request is used with the  NRF manager to create   new 
named files.

NRF files may be created by using the pathlist "/NVR/<name>" where  <name> 
is the logical file  name.  If an NRF  file with the  same name    already 
exists, an  error  (E$CEF)  is  returned.   Access  permissions  may    be 
specified, and are handled similar to RBF3.

The application must  specify an  initial file size  for NRF  files   when 
creating a new file.  This is done by  passing the desired file size    in 
register d2.   This technique  allows NRF  to ensure  that  enough   space 
exists for the file, and speeds up subsequent write requests.


      Input:     d0.w = Access mode (W R)
           d1.w = File attributes (PW PR W R)
           d2.l = Initial file size
           (a0) = Pathname pointer

      Output:    d0.w = Path number
           (a0) = Updated past the pathlist
      Error Output:    cc   = Carry bit set to one
           d1.w = Error code

      Possible Errors:     E$PthFul, E$BPNam, E$MemFul, E$CEF


      Access mode format:

                         ___________________________________________
                         _ Bit Number _ Description (if set to one)_
                         ___________________________________________
                         _     0      _ Read (R)                   _
                         _     1      _ Write (W)                  _
                         _    2-15    _ Reserved                   _
                         ___________________________________________

      File attributes format:

                         ___________________________________________
                         _ Bit Number _ Description (if set to one)_
                         ___________________________________________
                         _     0      _ Owner read (R)             _
                         _     1      _ Owner write (W)            _
                         _     2      _ Reserved                   _
                         _     3      _ Public read (PR)           _
                         _     4      _ Public write (PW)          _
                         _    5-15    _ Reserved                   _
                         ___________________________________________


2.4.3  I$Open - Opening NRF Files


An existing NRF file  may be accessed using  the I$Open service   request, 
passing the  same  name specified  when  the file  was  created.    I$Open 
searches through a  list of  file names associated  with the  given    NRF 
device descriptor.  If the file name is not  found, an error (E$PNNF)   is 
returned.

NRF enforces record locking for  files on the NVRAM  device.  If an   open 
request is made for an NRF file while it is being created, or is   already 
open for write access,  an error (E$Busy) is  returned.  Similarly if    a 
file is open for read access and a process attempts to open it for   write 
access an error (E$Busy)  is returned.  Several processes  may have    the 
same NRF file opened simultaneously only if they do not have write  access 
to the file.


      Input:     d0.w = Access mode
           (a0) = Pathname pointer

      Output:    d0.w = Path number
           (a0) = Updated past pathname

      Error Output:    cc   = Carry bit set to one
           d1.w = Error code

      Possible Errors:      E$PthFul, E$BPNam, E$BMode, E$FNA,   E$PNNF, 
                           E$Busy, E$Share

      Access mode format:

                    ___________________________________________
                    _ Bit Number _ Description (if set to one)_
                    ___________________________________________
                    _     0      _ Read (R)                   _
                    _     1      _ Write (W)                  _
                    _    2-5     _ Reserved                   _
                    _     6      _ Non-shareable use          _
                    _     7      _ Directory                  _
                    ___________________________________________


2.4.4  I$Delete - Deleting Files


The I$Delete service request is used to remove NRF files and return  their 
memory to the system.  A process must have  write permission for any   NRF 
file being deleted.  If the file is not  found or is currently open,    an 
error (E$PNNF or E$Busy) is returned.

When an  NRF  file is  deleted,  other non-volatile  RAM  files  will   be 
compacted together to make the available memory contiguous.

      Input:     d0.w = Access mode
           (a0) = Pathname pointer

      Output:    (a0) = Updated past pathname

      Error Output:    cc   = Carry bit set to one
           d1.w = Error code

      Possible Errors:     E$BPNam, E$PNNF, E$BMode

      Access Mode Format:  See VII.2.4.2.

2.4.5  I$Seek - Random Access

The I$Seek service request may be used to access data within an NRF   file 
randomly.  No error  is produced  at the time  of the  seek if  the    new 
position is beyond the current 'end of file'.

      Input:     d0.w = Path number
           d1.l = New file position

      Output:    None

      Error Output:    cc   = Carry bit set to one
           d1.w = Error code

      Possible Errors:     E$BPNum



2.4.6  I$Read, I$ReadLn - Reading Data

NRF supports I$Read and I$ReadLn  for returning the specified  number   of 
data bytes from the  current file position.  I$ReadLn  terminates when   a 
carriage return or the  specified number of characters  have been    read, 
whichever comes first.  An  end of file error  (E$EOF) is returned    when 
there is no more data in the file.

      Input:     d0.w = Path number
           d1.l = Maximum number of bytes to read
           (a0) = Buffer pointer

      Output:    d1.l = Number of bytes actually read

      Error Output:    cc   = Carry bit set to one
           d1.w = Error code

      Possible Errors:     E$BPNum, E$Read, E$BMode, E$EOF



2.4.7  I$Write, I$WriteLn - Writing Data

The I$Write and I$WriteLn service requests may be used to write data  into 
an NRF  file.   I$WriteLn  terminates  when  a carriage  return  or    the 
specified number of bytes have been read, whichever comes first.   I$Write 
requests beyond the current 'end of file' automatically  expand the   file 
with the new data.  An error (E$Write) is returned if there is not  enough 
memory to satisfy the write request.

The data within  an NRF  file occupies one  contiguous block  of   memory. 
Expanding a  file  may  cause  a  reorganization  of  files  within    the 
non-volatile RAM.

      Input:     d0.w = Path number
           d1.l = Maximum number of bytes to write
           (a0) = Buffer pointer

      Output:    d1.l = Actual number of bytes written

      Error Output:    cc   = Carry bit set to one
           d1.w = Error code

      Possible Errors:     E$BPNum, E$BMode, E$Write, E$MemFul



2.4.8  I$Close - Closing NRF Files


The I$Close service request must be used to close an NRF file when it   is 
no longer needed.  Files open for write access must be closed before  they 
may be accessed by any other process.  An NRF file may not be deleted   if 
it is open.

      Input:     d0.w = Path number

      Output:    None

      Error Output:    cc   = Carry bit set to one
           d1.w = Error code

      Possible Errors:     E$BPNum


2.4.9  Status Functions


In the I/O System Calls chapter of Appendix VII.1 a specification of   the 
parameters and function of the status functions is  given. Figure   VII.21 
below lists the status functions that are supported by NRF.


Figure VII.21

GetStat Functions:
________________________________________________________________
_  Name   _                  Description                       _
________________________________________________________________
_ SS_Opt  _ Reads the 128-byte path descriptor option section  _
_ SS_Size _ Returns the current file size                      _
_ SS_EOF  _ Tests for end of file                              _
_ SS_FD   _ Returns the file descriptor                        _
_ SS_Pos  _ Get current file position                          _
_ SS_FDInf_ Get specified FD information                       _
_ SS_Free _ Return size of free space on device                _
________________________________________________________________

SetStat                                                         Functions:                                                       
________________________________________________________________
_  Name   _                  Description                       _
________________________________________________________________
_ SS_Opt  _ Rewrites the 128-byte path descriptor option       _
_         _ section                                            _
_ SS_Size _ Expands or contracts the file to the specified size_
_ SS_Attr _ Changes the NRF file attributes                    _
________________________________________________________________



2.4.10  Changing and Making Directories


The NRF file  manager does  not support directory  files and  returns   an 
error (E$UnkSvc) for both the I$MakDir and I$ChgDir service requests.



2.4.11  NRF Directories


It is possible to determine the contents of an NRF device by opening   the 
NVRAM device  in  Directory mode.   Subsequent  read requests  return    a 
32-byte record for each  NRF file, in a  format compatible with  RBF   and 
PIPE devices.  This allows utilities that normally read an RBF   directory 
file sequentially to work with NRF as well.



2.5  Error Codes


      Error Number     Description

      006:000 E$IllPrm Illegal Parameter

      006:001 E$IdFull Identifier (ID) table full

      006:002 E$BadSiz Bad size error

      006:003 E$RgFull Region definition full (overflow)

      006:004 E$UnID   Unallocated identifier number

      006:005 E$NullRg Null Region

      006:006 E$BadMod Bad drawmap/region/pattern mode

      006:007 E$NoFont No active font

      006:008 E$NoDM   No drawmap

      006:009 E$NoPlay No audio play in progress

      006:010 E$Abort  Play aborted





VII.3  Device Drivers

3.1  Compact Disc

3.1.1  Introduction


This section  specifies  the interface  between  the Compact  Disc    File 
Manager (CDFM) and its drivers.  As with all CD-RTOS device drivers,   the 
CDFM  drivers  will  perform  basic  low  level  physical     input/output 
functions.  The driver is  not concerned with files,  directories,   etc., 
which are handled at a higher level by  the CDFM.  Device driver   modules 
are re-entrant  so one  copy of  the module  can  simultaneously   support 
multiple devices that use identical I/O controller hardware.




3.1.2  Basic Functional Requirements of CDFM Drivers


The CDFM device driver module is a package  of six subroutines that    are 
called by the CDFM in system state.  The functions are:

(1) Initialize  the  device  controller  hardware  and  related    driver  
variables as required.

(2) Read standard physical units.

(3) Return a specified device status.

(4) Set a specified device status.

(5) De-initialize the device.  It is assumed that the device will not   be 
used again unless reinitialized.

(6) Play a selected portion of the disc.

When written  properly,  a  single  physical  driver module  can    handle 
multiple identical  hardware interfaces.   The specific  information   for 
each physical interface (port address, initialization constants, etc.)  is 
given in  a device  descriptor module.   Device descriptor  modules    are 
described in section VII.3.1.4.1.





The name by which the device is known  to the system is the name of    the 
device descriptor module.  CD-RTOS  copies the information contained    in 
the device descriptor module  to the path descriptor  data structure   and 
the device driver static storage area for easy access by the drivers.




3.1.3  Driver Module Format


All drivers must conform  to the standard CD-RTOS  memory module   format. 
The module type code is "Drivr".

The execution offset in the module header (M$Exec)  gives the address   of 
an offset table,  which specifies  the starting address  of each  of   the 
seven driver subroutines.  The driver subroutines are called by the   CDFM 
through the offset table.   The driver routines are  always executed    in 
system state.   Each subroutine  is terminated  by an  RTS    instruction. 
Error status is returned using the CC carry bit with an error code  return 
in register d1.w.

The static storage size  (M$Mem) specifies the amount  of local    storage 
required by the driver.  This is the sum  of the storage required by   the 
file manager plus any variables and tables declared in the driver.




3.1.4  Data Structures


CDFM and its  drivers must  concern themselves with  the following    data 
structures:

                  - Device Descriptors
                  - Path Descriptors
                  - Device Static Storage
           - Device Drive Tables
                  - PLAY Control Blocks
                  - PLAY Control Lists






3.1.4.1  CDFM Device Descriptors


Device descriptor modules are small, non-executable modules that   provide 
information that associates a specific I/O device with its logical   name, 
hardware controller address(es), device driver name, file manager    name, 
and initialization parameters.

Device drivers  and file  managers both  operate on  general  classes   of 
devices, not specific I/O  ports.  The device descriptor  modules   tailor 
their function to a  specific I/O device.  One  device descriptor   module 
must exist for each I/O device in the  system.  However, one device    may 
also have  several  device  descriptors  with  different    initialization 
constants.

The name of the module is used as  the logical device name by the   system 
and the user.  Its format consists of a standard module header (48  bytes) 
that has a type code of "device descriptor". The remaining header   fields 
(24 bytes) are standard for device descriptor modules.




3.1.4.1.1  Standard Device Descriptor Header Fields


The first 72 bytes of each device descriptor are defined in the same   way 
for all device descriptors in CD-RTOS.



3.1.4.1.2  Device Descriptor Option Fields (Initialization
           Table)


The initialization table is copied into the 'option section' of the   path 
descriptor when  a  path to  the  device is  opened.   It  is    generally 
referenced using the path  descriptor.  Additional option fields  may   be 
added here.  Currently, only one field is required.   The values in   this 
table may be used to define the operating parameters that are   accessible 
by the I$GetStt  and I$SetStt  system calls.  The  maximum size  of    the 
initialization table is 128 bytes.




Figure VII.22

________________________________________________________________
_Offset_Length_  Name    _            Description              _
________________________________________________________________
_  72  _  1   _ PD_DTP   _ Device class (device class of CDFM  _
_      _      _          _   is 5).                            _
_  73  _  1   _ PD_FC    _ Functional Class (0=CD, 1=Audio)    _
_  74  _  1   _ PD_ErrSz _ Number of bytes per error bit       _
_  75  _  1   _ PD_NDscs _ Number of discs in player           _
_  76  _  1   _ PD_DNum  _ Device number for CD Drive or Audio _
_      _      _          _   Processor                         _
_  77  _  1   _ PD_BFctr _ Blocking factor                     _
________________________________________________________________

3.1.4.1.3  Device Configuration Fields

There is  a  section  of  the  device  descriptor  reserved  for    Device 
Configuration variables  (the DevCon  section).  There  is one    standard 
field in the DevCon section.  This is the  player default character   set. 
If this  field is  all 0's,  it is  considered  to be  the CD-I    default 
character set (ISO 8859-1).  Otherwise, this field will  contain the   ISO 
2022 escape sequence for the player default character set.


3.1.4.2  CDFM Path Descriptors


Every open  path  is represented  by  a data  structure  called  a    path 
descriptor.  Every  time  an  I$Open  system  call is  invoked,  a    path 
descriptor is created.  It contains information required by file  managers 
and device  drivers  to perform  I/O  functions.  Path  descriptors    are 
dynamically allocated and de-allocated as paths are opened and closed.

Path descriptors have three sections, a standard section, a file   manager 
section, and an options section.



3.1.4.2.1  Standard Path Descriptor Fields

The first 42 bytes of the Path Descriptor are defined in the same way  for 
all path  descriptors  in CD-RTOS.   These  fields may  be  read  by   the 
drivers, but may not be modified by them.

Figure VII.22a

_________________________________________________________________
_Offset _ Length _   Name   _           Description             _
_________________________________________________________________
_  0    _    2   _ PD_PD    _Path number                        _
_  2    _    1   _ PD_MOD   _Mode (read/write/update)           _
_  3    _    1   _ PD_CNT   _Number of paths using this P.D.    _
_  4    _    4   _ PD_DEV   _Device Table entry address         _
_  8    _    2   _ PD_CPR   _Current process ID                 _
_ 10    _    4   _ PD_RGS   _Caller's register stack pointer    _
_ 14    _    4   _ PD_BUF   _Buffer address                     _
_ 18    _    4   _ PD_USER  _Group/User ID of path's creator    _
_ 22    _    4   _ PD_Paths _Linked list of open paths on device_
_ 26    _    2   _ PD_COUNT _Actual number of paths using this  _
_       _        _          _P.D.                               _
_ 28    _    2   _ PD_LProc _Last active process ID             _
_ 30    _   12   _    -     _Reserved                           _
_________________________________________________________________

3.1.4.2.2  File Manager Path Descriptor Fields

CDFM defines the following  fields for its own  use.  Drivers will    read 
some of these fields but normally do not write them.























This page is intentionally left blank



Figure VII.23
_________________________________________________________________
_Offset_Length_  Name    _           Description                _
_________________________________________________________________
_  42  _  2   _PD_BIn    _Number of characters in the File      _
_      _      _          _Manager buffer.                       _
_      _      _          _                                      _
_  44  _  4   _PD_Cp     _Current File position.                _
_      _      _          _                                      _
_  48  _  4   _PD_FP     _Actual sector position of beginning of_
_      _      _          _file.                                 _
_      _      _          _                                      _
_  52  _  2   _PD_INTLV  _File interleave factor.               _
_      _      _          _                                      _
_  54  _  4   _PD_Siz    _File size.                            _
_      _      _          _                                      _
_  58  _  4   _PD_FDAddr _Byte address of file descriptor.      _
_      _      _          _                                      _
_  62  _  4   _PD_NxtPD  _Next path descriptor in Play list.    _
_      _      _          _                                       _ _    66 
_  4   _PD_LstPD  _Last path descriptor in Play list.    _
_      _      _          _                                      _
_  70  _  4   _PD_PSRT   _Starting sector of Play selection.    _
_      _      _          _This is the logical starting sector of_
_      _      _          _the Play selection.                   _
_      _      _          _                                      _
_  74  _  2   _PD_PROCID _Process ID of Owner of this path.     _
_      _      _          _Signals from the Play Control List and_
_      _      _          _Play Control Block are sent to the    _
_      _      _          _process with this ID.                 _
_      _      _          _                                      _
_  76  _  4   _PD_PCBptr _Pointer to Play Control Block or      _
_      _      _          _Status Block                          _
_      _      _          _                                      _
_  80  _  2   _PD_DIRCT  _Direction of head movement.           _
_      _      _          _                                      _
_  82  _  4   _PD_PCB    _Reserved for CDFM use.                _
_      _      _          _                                      _
_  86  _  4   _PD_PCL    _Reserved for CDFM use.                _
_      _      _          _                                      _
_  90  _  4   _PD_PCLArr _Reserved for CDFM use                 _
_      _      _          _                                      _
_  94  _  4   _PD_DTPtr  _Drive Table Pointer                   _
_      _      _          _                                      _
_  98  _  6   _          _Reserved                              _
_      _      _          _                                      _
_ 104  _  1   _PD_FNum   _File number.                          _
_      _      _          _                                      _
_ 105  _  1   _PD_CDFlags_CDFM flag bits                        _
_________________________________________________________________
3.1.4.2.3  Option Table Path Descriptor

The first fields of the option table are copied directly from the   device 
descriptor initialization fields.

Figure VII.24

________________________________________________________________
_Offset_Length_  Name  _             Description               _
________________________________________________________________
_  128 _   1  _PD_DTP  _Device class                           _
_      _      _        _                                       _
_  129 _   1  _PD_CDFC _Function class                         _
_      _      _        _                                       _
_  130 _   1  _PD_ErrSz_Number of bytes per error bit          _
_      _      _        _                                       _
_  131 _   1  _PD_NDscs_Number of discs in player              _
_      _      _        _                                       _
_  132 _   1  _PD_DNum _Device number for Audio Processor      _
_      _      _        _                                       _
_  133 _   1  _PD_BFctr_Blocking factor                        _
_      _      _        _                                       _
_  134 _   4  _PD_Did  _Disc ID                                _
_      _      _        _                                       _
_  138 _   2  _PD_Track_Track type.  This indicates the type of_
_      _      _        _track (i.e. CD-I, CD-DA).              _
_      _      _        _                                       _
_  140 _   2  _PD_XAR  _Extended attribute record size.        _
_      _      _        _                                       _
_  142 _   4  _PD_CNUM _Channel mask.  This may be changed by  _
_      _      _        _the user at any time.                  _
_      _      _        _                                       _
_  146 _   32 _PD_TOK  _File name.  This is the file name of   _
_      _      _        _the open path.                         _
_      _      _        _                                       _
_  178 _   2  _PD_PTNUM_Path Table Entry Number                _
_      _      _        _                                       _
_  180 _   1  _PD_PTOFF_Path Table Entry Offset                _
_      _      _        _                                       _
________________________________________________________________
                                                                    3.1.4.3   
CDFM Device Driver Static Storage

CDFM device driver modules contain a package of subroutines that   perform 
sector oriented I/O to, or from, a specific hardware controller.   Because 
these modules are re-entrant, one copy of the  module can   simultaneously 
run several identical I/O controllers.

The kernel will allocate a static storage area for each device (which  may 
control several drives).  The size of the storage  area is given in    the 
device driver  module  header (M$Mem).   Some  of this  storage  area   is 
required by the kernel and CDFM.  The device driver may use the  remainder 
in any manner.

                 Figure VII.25
________________________________________________________________
_Offset_Length_  Name  _Description                            _
________________________________________________________________
_      _      _        _                                       _
_  0   _ 4    _V_PORT  _Device base port address               _
_      _      _        _                                       _
_  4   _ 2    _V_LPRC  _Last active process ID.  This contains _
_      _      _        _the process ID of the last process to  _
_      _      _        _use the device.                        _
_      _      _        _                                       _
_  6   _ 2    _V_BUSY  _Not used by CDFM.  See V_Play          _
_      _      _        _                                       _
_  8   _ 2    _V_WAKE  _Process ID to awaken.  This contains   _
_      _      _        _the process ID of any process that is  _
_      _      _        _waiting for the device to complete I/O _
_      _      _        _(0 = no process waiting).  Maintained  _
_      _      _        _by the device driver.                  _
_      _      _        _                                       _
_ 10   _ 4    _V_PATHS _Linked list of open paths.  This is a  _
_      _      _        _singly-linked list of all paths        _
_      _      _        _currently open on this device.  It is  _
_      _      _        _maintained by the kernel.              _
_      _      _        _                                       _
_ 14   _ 32   _        _Reserved                               _
_      _      _        _                                       _
_ 46   _ 1    _V_NDRV  _Number of drives.  This contains the   _
_      _      _        _number of drives that the controller   _
_      _      _        _can use.  It is defined by the device  _
_      _      _        _driver as the maximum number of drives _
_      _      _        _that the controller can work with.     _
_      _      _        _CDFM will assume that there is a drive _
_      _      _        _table for each drive.                  _
_      _      _        _                                       _
_  47  _  1   _V_NAP   _Number of Audio Processors             _
_      _      _        _                                       _
_  48  _  6   _        _Reserved                               _
_      _      _        _                                       _
_  54  _      _        _Drive tables.  This contains one table _
_      _      _        _per drive that the controller will     _
_      _      _        _handle.  CDFM will assume there are as _
_      _      _        _many tables as specified in V_NDRV.    _
________________________________________________________________


3.1.4.3.1  Drive Tables

After the driver's INIT routine has been called, CDFM requests the  driver 
to initialize the drive table for the corresponding drive.  As   mentioned 
in Figure VII.25 (last item), each drive has a corresponding drive  table. 
The drive table format is as follows:
Figure VII.26
_________________________________________________________________
_Offset_Length_  Name    _          Description                 _
_________________________________________________________________
_  54  _  4   _V_LastPos _Last seek position. Initialized by the_
_      _      _          _CDFM device driver                    _
_      _      _          _                                      _
_  58  _  4   _V_PTSiz   _Path table size.  Initialized by the  _
_      _      _          _CDFM                                  _
_      _      _          _                                      _
_  62  _  4   _V_PTAdd   _Path table address.  Handled  only    _
_      _      _          _by the CDFM.  Set to zero when driver _
_      _      _          _detects disc change or in INIT        _
_      _      _          _routine                               _
_      _      _          _                                      _
_  66  _  2   _V_CHILD   _Child process number                  _
_      _      _          _                                      _
_  68  _  4   _V_PLAY    _Pointer to path  descriptor of Play   _
_      _       _          _path.   Initialized by  the CDFM  and  the_   _ 
_      _          _CDFM device driver.                   _
_      _      _          _                                      _
_  72  _  4   _V_DIRCT   _Direction of head movement.           _
_      _      _          _Initialized by the CDFM               _
_      _      _          _                                      _
_  76  _  4   _V_DSize   _Size of CD-I disc.  Initialized by the_
_      _      _          _CDFM                                  _
_  80  _  4   _V_ChanMask_Channel mask. Initialized by the CDFM _
_      _      _          _device driver                         _
_  84  _  4   _V_APMask  _Audio channel mask. Initialized by the_
_      _      _          _CDFM device driver                    _
_  88  _  1   _V_PlayFlag_Play in progress flag. Initialized by _
_      _      _          _the CDFM device driver                _
_  89  _  1   _V_Paused  _Drive paused flag. Initialized by the _
_      _      _          _CDFM device driver                    _
_  90  _  1   _V_BFctr   _Blocking factor.  Initialized by the  _
_      _      _          _CDFM                                  _
_      _      _          _                                      _
_  91  _  1   _V_IRQlv   _Hardware interrupt level.  Initialized_
_      _      _          _by the CDFM device driver             _
_________________________________________________________________
(continued)



Figure VII.26 (continued)
_________________________________________________________________
_Offset_Length_  Name    _          Description                 _
_________________________________________________________________
_      _      _          _                                      _
_  92  _  1   _V_ROMFlag _CDROM disc flag.  Initialized by      _
_      _      _          _the CDFM device driver                _
_  93  _  1   _V_PTValid _Path Table valid flag.  Initialized   _
_      _      _          _by the CDFM                           _
_      _      _          _                                      _
_  94  _  4   _V_SoundMap_Pointer to current playing soundmap   _
_      _      _          _descriptor by the CDFM device driver  _
_      _      _          _                                      _
_  98  _  2   _V_ASigPrc _Process identifier for audio signal.  _
_      _      _          _Initialized by the CDFM device driver _
_      _      _          _                                      _
_ 100  _  1   _V_AudOff  _Flag for turning off audio.           _
_      _      _          _Initialized by the CDFM device driver _
_      _      _          _                                      _
_ 101  _  1   _V_AudPlay _Flag for soundmap output.  Initialized_
_      _      _          _by the CDFM device driver             _
_      _      _          _                                      _
_ 102  _  1   _V_ErFlags _Error handling flags                  _
_      _      _          _                                      _
_ 103  _ 31   _          _Reserved                              _
_________________________________________________________________

The V_PlayFlag field indicates the type of play in progress:

_________________________________________________________________
_Value Name     Description                                 _
_________________________________________________________________
_ 1 Play_CDI    SS_Play or I$Read of Mode 2 disc in progress_
_ 2  Play_Seek    SS_Seek in progress                         _
_ 3  Play_CDDA    SS_CDDA in progress                         _
_ 4  Play_Read    I$Read of Mode 1 disc in progress           _
_________________________________________________________________

3.1.5  CDFM Device Driver Subroutines

As with all CD-RTOS  device drivers, CDFM device  drivers use a   standard 
executable memory module format with a module type of "Drivr" (code $0E).

The execution offset  address in  the module header  points to  a   branch 
table  that  has  eight  entries.   Each  entry  is   the  offset  to    a 
corresponding subroutine.  The branch table is as follows:

  


Diskent dc.wINIT  Initializes device
       dc.wREAD  Reads character
       dc.wWRITE(Not used)
       dc.wGETSTATGets device status
       dc.wSETSTATSets device status
       dc.wTERM  Terminates device
       dc.w TRAP  Trap entry point
       dc.wPLAY  Plays selection

Each subroutine should exit  with the condition code  register carry   bit 
cleared, i.e. set to zero, if no error occurred. Otherwise the carry   bit 
should be set to one and an appropriate
error code returned in d1.w.

3.1.5.1  The INIT Subroutine

The INIT  routine's  function  is  to  initialize  the  device  and    the 
associated static storage.  The INIT routine must:

(1)    Initialize  the  device's  permanent  storage.   This    minimally 
    consists of initializing V_NDRV to the number of  drives with   which 
    the controller will work.

(2) Initialize device control registers and enable interrupts.

(3) Place the IRQ service routine on the  IRQ polling list by using   the 
F$IRQ service request.

NOTE: Prior to being called, the device permanent storage will be  cleared 
(set to zero) except  for V_PORT which will  contain the device   address. 
The driver should initialize each drive table appropriately for the   type 
of disc the driver expects to be used on the corresponding drive.

Input: (a1) = Device descriptor pointer
           (a2) = Device static storage pointer
           (a4) = Current process descriptor pointer
           (a6) = System global data storage pointer

Output:     None

Error Output:  cc   = Carry bit set to one
           d1.w = Error code








3.1.5.2  The READ Subroutine

The function of the READ subroutine is to  read 'Mode 1' blocks from   the 
disc.



Input: d2.l = Disc logical sector number to read
           d3.l = Number of sectors to read
           (a0) = Read buffer pointer
           (a1) = Path descriptor pointer
           (a2) = Device static storage pointer
           (a4) = Current process descriptor pointer
           (a6) = System global data storage pointer

Output:     None

Error Output:cc   = Carry bit set to one
           d1.w = Error code

3.1.5.3  The WRITE Subroutine


This subroutine is currently illegal on CD-I media.   Any attempt to   use 
the WRITE subroutine will  return with the carry  bit set to  one and   an 
error code of E$UnkSvc in d1.w.



3.1.5.4  The GETSTAT and SETSTAT Subroutines

These two subroutines are grouped together because of their similarity  in 
use.  These  routines  are  used  to  get/set  the  device's     operating 
parameters as specified for the I$GetStt and I$SetStt service requests.

When the driver's getstat or setstat entry point is called, the  registers 
have the following values:

Input: d0.w = Function code
           (a1) = Path descriptor pointer
           (a2) = Device static storage pointer
           (a4)=Current process descriptor pointer
           (a5) = Pointer to user's register stack
           (a6) = System global data storage pointer
           Other registers are function code dependent

Output:     Function code dependent
Error Output:cc   = Carry bit set to one
           d1.w = Error code

The following additional input registers are used for the CDFM   functions 
listed:

    SS_Raw

    d2.l = Disc logical sector number to read
    d3.l = Number of 2340 bytes sectors to read
    (a0) = Address of read buffer
    (a4) = Process descriptor pointer
  
    SS_ReadTOC

    d2.l = Number of bytes
    (a0) = Address of Buffer

    SS_Seek

    d2.l = Logical sector number to seek to
    (a0) = Pointer to status block

    SS_CDDA

    d2.l = Logical sector number to start play
    d3.l = Number of sectors to play
    (a0) = Pointer to status block

    SS_Mount

    d2.w = Disc number
3.1.5.5  The TERMINATE Subroutine


This routine is called when a device is  no longer in use in the   system. 
This is defined as when the link count of its device table entry   becomes 
zero.

The TERM subroutine must:

(1) Wait until any pending I/O has completed.

(2) Disable the device interrupts.

(3) Remove the device from the IRQ polling list.

  Input:    (a1) = Device descriptor pointer
    (a2) = Device static storage pointer
    (a4) = Current process descriptor pointer
    (a6) = System global data pointer
    
  Output:   None

  Error Output: cc=Carry bit set to one
    d1.w    =Error code


3.1.5.6  The TRAP subroutine

The TRAP entry should be defined as the offset to the exception   handling 
code or zero if no handler is available.   This entry point is   currently 
not used by the kernel.

3.1.5.7  The PLAY Subroutine


The PLAY  subroutine  sets up  the  controller's registers  to  'play'   a 
selection.  The PLAY routine must:

(1) Get the starting sector for the play from the path descriptor.

(2) Seek to the starting sector if necessary.

(3) Set up the  file number selection mechanism  using the file    number 
from the path descriptor.

(4) Set up the channel number selection mechanism using the channel  mask 
from the Play Control Block.

NOTE: The Play entry  point will be called  to read all  Mode 2   sectors. 
The Read entry will be called to read Mode 1 sectors.

  Input:    (a1) = Path descriptor pointer
     (a2) = Device static storage pointer
     (a4) = Process descriptor pointer
     (a6) = System global data storage pointer

  Output:   None

  Error Output: cc   = Carry bit set to one
     d1.w = Error code




3.1.5.8  The IRQ Service Request Subroutine


Although this routine is not included in the device driver module   branch 
table and is not  called directly by the  CDFM, it is  a key routine    in 
interrupt driven device drivers.  Its general functions include:

(1)   Poll the device to determine the interrupt type.  If the  interrupt 
    is not caused by the CD controller, the  carry bit must be   returned 
    set to one with an RTS instruction as quickly as possible.

(2) Service device interrupts.

(3) When the IRQ service routine finishes servicing an interrupt it  must 
clear the carry bit (i.e. set to zero) and exit with an RTS instruction.

The IRQ routine must perform very specific instructions when servicing   a 
PLAY interrupt.  These functions are as follows:

(1) Determine the type of Coding Information (Audio, Video, or Data).

(2) Get the path descriptor pointer out of V_PLAY.

(3) Get the PCB out of the path descriptor.

(4) Get the PCL for the type of Coding Information.

(5) Update the PCL and PCB counts.

(6) Copy the  data into  the appropriate PCB  buffer (audio    processor, 
video processor, or memory).
  
(7) Send the PCL_Sig if the buffer for the PCL is full.

(8) Determine if the Play is finished.  If so, send the PCB_Sig signal.

(9) Get the next Play path descriptor from PD_NxtPD.

(10) Put the next Play path descriptor in V_PLAY.

(11) Wake up the next PLAY process.

  Input:    (a2) = Device Static storage pointer
     (a3) = Port address
     (a6) = System global data storage pointer




3.2  UCM Driver Interface


This section defines the interface between the UCM and the drivers   which 
interface it to the user input-output hardware.




3.2.1  Driver and Descriptor Organization and Initialization


The UCM manages three types of I/O; video  display output, pointer   input 
and keyboard input.  However,  the functions of these  devices are   often 
inter-related.  Therefore, a mechanism is provided to logically tie  these 
devices together, thereby  creating one  logical path to  these   devices. 
UCM requires  that the  video device  descriptor references  the   pointer 
device and the keyboard device if one is available.

This enables the application  to reference all devices  on a single   path 
and enables  the system  to work  more closely  with  the devices.     The 
pointer and keyboard descriptors should only reference themselves.

When an application issues an I$Open service request, the CD-RTOS   kernel 
allocates a path descriptor for the path and issues an I$Attach call   for 
the device  named in  the service  request. The  I$Attach  function   will 
allocate static storage for the device and call the device driver's   Init 
routine if this is the first I$Attach issued for the device.

The kernel then  calls the  UCM's Open subroutine.   The UCM  checks   the 
PD_D2N field of the device descriptor to see  if an additional device   is 
named.  If not, UCM returns.  If so, the  UCM issues an I$Attach   service 
request for the  device named.   UCM then repeats  this process  for   the 
device named in PD_D3N.














3.2.2  Data Structures


3.2.2.1  Device Descriptor Format


Device  descriptor  modules  are  non-executable  modules  that    provide 
information which  associates  I/O  devices  with  their logical    names, 
hardware controller address(es), device driver name, file manager    name, 
and initialization parameters.




3.2.2.1.1  Standard Device Descriptor Fields


The first 72 bytes of each device descriptor are defined in the same   way 
for all device descriptors in CD-RTOS.  For further information refer   to 
Appendix VII.1.




3.2.2.1.2  Device Descriptor Option Fields


The options fields of the device descriptor describe the device  dependent 
options for a device.  They are copied into and referenced from the   path 
descriptor when a process opens a path to the device.

Figure VII.27


________________________________________________________________
_Offset_Length_ Name _            Description                  _
________________________________________________________________
_  72  _  1   _PD_DTP_ Device type (6 for UCM)                 _
_  73  _ 27   _      _ Reserved                                _
_ 100  _  1   _PD_FC _ Classes of functions of which device    _
_      _      _      _ is capable                              _
_ 101  _  1   _      _ Reserved                                _
_ 102  _  2   _PD_D2N_ Offset to second device name            _
_ 104  _  2   _PD_D3N_ Offset to third device name             _
_ 106  _  2   _      _ Reserved                                _
________________________________________________________________

The format of the field PD_FC is as follows.

                         _______________
                         _   _   _V_P_K_
_______________
                     bit 7             0

              V = Capable of video display output
              P = Capable of pointer input
              K = Capable of keyboard input



3.2.2.2  Path Descriptor Format


Every time  an  I$Open system  call  is invoked,  a  path  descriptor   is 
created.  It is used  to store information required  by the kernel,    the 
file manager, and the driver to perform an I/O function. Path  descriptors 
have three sections, a standard section, a file  manager section, and   an 
options section.



3.2.2.2.1  Standard Fields


The first forty-two bytes of each path descriptor are defined in the  same 
way for all path descriptors in CD-RTOS.  These fields may be read by  the 
drivers but  they  may  not  modify  them.  For  more  information,    see 
VII.3.1.4.2.1.




3.2.2.2.2  File Manager Fields


The UCM defines the following fields for its  own use.  Drivers may   read 
these fields but they may not write to them.


Figure VII.28


_________________________________________________________________
_ Offset _ Length _  Name      _   Description                  _
_________________________________________________________________
_   42   _   4    _ Reserved   _Space for PD_DV2 of SCF         _
_   46   _   2    _ Reserved   _Space for PD_MAX of SCF         _
_   48   _   1    _ Reserved   _Space for PD_RAW of SCF         _
_   49   _   1    _ PD_DFLGS   _Device detach flags             _
_   50   _   4    _ PD_KDEV    _Keyboard device table entry     _
_   54   _   4    _ PD_KSTAT   _Keyboard driver static storage  _
_   58   _   4    _ PD_PDEV    _Pointer device table entry      _
_   62   _   4    _ PD_PSTAT   _Pointer driver static storage   _
_   66   _   4    _ PD_VDEV    _Video device table entry        _
_   70   _   4    _ PD_VSTAT   _Video driver static storage     _
_   74   _   4    _ PD_FEXEC   _Driver routine to execute       _
_   78   _   4    _ PD_EXTMOD  _External Subroutine Module      _
_        _        _            _  Pointer                       _
_   82   _   4    _ PD_ChOtData_Character output data area      _
_        _        _            _  pointer                       _
_   86   _   4    _ PD_EModData_External Subroutine Module data _
_        _        _            _  area                          _
_________________________________________________________________

The UCM also defines  the following fields in  the Character Output   Data 
Area, pointed to  by PD_ChOtData.   These fields are  to be  used by   the 
video device  driver  for maintaining  the  status of  the  I$Write    and 
I$WriteLn functions; field PD_Flags  is also used by  UCM.  These   fields 
are written to only by the device driver.

Figure VII.29
________________________________________________________________
_ Offset_ Length_   Name     _    Description                  _
________________________________________________________________
_    0  _   2   _ PD_LastRow _ Highest row number for         _
_       _       _            _ character output                _
_    2  _   2   _ PD_LastCol _ Highest column number for      _
_       _       _            _ character output                _
_    4  _   2   _ PD_CurX    _ Horizontal cursor2 location     _
_    6  _   2   _ PD_CurY    _ Vertical cursor1 location       _
_    8  _   2   _ PD_Flags   _ Character output flags          _
_   10  _   4   _ PD_COMD    _ Pointer to character output     _
_       _       _            _ drawmap descriptor              _
_   14  _   2   _ PD_Beg0    _ Beginning glyph number for 1st  _
_       _       _            _ active font                     _
_   16  _   2   _ PD_End0    _ Ending glyph number for 1st     _
_       _       _            _ active font                     _
_   18  _   4   _ PD_AFData0 _ Pointer to beginning of 1st     _
_       _       _            _ active font data                _
_   22  _   2   _ PD_Beg1    _ Beginning glyph number for 2nd  _
_       _       _            _ active font                     _
_   24  _   2   _ PD_End1    _ Ending glyph number for 2nd     _
_       _       _            _ active font                     _
_   26  _   4   _ PD_AFData1 _ Pointer to beginning of 2nd     _
_       _       _            _ active font data                _
_   30  _   2   _ PD_Beg2    _ Beginning glyph number for 3rd  _
_       _       _            _ active font                     _
_   32  _   2   _ PD_End2    _ Ending glphh number for 3rd     _
_       _       _            _ active font                     _
_   34  _   4   _ PD_AFData2 _ Pointer to beginning of 3rd     _
_       _       _            _ active font data                _
_   38  _   2   _ PD_Beg3    _ Beginning glyph number for 4th  _
_       _       _            _ active font                     _
_   40  _   2   _ PD_End3    _ Ending glyph number for 4th     _
_       _       _            _ active font                     _
_   42  _   4   _ PD_AFData3 _ Pointer to beginning of 4th     _
_       _       _            _ active font data                _
_   46  _   1   _ PD_Byte    _ Save byte for write             _
________________________________________________________________
UCM uses  the  least significant  two  bits of  the  PD_Flags  field    to 
determine how is  it to  process characters on  the I$WriteLn    function. 
These bits must be set by the video  driver when it executes the   CO_SCMM 
function.  The format of the PD_Flags field follows:

                           __________________
                           _      R    _ C  _
                           __________________
      R - Reserved for driver use

      C - Character output mapping method
         00 = Seven-bit
         01 = Seven/Fifteen-bit
         10 = Sixteen-bit
         11 = Reserved

  
3.2.2.2.3  Options Fields

All options fields of  the device descriptor are  copied to the    options 
fields of the path descriptor.

Figure VII.30

________________________________________________________________
_Offset_Length_ Name  _           Description                  _
________________________________________________________________
_ 128  _  1   _PD_DTP _Device type (6 for UCM)                 _
_ 129  _ 27   _       _Reserved                                _
_ 156  _  1   _PD_FC  _Classes of functions of which device    _
_      _      _       _is capable                              _
_ 157  _  1   _       _Reserved                                _
_ 158  _  2   _PD_D2N _Offset to second device name            _
_ 160  _  2   _PD_D3N _Offset to third device                  _
_ 162  _  2   _PD_CNum_Current column number                   _
_ 164  _  1   _PD_Errs_Most recent I/O error                   _
________________________________________________________________

The format of the field PD_FC is as follows.
                       _________________
                       _    _    _V_P_K_
                       _________________
                   bit 7               0

              V = Capable of video display output
              P = Capable of pointer input
              K = Capable of keyboard input
3.2.2.3  Driver Static Storage Format

The first 46 bytes of the driver static  storage are defined by    CD-RTOS 
for all drivers:

Figure VII.30a

_________________________________________________________________
_Offset_Length_ Name  _            Description                  _
_________________________________________________________________
_   0  _   4  _V_PORT _Device base port address                 _
_   4  _   2  _V_LPRC _Last active process ID                   _
_   6  _   2  _V_BUSY _Current process ID (0 = unbusy)          _
_   8  _   2  _V_WAKE _Active process ID if driver must wake up _
_  10  _   4  _V_Paths_Linked list of open paths on device      _
_  14  _  32  _   -   _Reserved                                 _
_________________________________________________________________

UCM also requires variables in the static storage  area.  In addition   to 
some reserved area, UCM requires pointers to the Read, Write, GetStat  and 
SetStat routines of the device driver. UCM requires the device driver   to 
initialize these fields when  the driver's Init routine  is called.    The 
definition of the UCM fields follows:

Figure VII.31

_________________________________________________________________
_Offset_Length_ Name  _            Description                  _
_________________________________________________________________
_  46  _  16  _       _Reserved                                 _
_  62  _   4  _V_READ _Address of Read routine                  _
_  66  _   4  _V_WRIT _Address of Write routine                 _
_  70  _   4  _V_PSTA _Address of SetStat routine               _
_  74  _   4  _V_GSTA _Address of GetStat routine               _
_  78  _  80  _V_EXMOD_Reserved                                 _
_ 158  _      _V_UCM  _Start driver static storage              _
_________________________________________________________________


3.2.3  Driver Functions


This section describes the  entry points that each  driver will   contain, 
the functions they are  to perform, the parameters  that are passed,   and 
any return values that must be provided.  All UCM drivers, like all  other 
CD-RTOS drivers, have the seven standard entry points defined in  Appendix 
VII.1. These are Init,  Read, Write, GetStat, SetStat,  Term and    Error. 
When necessary, the driver adds a device interrupt service routine to  the 
CD-RTOS interrupt polling system.



3.2.3.1  Init


The Init function is called when the device is first used.  This  function 
must be implemented in all UCM drivers.  It should initialize any   static 
storage variables,  allocate  any  additional  storage,  initialize    the 
device, and set up any necessary interrupts.

The driver is  also required  by UCM to  initialize the  V_READ,   V_WRIT, 
V_PSTA and V_GSTA fields  of the driver static  storage to point  to   the 
driver Read, Write, SetStat and GetStat functions, respectively.

  Input:  (a1) = Device descriptor pointer
    (a2) = Device static storage pointer
    (a4) = Current process descriptor pointer
    (a6) = System global data pointer

  Output: None

  Error Output:cc   = Carry bit set to one
    d1.w = Error code

  Possible Errors:F$IRQ, F$Event, F$SRqCMem, E$IdFull, F$SRtMem,  E$Unit, 
                      E$BMode, F$SRqMem








3.2.3.2  Read

The UCM keyboard input  driver is required to  implement this    function. 
The Read function returns the next available character from the   keyboard 
input buffer.  If no character is available, then the driver should   wait 
until a character is available.

  Input:  (a1) = Path descriptor pointer
    (a2) = Device static storage pointer
    (a4) = Current process descriptor pointer
    (a6) = System global data pointer

  Output: d0.b = Input character

  Error Output:cc   = Carry bit set to one
    d1.w = Error code

  Possible Errors: E$Read, E$NotRdy

3.2.3.3  Write

The UCM video driver must implement the Write function.  This entry  point 
provides the function where drawmaps can be used  to emulate the   display 
output function  of  CRT  type  terminals.   In addition  to    displaying 
characters, Write must also  perform all of the  control code    functions 
defined in VII.2.3.4.9.

  Input:  d0.w = Path number
    d1.l =  Number of bytes to write
    (a0) = Pointer to characters
    (a1) = Path descriptor pointer
    (a2) = Device static storage pointer
    (a4) = Current process descriptor pointer
    (a6) = System global data pointer

  Output: None

  Error Output:cc   = Carry bit set to one
    d1.w = Error code

  Possible Errors: E$NoFont, E$NoDM







3.2.3.4  GetStat and SetStat

The GetStat and SetStat driver subroutines are used  to implement all   of 
the extra  functions that  are specified  in VII.2.3.   The  general   UCM 
functions are  defined in  VII.2.3.3, the  video driver's  functions   are 
defined in VII.2.3.4, the keyboard driver's in VII.2.3.6, and the  pointer 
driver's in VII.2.3.5. The SS_SLink function is handled completely at  UCM 
level, for the other  functions the UCM passes  the parameters for    each 
function to driver in exactly the same way  as defined in VII.2.3.     Any 
return values are also the same.  In addition, the parameters defined   in 
the input list below also are always passed  to the GetStat and    SetStat 
routines.  If the function code or getstat/setstat code is unknown,  error 
E$UnkSvc is returned.

  Input:  d0.w = System path number
     (a1) = Path descriptor pointer
     (a2) = Device static storage pointer
     (a4) = Current process descriptor pointer
     (a5) = Pointer to user's registers
     (a6) = System global data pointer

  Output: Function dependent

  Error Output:cc   = Carry bit set to one
     d1.w = Error code

  Possible Errors: Function dependent

3.2.3.5  Term

The Term subroutine is called when the device is no longer in use.    This 
function is required by all UCM drivers.  It  should clean up,   disabling 
interrupts and events  set-up, unlinking  linked modules, returning    any 
allocated storage and putting devices into an "off" state.

  Input:  (a1) = Device descriptor pointer
     (a2) = Device static storage pointer
     (a4) = Current process descriptor pointer
     (a6) = System global data pointer

  Output: None

  Error Output:cc   = Carry bit set to one
     d1.w = Error code


  Possible Errors: F$IRQ, F$Event,  F$SRtMem, F$UnLink3.2.3.6  The   TRAP 
  subroutine

The TRAP entry should be defined as the offset to the exception   handling 
code or zero if no handler is available.   This entry point is   currently 
not used by the kernel.

3.2.3.7  IRQ


Although this routine is not included in the device driver module   branch 
table and is  not called  directly by the  UCM, it  is a  key routine   in 
interrupt driven device drivers.  Its general functions include:

  1.   Poll  the  device  to  determine  the interrupt  type.   If    the 
     interrupt was not caused  by the device, the  driver must set    the 
     carry bit to one and exit with an RTS as quickly as possible.

  2.Service device interrupts.

  3.   When the IRQ service routine finishes servicing  an interrupt   it 
     must clear the carry bit (i.e. set to  zero) and exit with an    RTS 
     instruction.

  Input:  (a2) = Device static storage pointer
     (a3) = Device base port address
     (a6) = System global data pointer


NOTE:     IRQ service routines may destroy the following registers only:
    d0, d1, a0, a2, a3 and a6.
    All other registers must be preserved.

3.3 NRF Driver Interface

This section defines the interface between the NRF and its drivers.

3.3.1 General

A device driver is required for the NRF file manager to handle the  actual 
initialization of the NVRAM area the first time the NVRAM is accessed   at 
the time of the first machine startup and to read and write bytes  from/to 
the NVRAM.

The read/write routines  are required  to be part  of the  device   driver 
because the physical NVRAM  area need not be  fully contiguous RAM.    The 
NVRAM area could consist of only the even  or odd addresses of the   NVRAM 
space, or it could  be fully contiguous RAM  of the full  address   space. 
Because of this, NRF only deals with logical addresses of the NVRAM   area 
and the device driver must translate this logical address into a  physical 
memory address.  The first logical byte of the NVRAM area is 0 while   the 
first physical byte of the NVRAM area is  the port address of the    NVRAM 
given in the device descriptor.



3.3.2  Device Descriptor Format

3.3.2.1  Standard Device Descriptor Fields

The first eighty bytes of the device descriptor  are defined in the   same 
way for all device  descriptors in CD-RTOS, see  Appendix VII.1.2.     The 
M$Port field of the device descriptor should contain the base address   of 
the NVRAM area.


3.3.2.2  Device Descriptor Option Fields

The initialization table of the device descriptor is copied into part   of 
the descriptor option section when a path to the device is opened.

_________________________________________________________________
_Offset_Length_ Name  _            Description                  _
_________________________________________________________________
_  72  _  1   _PD_DTP _ Device type                             _
_  73  _  1   _PD_CONT_ Contiguous Flag, 0 = non-contiguous     _
_      _      _       _                  1 = contiguous         _
_  74  _  2   _PD_RSIZ_ RAM size for NVRAM                      _
_________________________________________________________________


3.3.3  Path Descriptor Format

3.3.3.1  Standard Fields

The first forty-two bytes of each path descriptor are defined in the  same 
way for all path descriptors in CD-RTOS.  These fields may be read by  the 
drivers but they may not be modified by them. For more information,  refer 
to Appendix VII.1.2.


3.3.3.2  File Manager Fields

NRF defines the following fields for its own use.  Drivers may read  these 
fields but not modify them.

_________________________________________________________________
_Offset_Length_ Name   _            Description                 _
_________________________________________________________________
_  42  _  4   _PD_CP   _ Current file position                  _
_  46  _  4   _PD_BLKLA_ Block header logical address           _
_  50  _  4   _PD_STAT _ Pointer to device static storage       _
_  54  _  4   _PD_HDBUF_ Block header buffer pointer            _
_________________________________________________________________


3.3.3.3  Option Fields

The following fields are defined as the options  section (PD_OPT) of   the 
path descriptor.   The  first two  fields  are copied  from  the    device 
descriptor initialization table, the last field is set up when a file   is 
opened or created.

_________________________________________________________________
_Offset_Length_ Name   _            Description                 _
_________________________________________________________________
_ 128  _  1   _PD_DTP  _ Device type                            _
_ 129  _  1   _PD_CONT _ Contiguous NVRAM flag                  _
_ 130  _  2   _PD_RSIZ _ NVRAM size                             _
_ 224  _ 32   _PD_NAM  _ File name                              _
_________________________________________________________________











3.3.4  Driver Static Storage

3.3.4.1  Logical Format of NVRAM Area

At logical address 0 of the NVRAM is a sync long word which is used as   a 
flag to indicate that the NVRAM has been initialized. At logical   address 
4 of NVRAM is the logical address of the free block.
_________________________________________________________________
_LogAddr_Length_                     Description                _
_________________________________________________________________
_   0   _  4   _  Sync bytes ($dead code)                       _
_   4   _  4   _  Logical Address of Free Block                 _
_________________________________________________________________

The NVRAM area is managed by NRF as  a list of linked file blocks.    Each 
file has a logically contiguous block of NVRAM  which includes the   block 
header and the actual data storage area for the file.  The free space   is 
kept as  a contiguous  free block  which shares  the  same header  as    a 
standard file, it is  identified by having the  name field start  with   a 
0xFF character.

_________________________________________________________________
_Offset_Length_ Name      _            Description              _
_________________________________________________________________
_   0  _  28  _NVF_FILNAME_ File name                           _
_  28  _   4  _NVF_LSN    _ LSN for RBF compat. (address of     _
_      _      _           _ FD info)                            _
_  32  _   4  _NVF_NEXTBLK_ Logical address of next block       _
_  36  _   4  _NVF_PREVBLK_ Logical address of previous block   _
_  40  _   4  _NVF_BLKSIZ _ Size of block, including header     _
_  44  _   1  _NVF_RES1   _ Reserved byte                       _
_  45  _   1  _NVF_FDATT  _ File attributes (start of FD info)  _
_  46  _   2  _NVF_FDOWN  _ File owner                          _
_  48  _   5  _NVF_FDDATE _ Last modified data (YYMMDDHHMM)     _
_  53  _   1  _NVF_FDLINK _ Link count                          _
_  54  _   4  _NVF_FDSIZE _ File data size                      _
_  58  _   3  _NVF_FDDCR  _ Date created (YYMMDD)               _
_  61  _   1  _NVF_RES2   _ Reserved byte                       _
_________________________________________________________________


3.3.5  Driver functions

This section describes the entry points that the driver will contain,  the 
functions they are to  perform, the parameters that  are passed and    any 
return values that  must be  provided.  All NRF  drivers have  the   seven 
standard entry points defined  in Appendix VII.1, these  are Init,   Read, 
Write, GetStat, SetStat, Term amd IRQ.


3.3.5.1  Init

The Init function is called when the NVRAM is first used.  This   function 
should be implemented to check that the NVRAM  area has been   initialized 
and if not initialize it with a free block size of the NVRAM area.

The parameters for the Init routine are as follows:

  Input:  (a1) = Device descriptor pointer
     (a2) = Device static storage pointer
     (a4) = Current process descriptor pointer
     (a6) = System global data pointer

  Output: None

  Error Output:cc = Carry bit set to one
     d1.w = Error code

3.3.5.2  Read

The Read routine is required to read the  given number of bytes from   the 
NVRAM area into the data buffer.  A driver  Read routine is required    so 
that the physical NVRAM  area may be non-contiguous  addresses, such    as 
using only the odd or even addresses of the NVRAM address space.

  Input:  d0.1 = Number of bytes to read
     d2.1 = Logical address of NVRAM to read
     (a1) = Path descriptor pointer
     (a2) = Device static storage pointer
     (a4) = Current process descriptor pointer
     (a6) = System global data pointer

  Output: byte(s) returned in buffer given by PD_BUF

  Error Output:cc = Carry bit set to one
     d1.w = Error code
3.3.5.3  Write

The Write routine is used to write bytes to the NVRAM area.

  Input:  d0.1 = Number of bytes to write
     d2.1 = Logical address of NVRAM to write
     (a1) = Path descriptor pointer
     (a2) = Device static storage pointer
     (a4) = Current process descriptor pointer
     (a6) = System global data pointer

  Output: byte(s) written to NVRAM from PD_BUF

  Error Output:cc =Carry bit set to one
     d1.w = Error code

3.3.5.4  GetStat and SetStat

The NRF file manager directly handles all the Get/Set Stat codes   defined 
in VII.2.4.9, any  other code  sent to the  file manager  will be   passed 
directly to the driver with the following parameters:

  Input:  d0.w = Function code
     (a1) = Path descriptor pointer
     (a2) = Device static storage pointer
     (a4) = Current process descriptor pointer
     (a6) = System global data pointer

  Output: Function dependent

  Error Output:cc   = Carry bit set to one
     d1.w = Error code

3.3.5.5  Term

The Term routine is  called when the device  is no longer  in use.    This 
function can just return with no error, it need not do anything.

  Input:  (a1) = Device descriptor pointer
     (a2) = Device static storage pointer
     (a4) = Current process descriptor pointer
     (a6) = System global data pointer

  Output: None

  Error Output:cc   =Carry bit set to one
     d1.w = Error code
3.3.5.6  The TRAP subroutine

The TRAP entry should be defined as the offset to the exception   handling 
code or zero if no handler is available.   This entry point is   currently 
not used by the kernel.




VII.4  Synchronization Primitives

CD-RTOS provides several low-level  mechanisms for use by  an   application 
program to synchronize  e.g. visual  effects with audio  data.  The    most 
basic mechanism available is  to simply rely on  the inherent ordering   of 
blocks of  data  on  disc.   In  some  applications  (e.g.,  slide     show 
presentations), the ordering of data may provide all  the   synchronization 
necessary.

A simple  improvement  can be  made  by reading  the  system  clock,    and 
executing a function at a particular time.  CD-RTOS  provides the time   of 
day in increments of 1/100th of a second for this case.

More complicated sychronization methods are possible using an event  and/or 
signals (e.g. software interrupts).  Events are similar to  semaphores  and 
are described completely in the CDRTOS technical manual  (Appendix  VII.1). 
The use of  signals are  covered here.  Signals  may be  generated for    a 
process in any of the following ways:

  - The presence of  a trigger (T), end  of record (EOR),  or end of  file 
(EOF) bit in the subheader submode byte of a real-time sector (see  SS-Play 
in VII.2.2.3.2).

    Note:
    (1)         The EOF and T bits should generate interrupts only   after 
          file number selection.

    (2)         The EOR bit should generate an interrupt  only after   the 
          file and channel number selection.

  - The buffer of a play control list becoming full (see           SS-Play 
in VII.2.2.3.2).
  -  The  expiration  of  a  software  timer  (e.g.,   from  the   F$Alarm 
system call see VII.1.1.4.2).
  - The receipt of data from a user input device (see I$SetStt PT_SSig  in 
VII.2.3.5 or KB-SSig in VII.2.3.6).
  - A software interrupt (signal) sent from other concurrent         
processes.
  - The video line display interrupt.

If a process makes  a call to PT_SSig,  KB_SSig or DC_SSig  while   another 
signal request is pending, the call will return the error E$NotRdy.   After 
receiving the signal from one of these calls the application must  "re-arm" 
the signal  by calling  the function  again in  order  to receive   another 
signal.