printer_op_scenario.txt

使用ISP1362芯片的USB_OTG参考设计源代码比较新的版本

How the printer class operation applet works?

                                                  OKANO, Akifumi / 02-Dec-2003

 a. Printer device attach 
  
     1. Normal enumeration sequence is started by "hub_event_handler()" 
        in "_hc_core/port_ctl.c". 
     
     2. Enumeration transfer sequence managed by 
        "devep_create_device()" in "_hc_core/dev_ep.c" 
        
     3. "clshndl_initialization_method()" called in "devep_create_device()". 
     
     4. "clshndl_initialization_method()" in "_hc_cls/cls_hndl.c". 
        "clshndl_initialization_method()" will find the class for the device. 
        
        It calls the "class initialization routine" which was installed by 
        "clshndl_initialization_method_install()". 
     
     5. "class initialization routine" for the printer is 
        "printer_init_commands()" in "class_dr/printer/printer.c". 
        This is called.
     
     6. "printer_init_commands()" makes printer instance and links this 
        instance to device instance. 
        
        The printer instance will be initialized. 
        
 
 b. Printing start command
   
     1. Application (user interface) layer calls "printer_main()". 
     
        It will process following things...
        
           In "printer_job_initialization()"...
           
              - Prepare printing data : Open file.
              
              - Allocate buffer for the data. 
              
              - Find target endpoint
        
           In "start_printer()"...
           
              - Find and reserve a transfer slot.
                The slot index will be kept in printer instance.
                
              - Initialize variables to start printing. 
              
              - Install printer maintenance routine. 
                It is "async_read_file_and_bulk_out()". 
                
     2. The "printer_main()" finished and return. 
        After this, the maintenance routine will take care about all 
        printing process. 


 c. Printing process maintenance
   
     1. The maintenance routine "async_read_file_and_bulk_out()" will be 
        called from "wait_ms()" function. 
        (Because this function is installed at printing start processing.)
     
     2. The maintenance routine will find the printer which is requesting 
        the printing job processing. 
        
        The request can be found as a condition of variable 
        "pi_ptr->time_for_action" and "gp_sof_counter".
        
           "pi_ptr->time_for_action" is keeping the value for the timing 
           to execute printing job processing. 
           
           IF "pi_ptr->time_for_action" is greater than current timer value, 
           (i.e. "gp_sof_counter") the job processing will not be done. 
           It is be done in future. 
           
           The "pi_ptr->time_for_action" will take 4 kinds of values. 
           Those are...
           
             (1) #define ACTION_IMMIDIATE 0L
             (2) #define ACTION_START     1L
             (3) #define ACTION_IDLE      0xFFFFFFFF
             (4) certain value to execute the printing job processing
           
           The printer which does not have printing process will be kept 
           "pi_ptr->time_for_action == ACTION_IDLE". 
           With this setting, the expression 
           "if ( pi_ptr->time_for_action < gp_sof_counter )" is always false.
           (In WASABI, the gp_sof_counter is assumed never wraparound. 
           So continouous operation for 49 days may be OK. :-) )
 
     3. Right after the printing start, the "pi_ptr->time_for_action" will 
        have value of ACTION_START(==1). This is special value to let the 
        printing job processing needs to do the initial process. 
        
        With this valiable value, the expression 
        "if ( pi_ptr->time_for_action < gp_sof_counter )" will be always true.
        
     4. When the value is ACTION_START in the printing job processing, 
        the local variable will be set to constant value for processing start. 
        Otherwise, those values will be set using previous transfer result. 
        
     5. The printing job processing is defined as function 
        "printer_maintenance()".

        After the call of this function, "pi_ptr->time_for_action" is set to 
        ACTION_IDLE(==0xFFFFFFFF). 
        This means the "printer_maintenance()" function will never be called 
        further unless somebody set the "pi_ptr->time_for_action" to some 
        value. 
        
     6. "size" is the data size remaining in the printer buffer. 
     
        if it is zero, 
             the data will be read from file. 
             the transfer will be started by "atlmix_set_transfer()". 
        else,
             the transfer will be restarted. 
        
        In both cases, the call of "atlmix_set_transfer()" is takes the 
        pointer to the callback function. 
        For the printer job, "read_file_and_bulk_out()" is used as a 
        callback.
     
     7. "read_file_and_bulk_out()" will be called at each transfer completion 
        or termination. 
        In this function the variable "pi_ptr->time_for_action" is (re)set to 
        ACTION_IMMIDIATE(==0).
     
     8. The scenario for the maintenance routine and callback is like this. 
     
          A. The maintenance routine keeps monitoring the printer. 
             "if ( pi_ptr->time_for_action < gp_sof_counter )" is true, 
             the printing job processing executed.
             
          B. The printing job processing starts a transfer. 
             The printing job processing sets the "pi_ptr->time_for_action" 
             to ACTION_IDLE(==0xFFFFFFFF).
             
          C. The maintenance routine keeps monitoring the printer in the 
             timing of "wait_ms()". 
             
          D. But the printing job processing is never executed during 
             the transfer in progress. 
             
          E. After the transfer done or transfer termination by time out, 
             the callback function sets the "pi_ptr->time_for_action" to 
             ACTION_IMMIDIATE(==0).
          
          F. After next time of examining : 
             "if ( pi_ptr->time_for_action < gp_sof_counter )" in the 
             maintenance routine, the printing job processing will be 
             executed again. 
             
         
     9. In the "printer_maintenance()", there is a bandwidth control for 
        NAK retry. 
        
        If the previous transfer has done with 0 byte transfer, that means 
        printer returned NAK all time for the transfer. 
        
        When this condition is happened, printing job processing will just set 
        the "pi_ptr->time_for_action" and returns. No transfer will happen. 
        
        In this case "pi_ptr->time_for_action" is set to value of 
        "gp_sof_counter + NAK_RETRY_WAIT". 
        This will make the transfer will be retried again after NAK_RETRY_WAIT 
        (mili second). 
        
        This mechanism has been made to prevent occupying the USB band width 
        with printer's OUT-NAK transactions (Normally, the printer devices are 
        very slow). 
        
        NAK-retry sequence is done as below.
        
          A. Try transfer.
          
          B. The transfer is terminated by timeout. 
             The timeout value is set by 
               "#define InitVal_HcATLPTDDoneThresholdTimeOut" in "init.h". 
          
          C. The printing job processing will find no data transfer happend. 
             Then set "pi_ptr->time_for_action" to 
             "gp_sof_counter + NAK_RETRY_WAIT" 
             to call "printer_maintenance()" again after NAK_RETRY_WAIT. 
          
          D. The printing job processing is called again and retry the 
             transfer. 
       
        The default setting will have trying transfer for 5ms and wait retry 
        for 20ms. 
 
 
    10. In the "printer_maintenance()", the file reading size became to zero, 
        the printing job will be stopped. 
        
        Stop process is including...
           
           - Free-ing transfer slot
           
           - Free-ing data buffer
           
           - Closing file
           
           - un-install maintenance process