iic_os2.asm

i2c to os/2

;                 + directive options    ;======================
;                 + sub-directive options;                       = none
;                                        ;                      or 'ioD_'
;                                        ;                      or 'ioX_'
;                                        ;                      or 'ioC_'
;                                        ;    or 'immediate_' (targets CODE)
;                                        ;    or 'ioBuffer_'  (targets DATA)
;                                        ;
;                                        ;directive options
;                                        ;=================
;                                        ;                  =  none
;                                        ;                  or 'indirect_'
;                                        ;('indirect_' used only with 'ioD_',
;                                        ; 'ioX', or 'ioC' memory space
;                                        ; directives)
;                                        ;
;                                        ;sub-directive option
;                                        ;====================
;                                        ;                     =  none
;                                        ;                     or 'call_'
;                                        ;
;(3) number of data bytes                ;for Options 1 to 3 only
;(4) low byte address of data            ;for Options 1 to 3 only
;(5) high byte address of data           ;for Options 1 to 3 only (and only if
;                                        ;target is CODE or XDATA).
;(6) low byte of address of subroutine   ;only if 'call_' sub-directive used
;(7) high byte of address of subroutine  ;only if 'call_' sub-directive used
;
;The IIC Command File is built from 1 to any number of blocks.  Each block
;is from 2 to 7 bytes long, depending on what functions must be performmed.
;There are only four types of blocks, indicated by the options in the format
;below and breifly explained here:
;
;Option 1 = GENERAL DATA TRANSFER into DATA or XDATA space,
;++++++++++++++++++++++++++++++++ (or from DATA, XDATA or CODE space)
;++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
;         FUNCTION:  send/receive bytes to/from slave from/to any memory space
;         # BYTES IN THIS COMMAND FILE BLOCK:                                5
;         NUMBER OF BYTES TO SEND/RECEIVE:        get number from command file
;         ADDRESS FOR DATA DERIVED FROM:                          command file
;         OTHER FUNCTIONS:                                                none
;         COMMENTS: Option 1 is useful for sending or receiving any specified
;                   number of data bytes to/from the specified slave.  Every
;                   required piece of information is stored in the command
;                   file - that is, the address of the slave + read/write bit,
;                   the number of bytes to send or receive, and the address
;                   to send from or receive to.  Recall that the address space
;                   is always specified in the command file.
;
;Option 2 = 'immediate_' DIRECTIVE
;+++++++++++++++++++++++++++++++++
;         FUNCTION:                      send bytes to slave from command file
;         # BYTES IN THIS COMMAND FILE BLOCK:                                4
;         NUMBER OF BYTES TO SEND/RECEIVE:        get number from command file
;         ADDRESS FOR DATA DERIVED FROM:  data read directly from command file
;         OTHER FUNCTIONS:                                                none
;         COMMENTS: Option 2 is used to send up to 255 bytes to an addressed
;                   slave.  The bytes are fixed and are stored in the command
;                   file itself; this method reduces command file bytes since
;                   no specification for data address is necessary.  Option 2
;                   provides a simple means of setting the sub-address in IIC
;                   memory devices.
;
;Option 3 = 'ioBuffer_' DIRECTIVE
;++++++++++++++++++++++++++++++++
;         FUNCTION: send/receive bytes to/from slave from/to 'IIC_data_buffer'
;         # BYTES IN THIS COMMAND FILE BLOCK:                                3
;         NUMBER OF BYTES TO SEND/RECEIVE:        get number from command file
;         ADDRESS FOR DATA DERIVED FROM:  always targets the 'IIC_data_buffer'
;         OTHER FUNCTIONS:                                                none
;         COMMENTS: Option 3 is the data equivalent of 'immediate_'.  That is
;                   this option tells IIC_OS2 to always target the DATA space
;                   'IIC_data_buffer' for input and output.  The user must
;                   pre-load the data into the buffer for outputs.  The user
;                   must ensure that the number of data bytes specified for
;                   input must not exceed 'IIC_buffer_size_'.
;
;Option 4 = 'indirect_' DIRECTIVE
;++++++++++++++++++++++++++++++++
;         FUNCTION:  send/receive bytes to/from slave from/to any memory space
;         # BYTES IN THIS COMMAND FILE BLOCK:                                2
;         NUMBER OF BYTES TO SEND/RECEIVE:    get number from 'indirect_count'
;         ADDRESS FOR DATA DERIVED FROM:   get address from 'indirect_address'
;         OTHER FUNCTIONS:                                                none
;         COMMENTS: Option 4 assumes that the calling program has set-up the
;                   'indirect_count' register with the number of bytes to be
;                   sent or received, and the 'indirect_address' with the
;                   address of the bytes to be sent or received.  The data
;                   space targetted is specified in the command file as
;                   usual.
;
;Additionally, the 'call_' and 'use_aux_adrs_' subdirectives allow for
;additional flexibility:
;
;SUBDIRECTIVE 'call_'
;++++++++++++++++++++
;The 'call_' subdirective can be ORed with any of the memory space directives
;(the second byte of all command file blocks).  If this is done, a subroutine
;whose address is specified at the end of the command file block will be
;called once the block is completed execution.
;
;ALTERNATE ADDRESS OPTION 'use_aux_adrs_'
;++++++++++++++++++++++++++++++++++++++++
;The 'use_aux_adrs_' command is used in place of the slave address in the
;command file (the first byte of the command file block).  It tells the system
;to get the slave address from the 'aux_adrs' register.  This function is
;useful when many slave devices are communicated with in a very similar
;fashion - instead of having a separate block for each slave, each block being
;identical except for the slave address, the user could have one block and
;use the 'use_aux_adrs_' feature.
;
;To efficiently use this system, several of these blocks can be put together.
;In fact, there is no limit on the number of blocks allowed.
;This IIC_OS2 lends itself very nicely to complex IIC requirements.  The
;following examples will illustrate the usefullness of this program.
;
;EXAMPLES
;********
;The following examples are samples for each option.    The code fragment
;"PROGRAM" is simply the part of the code that sets up and calls the "DO_IIC"
;program which waits for the execution of the command file.  The
;"Optionx_file" code fragments are the code space command files.
;
;It should be noted that "IIC_OS2" will process a command file until an
;'iic_end_' character is encountered - after which, a STOP condition will be
;implemented.  This means that the master can keep possesion of the bus
;for as long as it has to.
;
;It is assumed that all the slave addresses and other EQUates have been
;defined in the program previously.
;
;EXAMPLE Option 1 - General Data Transfer
;++++++++++++++++
;PROGRAM:
;        MOV     DPTR,#Option1_file              ;load address of command file
;        CALL    DO_IIC                ;call program to wait for IIC execution
;        JBC     IIC_failure,PROGRAM            ;check for any type of failure
;        JMP     MORE_PROGRAM
;        ;
;        ;Notice the block structure of the command file.  Each block has
;        ;been spaced to accentuate this structure.
;        ;'Option1_file' tells the IIC_OS2 (called through "DO_IIC") to
;        ;read 5 bytes of data in from 'slave1' and store the bytes in the
;        ;DATA space starting at location 'd_iic_data'; after this input
;        ;is done, 'slave2' has 1 byte written to it from the XDATA space
;        ;starting at address 'x_iic_data'.  Notice that all XDATA memory
;        ;space references require 2 address bytes.
;        ;Both blocks below are option 1 types, but the first is a read
;        ;and the second is a write.
;        ;
; Option1_file:
;        DB      slave1_address OR iic_read_mask_      ;slave1 address + read bit
;        DB      ioD_                              ;indicate DATA space target
;        DB      5                                   ;indicate number of bytes
;        DB      d_iic_data                     ;start address of target bytes
;
;        DB      slave2_address OR iic_write_mask_    ;slave2 address + write bit
;        DB      ioX_                              ;indicate DATA space target
;        DB      1                                   ;indicate number of bytes
;        DB      LOW(x_iic_data)                ;start address of target bytes
;        DB      HIGH(x_iic_data)
;
;        DB      iic_end_                                  ;end of iic session
;
;MORE_PROGRAM:
;        continue with program
;
;EXAMPLE Option 2 - 'immediate_' Directive
;++++++++++++++++
;PROGRAM:
;        MOV     DPTR,#Option2_file              ;load address of command file
;        CALL    DO_IIC                ;call program to wait for IIC execution
;        JBC     IIC_failure,PROGRAM            ;check for any type of failure
;        JMP     MORE_PROGRAM
;        ;
;        ;Notice the block structure of the command file.  Each block has
;        ;been spaced to accentuate this structure.
;        ;'Option2_file' tells the IIC_OS2 (called through "DO_IIC") to
;        ;write one byte of data to the addressed slave - the data is present
;        ;in the command file.
;        ;In this example, the address for a memory location in an IIC memory
;        ;peripheral will be set and the following block does an option 1
;        ;type of input.
;        ;
;Option2_file:
;        DB      PCF8570_adrs OR iic_write_mask_    ;slave address + write bit
;        DB      immediate_                           ;send out next byte only
;        DB      1                                       ;number of data bytes
;        DB      1                                       ;data byte to be sent
;                                                     ;(end of option 2 block)
;        DB      PCF8570_adrs OR iic_read_mask_      ;slave address + read bit
;        DB      ioD_                          ;memory space where bytes go to
;        DB      6                                 ;number of bytes to be read
;        DB      iic_input_data                       ;address of input target
;
;        DB      iic_end_
;
;MORE_PROGRAM:
;        continue with program
;
;EXAMPLE Option 3 - 'ioBuffer_' Directive
;++++++++++++++++
;PROGRAM:
;        MOV     DPTR,#Option3_file              ;load address of command file
;        CALL    DO_IIC                ;call program to wait for IIC execution
;        JBC     IIC_failure,PROGRAM            ;check for any type of failure
;        JMP     MORE_PROGRAM
;        ;
;        ;Notice the block structure of the command file.  Each block has
;        ;been spaced to accentuate this structure.
;        ;'Option3_file' tells the IIC_OS2 (called through "DO_IIC") to
;        ;read 5 bytes of data in from 'slave1' and store the bytes in the
;        ;DATA space starting at location 'IIC_data_buffer'; after this input
;        ;is done, 'slave2' has 3 bytes written to it from the DATA space
;        ;starting at address 'IIC_data_buffer'.  The 'IIC_data_buffer' is
;        ;targetted because the 'ioBuffer_' directive was specified.
;        ;Both blocks below are option 1 types, but the first is a read
;        ;and the second is a write.
;        ;
; Option1_file:
;        DB      slave1_address OR iic_read_mask_       ;slave1 address + read bit
;        DB      ioBuffer_                         ;indicate 'ioBuffer' target
;        DB      5                                   ;indicate number of bytes
;
;        DB      slave2_address OR iic_write_mask_     ;slave2 address + write bit
;        DB      ioBuffer_                         ;indicate 'ioBuffer' target
;        DB      3                                   ;indicate number of bytes
;
;        DB      iic_end_                                  ;end of iic session
;
;EXAMPLE Option 4 - 'indirect_' Directive
;++++++++++++++++
;PROGRAM:
;        MOV     indirect_adrs,#LOW(input_data1)
;        MOV     indirect_adrs+1,#HIGH(input_data1)
;        MOV     indirect_count,#6
;        MOV     A,decision
;        JZ      PROGRAM_10
;        MOV     indirect_adrs,#LOW(input_data2)
;        MOV     indirect_adrs+1,#HIGH(input_data2)
;        MOV     indirect_count,#3
;
;PROGRAM_10:
;        MOV     DPTR,#Option4_file              ;load address of command file
;        CALL    DO_IIC                ;call program to wait for IIC execution
;        JBC     IIC_failure,PROGRAM_10         ;check for any type of failure
;        JMP     MORE_PROGRAM
;        ;
;        ;Notice the block structure of the command file.  Each block has
;        ;been spaced to accentuate this structure.
;        ;'Option4_file' tells the IIC_OS2 (called through "DO_IIC") to
;        ;read 'indirect_count' number of bytes into external ram space
;        ;starting at address 'indirect_adrs'.  In the body of "PROGRAM"
;        ;the 'indirect_ registers are loaded based on a decision.  In this
;        ;case, if the data byte 'decision' is zero, 6 bytes of data are
;        ;read from the slave and placed in external ram starting at the
;        ;address 'input_data1'; if 'decision' is not zero, three bytes of
;        ;data are read from the slave and placed in external ram starting
;        ;at address 'input_data2'.
;        ;
;Option4_file:
;        DB      slave_address OR iic_read_mask_        ;slave address + read bit
;        DB      ioX_ OR indirect_              ;read to external ram area and
;                                                      ;use indirect registers
;        DB      iic_end_
;
;MORE_PROGRAM: