www.beck-ipc.com

Hardware API - SC12 @CHIP-RTOS V1.10


    IPC@CHIP Documentation Index          Hardware API News

Hardware API

Here are the interface definitions for access to the IPC@CHIP's hardware.

Topics

API Functions

The hardware API uses interrupts 0xA2 (PFE functions) and 0xA1 (HAL functions) with a service number in the high order byte of the AX register (AH).   The implemented hardware services are listed below.

For some useful comments see also under Programming notes

  • Interrupt_0xA2_function_0x80:_PFE: Enable Data Bus
  • Interrupt_0xA2_function_0x81:_PFE: Enable Non-Multiplexed Address Bus
  • Interrupt_0xA2_function_0x82:_PFE: Enable Programmable I/O Pins
  • Interrupt_0xA2_function_0x83:_PFE: Enable Programmable Chip Selects
  • Interrupt_0xA2_function_0x84:_PFE: Enable External Interrupt Requests
  • Interrupt_0xA2_function_0x85:_PFE: Enable External Timer Inputs/Outputs
  • Interrupt_0xA2_function_0x86:_PFE: Set Edge/Level Interrupt Mode
  • Interrupt_0xA2_function_0x87:_PFE: Enable PWD Mode
  • Interrupt_0xA2_function_0x88:_PFE: Enable External DMA
  • Interrupt_0xA2_function_0x89:_PFE: Enable INT0 / INTA cascade mode
  • Interrupt_0xA2_function_0x8A:_PFE: Set wait states for PCS0-3
  • Interrupt_0xA2_function_0x90:_PFE: Get Hardware API Function Pointers
  • Interrupt_0xA1_function_0x10:_HAL: Set int0 Vector
  • Interrupt_0xA1_function_0x80:_HAL: Read Data Bus
  • Interrupt_0xA1_function_0x81:_HAL: Write Data Bus
  • Interrupt_0xA1_function_0x82:_HAL: Read Programmable I/O Pins
  • Interrupt_0xA1_function_0x83:_HAL: Write Programmable I/O Pins
  • Interrupt_0xA1_function_0x84:_HAL: Install Interrupt Service Routine
  • Interrupt_0xA1_function_0x85:_HAL: Initialize Timer Settings
  • Interrupt_0xA1_function_0x86:_HAL: Start Timer
  • Interrupt_0xA1_function_0x87:_HAL: Stop timer
  • Interrupt_0xA1_function_0x88:_HAL: Read Timer Count
  • Interrupt_0xA1_function_0x89:_HAL: Write Timer Count
  • Interrupt_0xA1_function_0x8A:_HAL: Get Frequencies
  • Interrupt_0xA1_function_0x8B:_HAL: Set Timer Duty Cycle Waveform
  • Interrupt_0xA1_function_0x8C:_HAL: Read Specific I/O Pin
  • Interrupt_0xA1_function_0x8D:_HAL: Write to Specific I/O Pin
  • Interrupt_0xA1_function_0x8E:_HAL: Give EOI
  • Interrupt_0xA1_function_0x8F:_HAL: Initialize Timer Settings Ext
  • Interrupt_0xA1_function_0x90:_HAL: Get/Set Watchdog Mode
  • Interrupt_0xA1_function_0x91:_HAL: Refresh Watchdog
  • Interrupt_0xA1_function_0x92:_HAL: Mask/Unmask Int
  • Interrupt_0xA1_function_0xA0:_HAL: Block Read Data Bus
  • Interrupt_0xA1_function_0xA1:_HAL: Block Write Data Bus
  • Interrupt_0xA1_function_0xB0:_HAL: Start DMA Mode
  • Interrupt_0xA1_function_0xB1:_HAL: Stop DMA Transfer
  • Interrupt_0xA1_function_0xB2:_HAL: Get DMA Info
  • Interrupt_0xA1_function_0xC0:_HAL: Initialize/Restore Non-Volatile Data
  • Interrupt_0xA1_function_0xC1:_HAL: Save Non-Volatile Data
  • Interrupt_0xA1_function_0xC2:_HAL: Get Reboot Reason

  • Interrupt 0xA2 service 0x80: PFE: Enable Data Bus

    Initialize data bus I/O mask and ALE usage.

    Parameters

    AH
    Must be 0x80.

    AL
    0: Disable ALE,   1: Enable ALE

    DX
    Mask
      Bit 0 = 0: Data bus bit 0 is input, 1: is output
      Bit 1 = 0: Data bus bit 1 is input, 1: is output
      :
      :
      Bit 7 = 0: Data bus bit 7 is input, 1: is output
      Bit 8..15 not used (for future extensions)

    Return Value

    none

    Comments

    The I/O mask defines which data bits on the bus are inputs and which are outputs.   The DX mask bit for bi-directional data bus lines (read/write) should be set to '1'.

    used pins:
        ALE, AD[0..7], RD#, WR#
    excluded pins:
        if ALE is used, then PCS0# is not available.


    Top of list
    Index page

    Interrupt 0xA2 service 0x81: PFE: Enable Non-Multiplexed Address Bus

    The IPC@CHIP has three non-multiplexed address bit outputs, A0 through A2.   The enabling of these pins is done here.

    Parameters

    AH
    Must be 0x81.

    DX
    Mask
        Bit 0 = 1 Enable A0
        Bit 1 = 1 Enable A1
        Bit 2 = 1 Enable A2
        Bit 3..15 not used

    Return Value

    none

    Comments

    used pins:
        A[0..2], AD[0..7], RD#, WR#
    excluded pins:
        If A0 is enabled then PCS1#, TMRIN0, PIO4 are not available
        If A1 is enabled then PCS[5..6]#, TMRIN1, TMROUT1, PIO3 are not available
        If A2 is enabled then PCS[5..6]#, PIO2 are not available.


    Top of list
    Index page

    Interrupt 0xA2 service 0x82: PFE: Enable Programmable I/O Pins

    Enable used programmable I/O pins.   Define which pins are inputs and which are outputs.

    Parameters

    AH
    Must be 0x82.

    AL
    Mode
      0 = Only read PIO state
      1 = Input without pullup/pulldown
      2 = Input with pullup (not PIO13)
      3 = Input with pulldown (only for PIO3 and PIO13)
      4 = Output init value = High
      5 = Output init value = Low

    DX
    PIO pin
      Bit 0 = 1 Enable PIO0
      Bit 1 = 1 Enable PIO1
      :
      :
      Bit 13 = 1 Enable PIO13
      Bit 14..15 not used (for future extensions)

    Return Value

    AX = wPIO
      Bit 0 = 1: PIO0 is PIO
      Bit 1 = 1: PIO1 is PIO
      :
      :
      Bit 13 = 1: PIO13 is PIO
      Bit 14..15 not used (for future extensions)
    DX = wINPUTS (all pins, including non-PIO pins)
      Bit 0 = 1: PIO0 is input
      Bit 1 = 1: PIO1 is input
      :
      :
      Bit 13 = 1: PIO13 is input
      Bit 14..15 not used (for future extensions)
    CX = wOUTPUTS (all pins, including non-PIO pins)
      Bit 0 = 1: PIO0 is output
      Bit 1 = 1: PIO1 is output
      :
      :
      Bit 13 = 0: PIO13 is output
      Bit 14..15 not used (for future extensions)
    AX = DX = CX = 0, Error: Wrong arguments

    Comments

    This function can be called several times for definition of different PIO pins.   With repeated selection of the same pin, the definition made last is valid.   The selection of a PIO pin can be cancelled by calling the appropriate PFE function that causes the respective PIO pin to be used for another purpose (e.g. function 0x83 for PIO[2..6] pins).

    used pins:
        PIO[0..13]
    excluded pins:
        All other functionality on the selected PIO pin.

    Related Topics

    Read Specific I/O Pin
    Write to Specific I/O Pin
    Read Programmable I/O Pins
    Write Programmable I/O Pins
    Initialize the I2C Bus

    Top of list
    Index page

    Interrupt 0xA2 service 0x83: PFE: Enable Programmable Chip Selects

    Enable chip selects PCS[0..3]#, PCS[5..6]#.

    Parameters

    AH
    Must be 0x83.

    DX
    Mask
        Bit 0 = 1 Enable PCS0#, active when I/O address between 000h..0FFh
        Bit 1 = 1 Enable PCS1#, active when I/O address between 100h..1FFh
        Bit 2 = 1 Enable PCS2#, active when I/O address between 200h..2FFh
        Bit 3 = 1 Enable PCS3#, active when I/O address between 300h..3FFh
        Bit 4 = don't care
        Bit 5 = 1 Enable PCS5#, active when I/O address between 500h..5FFh
        Bit 6 = 1 Enable PCS6#, active when I/O address between 600h..6FFh
        Bit 7..15 = don't care

    Return Value

    none

    Comments

    used pins:
        PCS[0..3]#, PCS[5..6]#
    excluded pins:
        if PCS0#: ALE (multiplexed address / data bus)
        if PCS1#: A0, PIO4, TMRIN0
        if PCS2#: PIO6, INT2, INTA#, PWD, hw flow control serial port 1,
            cascaded interrupt controller
        if PCS3#: PIO5, INT4, hw flow control serial port 1
        if PCS5#: A[1..2], PIO3, TMROUT1, TMRIN1
        if PCS6#: A[1..2], PIO2


    Top of list
    Index page

    Interrupt 0xA2 service 0x84: PFE: Enable External Interrupt Requests

    Enable external interrupt requests INT[0], INT[2..6].

    Parameters

    AH
    Must be 0x84.

    DX
    Mask
        Bit 0 = 1 Enable INT0
        Bit 1 = don't care
        Bit 2 = 1 Enable INT2
        Bit 3 = 1 Enable INT3
        Bit 4 = 1 Enable INT4
        Bit 5 = 1 Enable INT5
        Bit 6 = 1 Enable INT6
        Bit 7..15 = don't care

    Return Value

    none

    Comments

    used pins:
        INT0, INT[2..6]
    excluded pins:
        if INT0: PIO13, TMROUT0, cascaded interrupt controller
        if INT2: PIO6, PCS2#, INTA#, PWD, hw flow control serial port 1
        if INT3: PIO12, serial port 1
        if INT4: PIO5, PCS3#, hw flow control serial port 1
        if INT5: PIO1, DRQ0, default I²C-Bus pins
        if INT6: PIO0, DRQ1, default I²C-Bus pins

    Related Topics

    Set Edge/Level Interrupt Mode

    Top of list
    Index page

    Interrupt 0xA2 service 0x85: PFE: Enable External Timer Inputs/Outputs

    Enable external timer inputs (TMRIN0, TMRIN1) or timer outputs (TMROUT0, TMROUT1).

    Parameters

    AH
    Must be 0x85.

    DX
    Mode
      Bit 0..1 = 10 Enable TMRIN0
               = 11 Enable TMROUT0
      Bit 2..3 = 10 Enable TMRIN1
               = 11 Enable TMROUT1
      Bit 4..15 = don't care

    Return Value

    none

    Comments

    If on a given timer the external input is selected, then that timer's external output is not available and vice-versa.

    used pins:
      TMRIN[0..1], TMROUT[0..1]
    excluded pins:
      if TMRIN0:   A0, PCS1#, PIO4, TMROUT0
      if TMRIN1:   A[1..2], PCS5#, TMROUT1
      if TMROUT0:   PIO13, INT0, cascaded interrupt controller, TMRIN0
      if TMROUT1:   A[1..2], PCS5#, TMRIN1, PIO3

    Related Topics

    HAL Initialize Timer Settings

    Top of list
    Index page

    Interrupt 0xA2 service 0x86: PFE: Set Edge/Level Interrupt Mode

    Set edge/level interrupt mode for INT0, INT2, INT3, INT4.

    Parameters

    AH
    Must be 0x86.

    AL
    1 = active high, level-sensitive interrupt
    0 = low-to-high, edge-triggered interrupt

    DX
    Mask, bits set to designate interrupts affected:
      Bit 0 = INT0
      Bit 1 = don't care
      Bit 2 = INT2
      Bit 3 = INT3
      Bit 4 = INT4
      Bit 5..15 = don't care

    Return Value

    none

    Comments

    Default for all interrupts is edge-triggered mode.   In each case (edge or level) the interrupt pins must remain high until they are acknowledged.

    Level-sensitive mode for INT5 / INT6 is not supported.  The INT5 / INT6 interrupts operate only in edge-triggered mode.

    Related Topics

    Enable External Interrupt Requests

    Top of list
    Index page

    Interrupt 0xA2 service 0x87: PFE: Enable PWD Mode

    Enable Pulse Width Demodulation (PWD)

    Parameters

    AH
    Must be 0x87.

    Return Value

    none

    Comments

    In PWD mode, TMRIN0, TMRIN1, INT2 and INT4 are configured internal to the
    chip to support the detection of rising (INT2) and falling (INT4) edges on the PWD
    input pin and to enable either timer0 when the signal is high or timer1 when
    the signal is low.   The INT4, TMRIN0 and TMRIN1 pins are not used in PWD mode
    and so are available for use as PIO's.

    The ISR for the INT2 and the INT4 interrupts should examine the current count of
    the associated timer, timer1 for INT2 and timer0 for INT4, in order to determine
    the pulse width.   The ISR should then reset the timer count in preparation for the
    next pulse.

    Overflow conditions, where the pulse width is greater than the maximum count of the
    timer, can be detected by monitoring the MaxCount bit in the associated timer or by
    setting the timer to generated interrupt requests.

    used pins:
        PWD
    excluded pins:
        TMRIN0, TMRIN1, TMROUT0, TMROUT1, INT4, INT2
        PCS2#, INTA#, PIO6, hw flow control serial port 1


    Top of list
    Index page

    Interrupt 0xA2 service 0x88: PFE: Enable External DMA

    Enables DRQ pin to start DMA transfer

    Parameters

    AH
    Must be 0x88.

    AL
    DRQ channel:
    0 = DRQ0
    1 = DRQ1

    Return Value

    AX = 0 no error
    AX = -1 invalid DRQ channel
    AX = -2 DMA channel is used for serial interface

    Comments

    You must disable the serial port DMA mode to use external DMA.   This is done with a CHIP.INI entry.   The COM port uses DRQ1 and the EXT port uses DRQ0.

    used pins:
        DRQ[0..1]
    excluded pins:
        if DRQ0: PIO1, INT5, default I²C-Bus pins
        if DRQ1: PIO0, INT6, default I²C-Bus pins


    Top of list
    Index page

    Interrupt 0xA2 service 0x89: PFE: Enable INT0 / INTA cascade mode

    Enable INT0 / INTA cascade mode

    Parameters

    AH
    Must be 0x89.

    Return Value

    none

    Comments

    To install a service interrupt routine in cascade mode, the
    HAL function 0x84 "Install Interrupt Service Routine" can not be used, because
    the cascaded interrupt controller supply the interrupt type over the bus.
    Install a normal interrupt service routine (ISR) using the setvect function.
    At the end of your ISR, issue an EOI to both the cascaded controller and to
    the internal interrupt controller (INT0).

    used pins:
        INT0, INTA#
    excluded pins:
        PIO13, TMROUT0, INT0 in normal mode, PIO6, PCS2#, PWD, hw flow control serial port 1

    Related Topics

    HAL 0x8E Give EOI

    Top of list
    Index page

    Interrupt 0xA2 service 0x8A: PFE: Set wait states for PCS0-3

    Set wait states for programmable chip selects PCS0#-PCS3#

    Parameters

    AH
    Must be 0x8A.

    AL
    Bit 0-3
      0000b = 0 wait states
      0001b = 1 wait states
      0010b = 2 wait states
      0011b = 3 wait states
      1000b = 5 wait states
      1001b = 7 wait states
      1010b = 9 wait states
      1011b = 15 wait states
    Bit 4-7
      don't care

    Return Value

    none

    Comments

    Default for PCS0#-PCS3# are 15 wait states.  

    Related Topics

    Enable programmable chip selects

    Top of list
    Index page

    Interrupt 0xA2 service 0x90: PFE: Get Hardware API Function Pointers

    Get the Function Pointers to Hardware API Functions, so that the functions can be called directly (without Software Interrupt).   This is much faster.

    Parameters

    AH
    Must be 0x90.

    ES:DI
    Pointer to a HwApiFunctionStruct data structure which will be filled with vectors to @CHIP-RTOS Hardware API Functions.

    Return Value

    AX= -1 if size parameter was too large.   The size field of the structure will be set in this case to the number of supported vectors.

    AX= 0 on success

    Comments

    Note that the size member of the HwApiFunctionStruct serves as both an input and output parameter.   The caller must set this value to the number of vectors to be filled into the data structure by this API call.   In the event that this value exceeds the number of vectors available, the AX value returned will be -1 and this API will set the size to 2, which is the number of vectors available by this API's current implementation.

    In any case, the resulting count in size indicates the number of vectors output to the caller's HwApiFunctionStruct data structure at [ES:DI] by this API call.

                
    typedef struct
    
    {
    
       int size; // number of function entries
    
       unsigned  (huge *readPios)(void);
    
       void      (huge *writePios)(unsigned);
    
    } HwApiFunctionStruct;
    
    
    
    // Example for usage:
    
    
    
    int main()
    
    {
    
      HwApiFunctionStruct hwApi;
    
      unsigned            pios;
    
    
    
      [...]
    
      hwApi.size = 2;          // space for two functions in the struct
    
    
      pfe_get_hwapi_func_ptr(&hwApi);
    
    
    
      hwApi.writePios(0x55);   // write something to the pios
    
      pios = hwApi.readPios(); // read something from the pios
    
      [...]
    
    }


    Top of list
    Index page

    Interrupt 0xA1 service 0x10: HAL: Set int0 Vector

    Define the interrupt handler for the hardware interrupt 0

    Parameters

    AH
    Must be 0x10

    ES:DX
    Pointer to your interrupt handler

    Return Value

    none

    Comments

    The interrupt handler should be defined as
      void interrupt my_handler(void)

    Interrupts are enabled upon entry into your routine.

    There is no need to signal any end of interrupt.   This is handled by the system after your handler performs it's return.

    The stack size must be at least 400 bytes.

    Do not use any floating point arithmetic in your interrupt service routine.


    Developer Notes

    This function is only for compatibility to older version of the hardware API.
    Please use interrupt 0xA2 function 0x84 and interrupt 0xA1 function 0x84 instead.


    Top of list
    Index page


    Interrupt 0xA1 service 0x80: HAL: Read Data Bus

    Read from specified address.

    Parameters

    AH
    Must be 0x80.

    DI
    Address

    BX
    wAND

    CX
    wXOR

    Return Value

    8 Bit data in ax, ax = (databus & wAND) ^ wXOR

    Comments

    & = bit wise AND
    ^ = bit wise XOR

    The result is combined with wAND and wXOR parameters.   To read the data bus without change, set wAND=0xFFFF and wXOR=0x0000.

    Related Topics

    Block Read Data Bus
    Write Data Bus

    Top of list
    Index page

    Interrupt 0xA1 service 0x81: HAL: Write Data Bus

    Write to specified address.

    Parameters

    AH
    Must be 0x81.

    DI
    Address

    DL
    8 bit data

    BX
    wAND

    CX
    wXOR

    Return Value

    none

    Comments

    & = bit wise AND
    ^ = bit wise XOR

    The provided parameters are combined as follows to form the output byte value:
      output value = (data & wAND) ^ wXOR

    To write the value in DL to the address without modification, set wAND=0xFFFF and wXOR=0x0000.

    Related Topics

    Block Write Data Bus
    Read Data Bus

    Top of list
    Index page

    Interrupt 0xA1 service 0x82: HAL: Read Programmable I/O Pins

    Read the programmable I/O pins.

    Parameters

    AH
    Must be 0x82.

    BX
    wAND

    CX
    wXOR

    Return Value

    ax = (PIO[0..13] & wAND) ^ wXOR.

    Comments

    & = bit wise AND
    ^ = bit wise XOR

    The result is combined with the wAND and wXOR parameters.   To read the PIO pins without modification, set wAND=0xFFFF and wXOR=0x0000.   To read only the input pins, set wAND = wPIO & wINPUTS.   The wPIO and wINPUTS values are return values from PFE function 0x82.

    Related Topics

    Read Specific I/O Pin
    Write Programmable I/O Pins
    PFE: Enable Programmable I/O Pins

    Top of list
    Index page

    Interrupt 0xA1 service 0x83: HAL: Write Programmable I/O Pins

    Write to the programmable I/O pins.

    Parameters

    AH
    Must be 0x83.

    DX
    data applied to PIO[0..13]
      where DX bit 0 maps to PIO[0]
      and DX bit 13 maps to PIO[13]

    BX
    wAND

    CX
    wXOR

    Return Value

    none

    Comments

    & = bit wise AND
    ^ = bit wise XOR

    Before the value is written, the value is combined with the wAND and wXOR parameters as:
      PIO[0..13] = (data & wAND) ^ wXOR

    To write value in DX to the programmable I/O pins without change, set wAND=0xFFFF and wXOR=0x0000.

    Only PIO pins that are defined as outputs can be written.

    Related Topics

    Write Specific I/O Pin
    Read Programmable I/O Pins
    PFE: Enable Programmable I/O Pins

    Top of list
    Index page

    Interrupt 0xA1 service 0x84: HAL: Install Interrupt Service Routine

    Install user interrupt service routine to be invoked by system interrupt handler.

    Parameters

    AH
    Must be 0x84.

    DH
    Bit mask for the ISR type:
      BIT0..6 must be 0
      BIT7: 0=normal ISR, 1=RTX ISR (RTX ISR allow RTX Calls, e.g. wake a task), please notice the comment below!

    DL
    HAL interrupt number from following list:
      0 = INT0 (external)
      1 = Network controller (internal) (*)
      2 = INT2 (external)
      3 = INT3 (external)
      4 = INT4 (external)
      5 = INT5 (external) / DMA Interrupt Channel 0 (if DMA is used)
      6 = INT6 (external) / DMA Interrupt Channel 1 (if DMA is used)
      7 = reserved
      8 = Timer0 (internal)
      9 = Timer1 (internal)
      10 = Timer 1ms (internal) (*)
      11 = Serial port 0 (internal)(*)
      12 = Serial port 1 (internal)(*)
      13 = reserved
      14 = reserved
      15 = NMI (internal/external)
      (* = internal used by @CHIP-RTOS, not available for user interrupt service functions)


    CX
    Number of interrupts generated before new user interrupt service routine is called.
    CX = 0 disables the user ISR (same as a NULL in ES:BX).

    ES:BX
    far pointer to user interrupt service routine
        if pointer is NULL user ISR is disabled

    Return Value

    Far pointer to old handler in ES:BX

    Comments

    The user-defined ISR is called from a system ISR with the interrupt identifier number in the BX CPU register, thus allowing for a single user ISR to handle multiple interrupt sources.   The user ISR can be declared in either of the following forms:

      void huge My_ISR(void) ;     // More efficient form

      void interrupt My_ISR(void) ;     // Tolerated form

    The more efficient huge procedures are recommended.   For assembly language ISR implementations, a far RET is recommended and a IRET on exit is tolerated.   The user ISR function must preserve only the DS and BP registers, so there is no requirement for the full register save/restore provided by the interrupt declarations.

    Any required EOI signal is issued by the system ISR which calls your user ISR function.  This EOI is issued after your function returns.

    If you install a RTX ISR you can use the following RTX calls in your ISR:


    Important Notes:
    A RTX ISR is slower than a normal ISR.   RTX ISR are not recommended for INT5 or INT6 if DMA is used by the Fossil serial ports interface, because the slower RTX ISR could result in UART receiver character loss.  

    If you are using a RTX ISR for timer0, timer1, INT5 or INT6 there must not exist a normal ISR on the system which enables the interrupts during its execution! Do not install a RTX ISR for NMI.!

    Also important :   The NMI function of the multifunction pin 17 (RESET/NMI/LINK_LED) of the IPC@CHIP SC11/SC12/SC13 is for power fail purposes only.   It is not possible to use NMI as a "normal" interrupt pin like INT0 for generating interrupts.   It can only be used as described in the IPC@CHIP hardware documentation.


    Top of list
    Index page

    Interrupt 0xA1 service 0x85: HAL: Initialize Timer Settings

    Initialize the timer settings of timer0 or timer1.

    Parameters

    AH
    Must be 0x85.

    AL
    Timer
        0=Timer0 / 1=Timer1

    DX
    Mode
        Bit 0: 0=run single time / 1=run continuous
        Bit 1: 0=disable timer interrupt / 1=enable timer interrupt
        Bit 2: 0=use internal clock / 1=use TMRIN pin as external clock
        Bit 3..15: not used

    CX
    Clock divider (maximum count value)

    Return Value

    none

    Comments

    The clock divider value serves as a comparator for the associated timer count.   The timer count is a 16 bit value that is incremented by the processor internal clock (see HAL function 0x8A) or can also be configured to increment based on the TMRIN0 or TMRIN1 external signals (see PFE function 0x85).   The TMROUT0 und TMROUT1 signals can be used to generate waveforms of various duty cycles.   The default is a 50% duty cycle waveform   (Change waveform with HAL function 0x8B).

    Note that TMRIN pin and TMROUT pin can not be used at the same time.

    If the clock divider value is set to 0000h, the timer will count from 0000h to FFFFh (maximum divider).   When the timer reaches the clock divider value, it resets to 0 during the same clock cycle.   The timer count never dwells equals to the clock divider value (except for special case when divider value is set to 0000h).

    When the timer is configured to run in single time mode, the timer clears the count and then halts on reaching the maximum count (clock divider value).

    If the timer interrupt is enabled, the interrupt request is generated when the count equals the clock divider value.   Use HAL function 0x84 to install your interrupt service routine.

    If "use internal clock" is selected the associated TMRIN pin serves as a gate.   A "high" on the TMRIN pin keeps the timer counting.   A "low" holds the timer value.

    Related Topics

    Initialize Timer Settings Ext
    HAL Start Timer function
    Read Timer Count
    Write Timer Count


    Developer Notes

    The timer output frequency is dependent on the internal processor clock.
    For compatibility with future versions of @Chip, please use the HAL function 0x8A, "Get frequencies", to compute the correct clock divider value.

    Available examples
        1. TimerIn example, timerin.c
        2. TimerOut example, timerout.c


    Top of list
    Index page


    Interrupt 0xA1 service 0x86: HAL: Start Timer

    Enable the specified timer to count.

    Parameters

    AH
    Must be 0x86.

    AL
    Timer
        0=Timer0 / 1=Timer1

    Return Value

    none

    Related Topics

    HAL Initialize Timer Settings
    Stop Timer function

    Top of list
    Index page

    Interrupt 0xA1 service 0x87: HAL: Stop timer

    Stop the specified timer's counting

    Parameters

    AH
    Must be 0x87.

    AL
    Timer
        0=Timer0 / 1=Timer1

    Return Value

    none

    Comments

    The specified timer is disabled.

    Related Topics

    Start Timer function

    Top of list
    Index page

    Interrupt 0xA1 service 0x88: HAL: Read Timer Count

    Read the timer count.

    Parameters

    AH
    Must be 0x88.

    AL
    Timer
        0=Timer0 / 1=Timer1

    Return Value

    AX = Counter reading
    DX = 1=MaxCount reached / 0=MaxCount not reached

    Comments

    AX contains the current count of the associated timer.   The count is incremented by the processor internal clock (see HAL function 0x8A), unless the timer is configured for external clocking (then it is clocked by the TMRIN0 and TMRIN1 signals).

    Related Topics

    HAL Initialize Timer Settings
    Stop Timer function
    Write Timer Count

    Top of list
    Index page

    Interrupt 0xA1 service 0x89: HAL: Write Timer Count

    Preset the specified timer's count register to provided value.

    Parameters

    AH
    Must be 0x89.

    AL
    Timer
        0=Timer0 / 1=Timer1

    DX
    Value to write to 16 bit counter

    Return Value

    none

    Comments

    The timer count can be written at any time, regardless of whether the corresponding timer is running.

    Related Topics

    HAL Initialize Timer Settings
    Stop Timer function
    Read Timer Count

    Top of list
    Index page

    Interrupt 0xA1 service 0x8A: HAL: Get Frequencies

    Get the system frequencies.

    Parameters

    AH
    Must be 0x8A.

    AL
    Which frequency to get:
      0 = Return processor frequency
      1 = Return timer base frequency
      2 = Return maximum baud rate
      3 = Return PWD timer frequency

    Return Value

    DX:AX frequency [Hz]

    Comments

    Use the timer base frequency to compute the correct timer clock divider value, where:

      Output frequency = timer base frequency / clock divider

    Use the maximum baud rate compute the correct baud rate for the processor specific baud rate initialize function (See Fossil Extended line control initialization function).

      Baud rate = maximum baud rate / baud rate divider

    Related Topics

    HAL Initialize Timer Settings

    Top of list
    Index page

    Interrupt 0xA1 service 0x8B: HAL: Set Timer Duty Cycle Waveform

    Set the duty cycle waveform of specified timer.

    Parameters

    AH
    Must be 0x8B.

    AL
    Which Timer
        0=Timer0 / 1=Timer 1

    DX
    Mode
        0=disable duty cycle / 1=enable duty cycle

    CX
    Alternate clock divider (if DX = 1)

    Return Value

    none

    Comments

    Use this function to modify the timer waveform behavior.   For example a 50% duty cycle waveform can be generated by specifying here an alternate clock divider value in CX that is the same value as was used for the main clock divider value set in the Timer Initialization function call.

    Please note that the timer frequency will change if you use this function.   If you disable the duty cycle, the timer output will no longer generate a rectangle signal.   When duty cycle mode is disabled, the TMROUT pin switches low for only one clock cycle after the maximum count is reached.   If you want an alternate duty cycle waveform, compute it with the following formula:

    Output frequency = Timer base frequency * 2
                / (divider high level + divider low level)


    The divider high level is the divider set by the Timer Initialization function.   The divider low level is the alternate clock divider passed to this function in the CX register.

    Related Topics

    HAL Initialize Timer Settings

    Top of list
    Index page

    Interrupt 0xA1 service 0x8C: HAL: Read Specific I/O Pin

    Read specified programmable I/O pin.

    Parameters

    AH
    Must be 0x8C.

    AL
    IPC@CHIP PIO No. [0..13]

    Return Value

    AX=0 PIO pin is low, AX!=0 PIO pin is high

    Related Topics

    Write to Specific I/O Pin
    Read Programmable I/O Pins
    PFE: Enable Programmable I/O Pins

    Top of list
    Index page

    Interrupt 0xA1 service 0x8D: HAL: Write to Specific I/O Pin

    Write to a specified programmable I/O pin.   Only PIO pins that are defined as outputs can be written.

    Parameters

    AH
    Must be 0x8D.

    AL
    IPC@CHIP PIO No. [0..13]

    DX
    DX = 0 ==> set PIO to low
    DX non-zero ==> set PIO to high

    Return Value

    none

    Related Topics

    Read Specific I/O Pin
    Write Programmable I/O Pins
    PFE: Enable Programmable I/O Pins

    Top of list
    Index page

    Interrupt 0xA1 service 0x8E: HAL: Give EOI

    Give End-Of-Interrupt for INT0-INT4

    Parameters

    AH
    Must be 0x8E.

    AL
    Type (0=INT0 ... 4=INT4)

    Return Value

    none

    Comments

    When installing a interrupt service routine through HW API, it's not
    necessary to call this function, because the HW API does it for you.
    This function is provided for writing your own interrupt service routines without
    the HAL function Install Interrupt Service Routine.

    This function is especially needed for generating an EOI for INT0 when using cascaded
    mode of the interrupt controller with INT0/INTA .

    Related Topics

    Enable INT0/INTA cascade mode

    Top of list
    Index page

    Interrupt 0xA1 service 0x8F: HAL: Initialize Timer Settings Ext

    Some more useful timer settings (extends the Initialize Timer Settings function)

    Parameters

    AH
    Must be 0x8F.

    AL
    Timer
        0=Timer0 / 1=Timer1

    DX
    Mode
        Bit 0..2: must be 0
        Bit 3: 0=disable prescale t2 / 1=enable prescale t2
        Bit 4: 0=disable retrigger / 1=enable retrigger
        Bit 5..15: must be 0

    Return Value

    none

    Comments

    The Initialize Timer Settings function must be called prior to this function!

    Prescale T2:
      If the Prescale feature is enabled, the timer (specified in AL) will use Timer2 output for its timer base (clock input), providing a 1000 Hz timer clock rate.   (Timer2 is used internally by the @CHIP-RTOS as a one millisecond interval timer.)   If this Prescale bit is disabled, the timer base will instead be the frequency reported by the Get Frequencies API function.


    Retrigger:
      If the retrigger setting is enabled, a 0 to 1 edge transition on TMRIN0 (or TMRIN1) resets the timer count.   When retrigger is disabled (DX bit 4 set to 0), a High input on TMRIN0 (or TMRIN1) enables counting and a Low input holds the timer value.

    Related Topics

    Initialize Timer Settings
    HAL Start Timer function
    Read Timer Count
    Write Timer Count

    Top of list
    Index page

    Interrupt 0xA1 service 0x90: HAL: Get/Set Watchdog Mode

    Get or set the watchdog mode.

    Parameters

    AH
    Must be 0x90.

    AL
    Mode
        0 = only get mode
        2 = Watchdog will be triggered by user program
        3 = Watchdog will be triggered by @CHIP-RTOS (default)

    Return Value

    AX=mode

    Comments

    The watchdog timeout period is 800 ms.

    If you select the User Program mode, you must call the HAL Refresh Watchdog function 0x91 at least every 800 ms to prevent the watchdog from resetting the system.   In @CHIP-RTOS mode, the @CHIP-RTOS performs the watchdog strobing provided that the system's timer interrupt is allowed to execute.   Beware that excessive interrupt masking periods can lead to system resets.

    Related Topics

    Refresh Watchdog Function

    Top of list
    Index page

    Interrupt 0xA1 service 0x91: HAL: Refresh Watchdog

    Strobe the hardware watchdog to reset its timeout period.

    Parameters

    AH
    Must be 0x91.

    Return Value

    none

    Comments

    If the watchdog is in User Program mode, this function must be called at least every 800 ms to prevent a CPU reset due to watchdog timeout.

    Related Topics

    Get/Set Watchdog Mode

    Top of list
    Index page

    Interrupt 0xA1 service 0x92: HAL: Mask/Unmask Int

    Mask or unmask an external Interrupt Request

    Parameters

    AH
    Must be 0x92.

    AL
    1=Mask, 0=Unmask

    DX
    HAL interrupt number from following list:
      0 = INT0 (external)
      1 = Network controller (internal)
      2 = INT2 (external)
      3 = INT3 (external)
      4 = INT4 (external)
      5 = INT5 (external) / Terminal Count DMA Channel 0 (if DMA is used)
      6 = INT6 (external) / Terminal Count DMA Channel 1 (if DMA is used)
      7 = reserved
      8 = Timer0 (internal)
      9 = Timer1 (internal)
      10 = Timer 1ms (internal)
      11 = Serial port 0 (internal)
      12 = Serial port 1 (internal)
      13 = reserved
      14 = reserved
      15 = NMI (Not maskable!)

    Return Value

    none

    Comments

    Some interrupts share the same mask bit.   If you mask one of them, the other interrupts which are assigned to the same bit are also masked.   Here are the groups which are masked together:

      Timer0, Timer1, Timer 1ms
      DMA0, INT5
      DMA1, INT6

    CAUTION:
      Masking any of the three timer interrupts will suspend the @CHIP-RTOS 1000 Hz real-time interrupt, essential for system operation.   Consequently this mask period should be very brief, if used at all.


    Top of list
    Index page

    Interrupt 0xA1 service 0xA0: HAL: Block Read Data Bus

    Read block of bytes from data bus into provided buffer.

    Parameters

    AH
    Must be 0xA0.

    DI
    First address

    SI
    Second address

    ES:BX
    Pointer to buffer

    CX
    Number of bytes to read into buffer

    Return Value

    none

    Comments

    IF SI != DI, this function will alternate reads between the two addresses until CX bytes are read, starting at first address.   Set SI == DI if you want to read from only a single address.

    Related Topics

    Block Write Data Bus
    Read Data Bus

    Top of list
    Index page

    Interrupt 0xA1 service 0xA1: HAL: Block Write Data Bus

    Output byte stream from buffer to specified address or addresses.

    Parameters

    AH
    Must be 0xA1.

    DI
    First address

    SI
    Second address

    ES:BX
    Pointer to buffer

    CX
    Number of bytes in buffer to output

    Return Value

    none

    Comments

    IF SI != DI, this function will alternate between writes to first and second address.   Set SI == DI if you want all data written to a single address.

    Related Topics

    Block Read Data Bus
    Write Data Bus

    Top of list
    Index page

    Interrupt 0xA1 service 0xB0: HAL: Start DMA Mode

    Starts the DMA mode.   After calling this function, the DMA transfer will be started when the external DRQ pins is activated.

    Parameters

    AH
    Must be 0xB0

    AL
    DMA channel:
    0 = DRQ0
    1 = DRQ1

    CX
    Number of bytes which has to be transferred

    DX
    Control Register:
        Bit 0: 1=Priority for the channel / 0=Priority for the other channel
        Bit 1: 1=Source synchronized / 0=No source synchronization
        Bit 2: 1=Destination synchronized / 0=No destination synchronization
        Bit 3: 1=Use interrupt at end of transfer / 0=do not use an interrupt
        Bit 4: must be set to '1'
        Bit 5: 1=Source address increment / 0=No increment of source address
        Bit 6: 1=Source address decrement / 0=No decrement of source Address
        Bit 7: 1=Source is in memory space / 0=Source is in IO space
        Bit 8: 1=Destination address increment / 0=No increment of destination address
        Bit 9: 1=Destination address decrement / 0=No decrement of destination address
        Bit 10: 1=Destination is in memory space / 0=Destination is in IO space
        Bit 11: 1=Word Transfer / 0=Byte Transfer

    Bit1 and Bit2 can't be set at the same time.

    BX:SI
    Pointer to unsigned long (20-Bit physical) source address

    ES:DI
    Pointer to unsigned long (20-Bit physical) destination address

    Return Value

    Success: AX = 0
    AX = -1 Invalid DMA channel
    AX = -2 DMA channel used for serial interface

    Comments

    This function starts a DMA transfer.   After calling this function the DMA controller is ready for transfer.   Once the DRQ pin is activated the DMA transfer will be started.   The number of bytes which will be transferred has to be specified in the CX register.   Before calling this function you have to enable the DRQ pin for this channel (also the serial DMA mode must be disabled in the CHIP.INI).

    Related Topics

    Enable external DRQ Pin
    HAL Stop DMA Transfer

    Top of list
    Index page

    Interrupt 0xA1 service 0xB1: HAL: Stop DMA Transfer

    Disables the DMA controller.   A running DMA transfer will be halted.

    Parameters

    AH
    Must be 0xB1

    AL
    DMA channel:
    0 = DRQ0
    1 = DRQ1

    Return Value

    Success: AX = 0
    AX = -1 Invalid DMA channel
    AX = -2 DMA channel used for serial interface

    Comments

    Stops a DMA transfer (disables the DMA controller).   The transfer could be continued by reading the current DMA values (using function Get DMA Info) and starting the DMA Transfer again with the read values (using function Start DMA Mode)

    Related Topics

    Start DMA Transfer

    Top of list
    Index page

    Interrupt 0xA1 service 0xB2: HAL: Get DMA Info

    Get the state of the DMA channel.

    Parameters

    AH
    Must be 0xB2

    AL
    DMA channel:
    0 = DRQ0
    1 = DRQ1

    BX:SI
    Output Parameter:   Pointer to unsigned long where this function will write the (20-Bit physical) source address

    ES:DI
    Output Parameter:   Pointer to unsigned long where this function will write the (20-Bit physical) destination address

    Return Value

    AX = 0 DMA channel disabled
    AX = 1 DMA channel (user mode) enabled for transfer
    AX = -1 Invalid DMA channel
    AX = -2 DMA channel used for serial interface
    CX = DMA counter (bytes which have yet to be transferred)
    DX = Control Register:     Bit 0: 1=Priority for the channel / 0=Priority for the other channel
        Bit 1: 1=Source synchronized / 0=No source synchronization
        Bit 2: 1=Destination synchronized / 0=No destination synchronization
        Bit 3: 1=Use interrupt at end of transfer / 0=do not use an interrupt
        Bit 4: must be set to '1'
        Bit 5: 1=Source address increment / 0=No increment of source address
        Bit 6: 1=Source address decrement / 0=No decrement of source Address
        Bit 7: 1=Source is in memory space / 0=Source is in IO space
        Bit 8: 1=Destination address increment / 0=No increment of destination address
        Bit 9: 1=Destination address decrement / 0=No decrement of destination address
        Bit 10: 1=Destination is in memory space / 0=Destination is in IO space

        Bit 11: 1=Word Transfer / 0=Byte Transfer
    [BX:SI] = contains unsigned long (20-Bit physical) DMA source address
    [ES:DI] = contains unsigned long (20-Bit physical) DMA destination address

    Comments

    This function returns the status of the DMA channel in AX.

    Related Topics

    Start DMA Transfer

    Top of list
    Index page

    Interrupt 0xA1 service 0xC0: HAL: Initialize/Restore Non-Volatile Data

    Initialize/Restore non-volatile data.   Tell the @CHIP-RTOS where your variables are located, which should be saved and reload their saved values, if available.
    The non-volatile (remanent) data is stored in A:\rema.bin file.

    Parameters

    AH
    Must be 0xC0

    ES:BX
    Pointer to a _REMOP structure:

    struct _REMOP
    {
        unsigned entries; // Number of entries in struct
                          // REMOP_ENTRY x[].
        unsigned segment; // Common segment address

        struct REMOP_ENTRY
        {
            unsigned offs;      // Address offset
            unsigned size;      // Number of bytes
            unsigned maxsize;   // Obsolete, set to 0
            unsigned elemsize;  // Number of bytes per data
                                // element
            unsigned distance;  // Distance to next data element
                                // (must be >= elemsize).
        }x[MAX_RETENTIVE_AREAS];
    };

    Return Value

    Success: AX = 0
    Failure: AX < 0, Could not create file

    Comments

    Call this function at the beginning of your program.

    The _REMOP structure reference by ES:BX must be static.   (This function does not make a copy of the structure's content.)

    The number of entries in the x array of REMOP_ENTRY data structures can be defined by the user.   This number must be specified in the entries field of the _REMOP data structure.

    All data saved / restored must reside in the same segment, specified by the segment field in _REMOP.   The individual data item locations in this segment are then listed in the offs fields of the REMOP_ENTRY structure array.

    Related Topics

    Save Non-Volatile Data

    Top of list
    Index page

    Interrupt 0xA1 service 0xC1: HAL: Save Non-Volatile Data

    This function saves your non-volatile data listed in the _REMOP structure registered with HAL function 0xC0.   The data is stored in A:\rema.bin file.

    Parameters

    AH
    Must be 0xC1

    Return Value

    none

    Comments

    Call this function on exit from your program and in your NMI (Non-Maskable Interrupt) handler.   Your hardware around the IPC@CHIP must support the Pfail signal, so that the IPC@CHIP can generate an NMI sufficiently in advance of power loss to the CPU.

    Reminder : The DK40 does not support the Pfail signal.

    Related Topics

    Initialize/Restore Non-Volatile Data
    Install Interrupt Service Routine

    Top of list
    Index page

    Interrupt 0xA1 service 0xC2: HAL: Get Reboot Reason

    Check cause of most recent reboot.

    Parameters

    AH
    Must be 0xC2

    Return Value

    AX = reason:
      0 = UNKNOWN
      3 = WATCHDOG
      4 = POWER FAIL

    Comments

    This function only returns valid results if the init/restore function (0xC0) was called following the reboot.

    Related Topics

    Initialize/Restore Non-Volatile Data

    Top of list
    Index page


    End of document