iic_os2.asm

i2c to os/2

$Title(I2C Byte Oriented Software Driver)
$Date(10/25/94)
;
;***************************************************************************
;I2C Byte Oriented System Driver.
;Written by Joe Brandolino, Philips Semiconductors FAE
;Region 21 (Canada).
;***************************************************************************
;
;DESCRIPTION:
;============
;IIC_OS2.ASM contains a complete multi-master I2C driver for the byte
;oriented Philips microcontrollers. To date, the list of byte
;oriented 80C51 derivative microcontrollers includes:
;
;                            - 8XCL410
;                            - 8XC542
;                            - 8XCL580
;                            - 8XC652
;                            - 8XC552
;                            - 8XCL267
;                            - 8XCL268
;                            - 8XC654
;                            - 8XCE654
;                            - 8XCL781
;                            - 8XCL782
;                            - 8XCL580
;                            - 8XCL167
;                            - 8XCL168
;                            - 8XCE558
;
;The IIC Bus is a deceptively simple concept.  With only two lines involved -
;the data line (SDA) and the clock line (SCL) - one would think that writing
;a IIC driver is a trivial task.  In reality, a complete multimaster capable
;IIC driver is a complex state machine (the IIC hardware state machine
;could assume one of 28 possible states).
;
;The idea behind IIC_OS2 is to make the state machine workings of the IIC
;mechanism transparent to the user.  When this driver is incorporated into
;a program, the user communicates with IIC peripherals (and other
;masters) by executing a command file which contains simple macro directives.
;For example, to send a byte of data (stored in 'the_data') to a PCF8574 I/O
;expandor (having IIC address 'PCF8574_adrs') using this driver, the main
;program would look like this:
;
;PROGRAM:
;       MOV     DPTR,#COMMAND_FILE               ;load address of command file
;       CALL    DO_IIC                                 ;call "IIC_OS2" routine
;       JBC     IIC_failure, PROGRAM                      ;check for a failure
;               .
;               .
;               .
;COMMAND_FILE:
;       DB      PCF8574_adrs OR iic_write_mask     ;address of slave + R/W bit
;       DB      ioD_                 ;define which data space to get data from
;       DB      1                              ;define number of bytes to send
;       DB      the_data                    ;define address of data to be sent
;       DB      iic_end_                      ;'end of command file' directive
;
;This example describes one option out of many which can be used to send
;the data byte to a slave.  Without a driver like "IIC_OS2", the user would
;have to interact with the IIC SFR registers, and take into account all
;hardware state possibilities.
;
;The comments in this listing assume that the reader has a basic knowledge of
;the 80C51 family, and is familiar with IIC basics.  This program has been
;tested as thoroughly as time permitted; however, Philips cannot
;guarantee that this IIC driver is flawless in all applications.
;
;The comment text fields in this file use a consistent method of highlighting
;the various parameters of the software.  All constants (EQUates), registers,
;bits and other bytes are surrounded by ' ' in the comment text. All routines,
;labels, procedures and file names are surrounded by " " in the comment text.
;Generally speaking, all 8051 mnemonics are in UPPERCASE, all variable names
;and labels are in LOWERCASE or MiXeD case.  All EQUates are named such that
;the last character in the EQUate name is an underscore (eg. 'iic_end_').
;The terms IIC and I2C are used interchangably, and both mean
;Inter-Integrated Circuit.
;
;---NOTE---NOTE---NOTE---NOTE---NOTE---NOTE---NOTE---NOTE---NOTE---NOTE---NOTE
;
;To incorporate this program into your main program, place it somewhere in
;your source file by including the following text:
;
;         $include(mod552)      ;include the desired processor descriptor file
;         $include(IIC_OS2.asm)                          ;include this program
;
;Since this program has a 'CSEG AT... definition for the IIC interrupt vector,
;it is probably best to place it in your program where all the other interrupt
;vector directives reside so that assembly synchronisation errors do not
;occur.
;
;One must also ensure that the data bytes used by this program do not
;conflict with those in your main program.  Don't forget to initialise
;the IIC control registers and the interrupt registers, etc.  For example:
;
;INIT:        .
;             .
;             .
;        MOV     IEN0,#10100000B         ;enable IIC interrupt (and any other)
;        MOV     S1CON,#ENS1_NOTSTA_NOTSTO_NOTSI_AA_CR0
;        MOV     S1ADR,#Own_adrs OR general_enable_ ;enable slave/general mode
;        MOV     IIC_status,#status_OK_               ;init system status byte
;        CLR     IIC_failure                                  ;init status bit
;             .
;             .
;             .
;
;This driver uses DATA space bytes (approx. 16 bytes), plus several buffers
;which are required only for multi-master scenarios where this micro can be
;addressed as a slave. One bit addressable byte is  used.
;The user must ensure the following EQUates are set appropriately for his
;system:
;
;Slave address for this microcontroller - other bus masters can address this
;micro as a slave; this driver simply sends 'SLVbytes_out_' number of bytes or
;receives 'SLVbytes_in_' number of bytes in the case of being addressed as a
;slave.  The LSBit of the address ('Own_adrs_') is set indicating that general
;calls will be responded to.
;
Own_adrs_         EQU     02EH    ;address of micro when addressed as a slave
general_enable_   EQU     1       ;general call recognised since LSBit is set
SLVbytes_in_      EQU     4     ;# bytes to receive when addressed as a slave
SLVbytes_out_     EQU     4         ;# bytes to transmit when    "     "    "
IIC_buffer_size_  EQU     20           ;# bytes reserved for 'IIC_data_buffer'
;
;Change the following equates to suit your system - they define where the
;start of DATA and BIT ADDRESSABLE DATA for the required bytes in "IIC_OS2".
;
IIC_OS2_DATA             EQU     48       ;change location to suit your system
IIC_OS2_BITADRS_DATA     EQU     32                           ;bit addressable!
;
;
;To interface to this IIC driver, the user need not understand all the details
;of the program - only the following registers must be understood:
;
;       'IIC_data_buffer'                - used with the 'ioBuffer_' command
;       'Slave_in' buffer (if required)  - used only in multi-master systems
;       'Slave_out' buffer (if required) - used only in multi-master systems
;       'aux_adrs'                       - used with 'use_aux_adrs_' command
;       'indirect_adrs'                  - used with the 'indirect_' command
;       'indirect_count'                 - used with the 'indirect_' command
;       'IIC_failure' (BIT)              - set if command file was kaput
;       'IIC_final_status'               - holds the final status of session
;
;Additionally, there is a command file structure (the command file is a
;list of commands that "IIC_OS2" will execute) which the user must conform to.
;The list of command file directives includes:
;
;       'ioD_'          - target DATA space for data transfers
;       'ioC_'          - target CODE space for data transfers
;       'ioX_'          - target XDATA space for data transfers
;       'ioBuffer_'     - target 'IIC_data_buffer' for data transfers
;       'immediate_'    - used to output bytes from command file stream
;       'call_'         - used to call a subroutine between reapeated starts
;       'indirect_'     - gets I/O address and count from 'indirect_ registers
;       'use_aux_adrs_' - gets slave address from 'aux_adrs'
;
;       'iic_end_'      - last byte of a command file
;     'iic_write_mask_' - OR with slave address to indicate a write operation
;     'iic_read_mask_'  - OR with slave address to indicate a read operation
;
;The command file structure is explained in detail below.
;
;---NOTE---NOTE---NOTE---NOTE---NOTE---NOTE---NOTE---NOTE---NOTE---NOTE---NOTE
;
;Multi-master systems are very specific to the system design, and therefore,
;very difficult to make generic.  Every multi-master system will have a
;different protocol for how many (and which) bytes to send/receive when the
;master is addressed as a Slave Receiver or Slave Transmitter.  For this
;reason, this program implements the multi-master scenario very simply -
;if the micro running this program is addressed as a slave, it will read up to
;'SLVbytes_in_' number of data bytes into the 'Slave_in' buffer or send
;'SLVbytes_out_' number of data bytes from the 'Slave_out' buffer (depending
;on what the calling master requests).
;
;This program also treats the general call scenario as a Slave Receiver mode.
;If the general call is received, and the 'S1ADRS' has been set to accept the
;general call, up to eight bytes can be received into the 'Slave_in' buffer.
;The IIC specification has defined how the general call should be handled,
;and the user can write his own code to conform to this specification, or
;simply use the general call as a means of sending common information to all
;the masters on the bus which use this driver.  Since the bytes sent from the
;general call master to the other masters which use this driver end up in the
;'Slave_in' buffer (and the 'IIC_status' is set to indicate a general call
;scenario), the user can write code in his mainline routine to conform to the
;IIC specification if he wishes.
;
;The user can make the size of these slave input/output buffers (by altering
;the corresponding equates 'SLVbytes_in_' and 'SLVbytes_out_') as large as
;required.  The calling Master can terminate the slave session at any number
;of data bytes sent or received by providing a stop or a not acknowledge.
;
;IIC_OS2, when integrated into the user's system, will require 16 DATA bytes
;(mapped anywhere in the internal DATA memory space), and one bit-addressable
;byte.  About 650 bytes of code-space memory are used.
;
;The user of this program need not concern himself with the bit or byte level
;operation of the IIC harware - this program takes care of all IIC registers,
;and checks for all collisions, arbitration lost scenarios, buss errors, etc.
;A command list consistiing of a limited number of simple macro commands is
;set-up by the user, and this driver uses that list of commands to perform
;the desired IIC operations.
;
;The user loads the DPTR register with the address of the sequence of IIC
;operations desired.  Once this register is loaded, the "DO_IIC"  routine
;is called.  "DO_IIC" starts the IIC process by forcing a START condition
;from which point the interrupt service routine "IIC_VECTOR" will execute
;the command file and interact with the IIC SFRs.  "DO_IIC" acts as a
;timeout watchdog while the command file is running.  Once the command file
;is completely executed, "DO_IIC" will return to the calling routine with
;the 'IIC_failure' bit and 'IIC_final_status' byte set according to the
;results of the command file execution.  The 'IIC_failure' bit will be set
;if an error occurs so the calling program could try again or interrogate the
;'IIC_final_status' byte to determine exactly what kind of error took place.
;
;The IIC operations to be performmed are stored sequentially starting at the
;address specified by the DPTR ('IIC_Command_File_adrs') and in the memory
;space designated by 'Data?adrs?space'.  IIC operations include:
;
;          1) sending or receiving any number of bytes from 1 to 255
;             into any valid address space
;          2) repeated start automatically performmed so multiple
;             slaves can be communicated with in one call
;          3) call subroutines between repeated start conditions directly
;             from the IIC command file list (i.e. transparent to the
;             calling routine).
;
;The IIC Command File must be constructed so that it conforms to the IIC
;driver system format.  This format is very simple and can be pictorially
;viewed as:
;
;         COMMAND_FILE:
;                       --------------------
;                       | Command Block 1  |
;                       |                  |
;                       --------------------
;                                |
;                       --------------------
;                       | Command Block 2  |
;                       |                  |
;                       --------------------
;                                |
;                                |
;                                |
;                       --------------------
;                       | Command Block N  |
;                       |                  |
;                       --------------------
;                      -----------------------
;                      | 'iic_end_' directive| ;last directive in command file
;                      -----------------------
;
;Each Command Block consists of the following bytes:
;(note '+' means logical OR)
;
;(1) slave address + direction mask      ;slave address
;                                        ;=============
;                                        ;              = hex number
;                                        ;        or 'use_aux_adrs_' directive
;                                        ;
;                                        ;direction mask
;                                        ;==============
;                                        ;              = 'iic_read_mask_'
;                                        ;             or 'iic_write_mask_'
;                                        ;
;(2) memory space directive              ;memory space directive