@CHIP-RTOS - I2C Bus and SPI Interface

I2C / SPI API

Philips was the inventor of the Inter-IC or I²C-bus, and it is now firmly established as the worldwide de-facto solution for embedded applications. It is used extensively in a variety of microcontroller-based professional, consumer and telecommunications applications as a control, diagnostic and power management bus. As a two-wire serial bus, its inherently simple operation was crucial to its emergence as the worldwide de-facto standard.

SPI is a serial bus standard established by Motorola. The Serial Peripheral Interface (SPI) is a synchronous serial interface useful for communicating with other peripheral or microcontroller devices. These peripheral devices may be Serial EEPROMs, shift registers, display drivers, A/D converters, etc.

Interrupt 0xAA Services

General

I2C Functions

SPI Functions

This function initializes the I2C bus. It enables the two defined pins for I2C usage (see also function 8eh and 8fh).

Parameters

AH

0x80

Return Value

AX=0, Carry flag cleared

Comments

The user can specify which two PIO are used for I2C clock and data.   After calling this initialization function, these two pins will no longer be available as PIO pins unless the PFE Enable function is called for these pins following this function call.

SC1x3/SC2x Comments

On SC1x3/SC2x the default is to use the hardware I2C interface on the dedicated pins. If the user calls functions 8eh and 8fh to select other PIOs for the bus, the I2C bus will be software emulated on the selected PIO pins.

If the hardware interface is used, the calling task will go to sleep, until the I2C interrupt issues a wakeup. Therefore the user should not make own wakeup calls to the I2C API calling task, while sleeping inside I2C functions.

Related Topics

Select I2C Clock Pin

Select I2C Data Pin

PFE: Enable Programmable I/O Pins

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

Report addresses of slave devices, one at a time.

Parameters

AH

0x81

AL

Bit7-0: First slave address (even address, LSB=0)

CL

Bit7-0: Last slave address (even address, LSB=0)

Return Value

AL: 0 no slave found
AL: -1 Timeout
AL: address of the first found slave

Comments

This is an iterator function which is called repetitively to determine all connected slaves.   Specify on each successive call a new restricted slave address range until no further address is returned by this function.  

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

Report addresses of slave devices, one at a time.

Parameters

AH

0x85

DX

Bit10-0: First slave address (even address, LSB=0)

CX

Bit10-0: Last slave address (even address, LSB=0)

Return Value

AX: 0 no slave found
AX: -1 Timeout
AX: address of the first found slave

Comments

This is an iterator function which is called repetitively to determine all connected slaves.   Specify on each successive call a new restricted slave address range until no further address is returned by this function.  

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.20	V1.20	V1.20	V0.90	V1.00

Send or receive a single character.

Parameters

AH

0x82

AL

Bit7-0: Slave address, LSB:0 => Transmit, LSB:1 => Receive

CL

If Transmit: CL = Byte to transmit
If Receive: CL = 0 for last char to be received

Return Value

Success: Carry flag cleared and CH contains received byte (if receiving)
Failure: Carry flag set and AL contains I2C error code

Comments

The IPC@CHIP® is the I2C bus master.

The least significant bit of the slave address determines the direction of the communication.

Even address:   Master sending to slave
Odd address:   Master receiving from slave

If the direction or the slave address changes, this functions executes the I2C restart function automatically. This will insert a I2C start condition on the bus. After this, the I2C address is send again.

I2C error codes:

8: Timeout
9: Slave faulty or not available

SC1x3/SC2x Comments

On SC1x3/SC2x these additional return values are possible if the hardware I2C interface is used:

3: Arbitration lost, general call address received
4: Arbitration lost, own slave address received, master wants to read (change from master to slave)
5: Arbitration lost, own slave address received, master wants to write (change from master to slave)
6: Arbitration lost
7: Bus error

Related Topics

I2C Transmit/Receive Block

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

Send or receive a single character.

Parameters

AH

0x86

DX

Bit10-0: Slave address, LSB:0 => Transmit, LSB:1 => Receive

CL

If Transmit: CL = Byte to transmit
If Receive: CL = 0 for last char to be received

Return Value

Success: Carry flag cleared and CH contains received byte (if receiving)
Failure: Carry flag set and AL contains I2C error code

Comments

The IPC@CHIP® is the I2C bus master.

The least significant bit of the slave address determines the direction of the communication.

Even address:   Master sending to slave
Odd address:   Master receiving from slave

If the direction or the slave address changes, this functions executes the I2C restart function automatically. This will insert a I2C start condition on the bus. After this, the I2C address is send again.

I2C error codes:

8: Timeout
9: Slave faulty or not available

SC1x3/SC2x Comments

On SC1x3/SC2x these additional return values are possible if the hardware I2C interface is used:

3: Arbitration lost, general call address received
4: Arbitration lost, own slave address received, master wants to read (change from master to slave)
5: Arbitration lost, own slave address received, master wants to write (change from master to slave)
6: Arbitration lost
7: Bus error
8: Timeout

Related Topics

I2C Transmit/Receive Block

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.20	V1.20	V1.20	V0.90	V1.00

Parameters

AH

0x83

AL

Bit7-0: Slave address, LSB:0 => Transmit, LSB:1 => Receive

CX

Number of bytes to transmit or receive

ES:BX

Buffer address

Return Value

Success: Carry flag cleared
Failure: Carry flag set and AL contains I2C error code

Comments

If an odd slave address is specified in AL then this function will dwell here until either CX bytes are received and stored in user buffer at [ES:BX], or until an error occurs.   For an even slave address this function will dwell here until CX bytes from user buffer at [ES:BX] are transmit or until an error occurs.

If the direction or the slave address changes, this functions executes the I2C restart function automatically. This will insert a I2C start condition on the bus. After this, the I2C address is send again.

Related Topics

I2C Transmit/Receive Character

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

Parameters

AH

0x87

DX

Bit10-0: Slave address, LSB:0 => Transmit, LSB:1 => Receive

CX

Number of bytes to transmit or receive

ES:BX

Buffer address

Return Value

Success: Carry flag cleared
Failure: Carry flag set and AL contains I2C error code

Comments

If an odd slave address is specified in AL then this function will dwell here until either CX bytes are received and stored in user buffer at [ES:BX], or until an error occurs.   For an even slave address this function will dwell here until CX bytes from user buffer at [ES:BX] are transmit or until an error occurs.

If the direction or the slave address changes, this functions executes the I2C restart function automatically. This will insert a I2C start condition on the bus. After this, the I2C address is send again.

Related Topics

I2C Transmit/Receive Character

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.20	V1.20	V1.20	V0.90	V1.00

Parameters

AH

0x84

Return Value

Carry flag cleared, AL contains I2C error

Comments

This function generates an I2C stop condition. (The Bus will be released). At next call of transmit or receive functions, the address will be send again.

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.26	V1.26	V1.26	V1.23	V1.23

Parameters

AH

0x8B

Return Value

Carry flag cleared

CF: 0

Comments

This function generates an I2C start condition. (The Bus will be reserved)

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

Select IPC@CHIP® I/O pin to be used for I2CCLK signal.

Parameters

AH

0x8E

AL

PIO pin number

Return Value

none

SC1x Comments

The default I2C clock pin is PIO 0
To change the I2CCLK pin this function must be called before the I2C initialize function (0x80) is called.

SC1x3/SC2x Comments

To use the I2C hardware interface do not call the functions "Select I2C Clock Pin" and "Select I2C Data Pin" or call them both with PIO pin number 0.

Related Topics

Initialize I2C Bus Function

Select I2C Data Pin

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

Select IPC@CHIP® I/O pin to be used for I2CDAT signal.

Parameters

AH

0x8F

AL

PIO pin number

Return Value

Carry flag cleared

SC1x Comments

The default I2C data pin is PIO 1
To change the I2CDAT pin this function must be called before the I2C initialize function (0x80) is called.

SC1x3/SC2x Comments

To use the I2C hardware interface do not call the functions "Select I2C Clock Pin" and "Select I2C Data Pin" or call them both with PIO pin number 0.

Related Topics

Initialize I2C Bus Function

Select I2C Clock Pin

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

This function sets the I2C bus timeout. If you like to change the default timeout value, then call this function after the I2C init function.

Parameters

AH

0x88

BX

Timeout value.

If the I2C hardware interface is used, this value has a resolution in milliseconds. This means that the internal I2C functions will wait for BX milliseconds if the I2C clock signal is released by the I2C slave.

If the software I2C emulation is used, this value is interpreted as a cycle count. This means that the internal I2C functions check BX times if the I2C clock signal is released by the I2C slave.

Return Value

Carry flag cleared

Comments

If the I2C slave uses clock stretching, this timeout specifies the maximum waiting time, before the access is aborted.

The default timeout is:
SC12: 50 cycles
SC12B: 100 cycles
SC13/SC11: 250 cycles
SC1x3/SC2x: 3000 cycles / 50 ms

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.22	V1.22	V1.22	V1.11	V1.00

This function sets the I2C bus speed, if the I2C hardware interface is used.

Parameters

AH

0xB0

BL

N (allowed value range 0-7)

BH

M (allowed value range 0-15)

Return Value

AX=0, Carry flag cleared

Comments

FREQsample = CPU clock / 2^N
FREQoscl = CPU clock / ((2^N) * (M+1) * 10)

FREQoscl is the frequency of the I²C clock line when the I²C controller is in master mode.
FREQsample is the frequency at which the I²C bus is sampled. This frequency should be at least 10 times faster than the fastest master on the bus, to ensure that START and STOP conditions are always detected.

Default is N=4, M=5, which sets FREQsample to 6 MHz and FREQoscl to 100 KHz at 96 MHz CPU frequency.

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V0.90	V1.00

This function resets the I2C bus hardware controller.

Parameters

AH

0xB1

Return Value

Carry flag cleared

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V0.90	V1.00

This function initializes the I2C bus slave interface. To use the I2C slave interface the user has to install an interrupt service routine for the I2C interrupt. An interrupt occurs when the I2C state changes. The user should than read the I2C state with function read I2C state.

Parameters

AH

0xB2

BX

Slave address:
Bit0: read/write bit must be 0
Bit7-1: 7 bit slave address or
Bit10-1: 10 bit slave address

CL

0: don't listen to general call address
1: listen to general call address

Return Value

Carry flag cleared

Comments

The I2C bus intialize function must be called previously. The Slave mode works only if the I2C hardware interface in used.

Related Topics

Init I2C function

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V0.90	V1.00

This function reads the current I2C bus state, if the I2C slave interface is used.

Parameters

AH

0xB3

Return Value

AX contains I2C bus state:
3: General call address received
4: Own slave address received, master wants to read
5: Own slave address received, master wants to write
6: Arbitration lost
7: Bus error
10: Data byte received from master
11: Data byte transmitted to master, master wants next byte
12: Last data byte transmitted to master
13: STOP or repeated START condition received

Comments

This function should be used inside the I2C interrupt handler, if the I2C slave interface is used.

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V0.90	V1.00

This function sends an acknowledge, if the I2C slave interface is used.

Parameters

AH

0xB4

AL

0: Send a non acknowledge
1: Send acknowledge

Return Value

Carry flag is cleared.

Comments

This function should be used inside the I2C interrupt handler, if the I2C slave interface is used and the return state signals that the master wants to write a byte.

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V0.90	V1.00

This function reads a byte from the bus, if the I2C slave interface is used.

Parameters

AH

0xB5

Return Value

AL contains read byte, Carry flag is cleared.

Comments

This function should be used inside the I2C interrupt handler, if the I2C slave interface is used and the return state signals that the master has written a byte, which can now be read out.

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V0.90	V1.00

This function writes a byte to the bus, if the I2C slave interface is used.

Parameters

AH

0xB6

AL

Byte to write

BL

1: Signal that more bytes are available
0: Signal that this is the last byte that can be transfered

Return Value

Carry flag is cleared.

Comments

This function should be used inside the I2C interrupt handler, if the I2C slave interface is used and the return state signals that the master wants to read a byte.

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V0.90	V1.00

This function sets the I2C internal state back to idle, if the I2C slave interface is used.

Parameters

AH

0xB7

Return Value

Carry flag is cleared.

Comments

This function should be used inside the I2C interrupt handler, if the I2C slave interface is used and the return state signals that the last byte was transmitted to the master.

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V0.90	V1.00

This function installs a far JMP opcode in the vicinity of the return instruction pointer to enter the specified USB API function directly from the user code. This function is provided for efficiency in real-time applications.

Parameters

AH

0x00

AL

Number of I2C/SPI API function that is to be linked

Return Value

Instruction Pointer is moved back 10 bytes so that newly installed far JMP will execute immediately.

(Refer to respective linked function's documention for further return value information.)

Note: All dynamically linked functions are free to use all registers except for DS, SI, DI, and BP registers which are preserved. This matches Paradigm C, Borland C++ 5.02 and Microsoft Visual C 1.52 calling conventions.

Comments

Dynamic linking is not yet implemented for I²C!

A JMP FAR instruction will be written 10 bytes before the user's return instruction pointer. This far jump will transfer control directly into the RTOS from the user code when executed. This new far JMP will execute immediately upon return from this software interrupt due to the instruction pointer adjustment performed within the call.

Interrupts are masked and restored to their state on entry.

Since the code at calling site will be patched by this RTOS call, it is important that it has exactly the following form (the link index carried in AL register will vary)

JMP SHORT over_patch  ; Occupies 2 bytes of instruction code here
NOP    ; Never executed (1 byte)
NOP    ; Never executed (1 byte)
NOP    ; never executed (1 byte)
over_patch:  ; Linker overwrites above 5 bytes with JMP FAR instruction
MOV AX,00090h  ; AH = 0x00, AL = 0x90 = index for spi_init() or spi_init_hw()
INT 0AAh

Developer Notes

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V1.15	V1.00

Initialize the SPI master interface.

SPI specifies four signals:

• clock (SCLK)
  
• master data output, slave data input (MOSI)
  
• master data input, slave data output (MISO)
  
• slave select (CSS)

In software SPI mode, the slave select signal pin is not specified with the SPI init function and not activated with the SPI read and write functions. The user has to enable any other PIO pin for that purpose and should serve this pin manually.

SC1x3/SC2x:

In hardware SPI mode, if Autodrive-mode is enabled the SLVSEL pin is automatically driven by the SPI master read and write functions.

Parameters

AH

Must be 0x90

CL

PIO number for SPI Clock Pin (SCLK)

CH

PIO number for SPI Input Pin (MISO)

DL

PIO number for SPI Output Pin (MOSI)

SC1x Parameters

BX

Mode, must be 0 (SPI mode 0)

SC1x3/SC2x Parameters

BX

Mode when software SPI is selected:
        BX must be 0

Mode when hardware SPI is selected:
        BIT0-1 = SPI mode (0-3)
        BIT2 = 1 use Open-Drain-Mode, 0 use Output-Mode
        BIT3 = 1 Autodrive SLVSEL chipselect pin, 0 do not drive SLVSEL pin
                    (Autodrive works only together with Alternate I/O)
        BIT4 = 1 invert SLVSEL chipselect pin (active high), 0 do not invert SLVSEL pin (active low)
        BIT5-7 = bit shift count, 000 = 8 bit, 001 = 1 bit ... 111 = 7 bit
        BIT8 = 0 Normal I/O pinout, 1 Alternate I/O pinout (swap SDI and SDO pin)
        BIT9-15 = must be 0

SI

SPI speed clock divider (valid values: 0-65535) (valid for hardware SPI only)
The SPI clock frequency is calculated with the formula:
SPI freq = CPU freq / (divider*2+2)

Return Value

none

SC1x3/SC2x Comments

If CL=CH=DL=0 than Hardware SPI is selected on dedicated pins else software SPI is performed on selected PIO pins.

A Wired-OR mode is provided which allows multiple masters to collide on the bus without risk of damage. In this mode, an external pull-up resistor is required on the Master Out Slave In (MOSI) and Master In Slave Out (MISO) pins. Generally, pull-ups are recommended on all of the external SPI signals to ensure they are held in a valid state, even when the SPI interface is disabled.

Alternate I/O pinout means that TX and RX lines are swapped.

Related Topics

Read SPI Block (master interface)

Write SPI Block (master interface)

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.10	V1.00	V1.00	V0.90	V1.00

Write n bytes out to the SPI Output pin

Parameters

AH

Must be 0x95.

ES:SI

Pointer to write buffer

CX

Number of bytes in buffer to write

Return Value

Result code in AX:

• Always 0 for software SPI
• 1, if illegal arguments were passed
• Else status bitmap:
  • BIT5 = 1: A collision has occurred between multiple masters
  • BIT6 = 1: An overrun was detected

SC1x3/SC2x Comments

Overrun detection only works with hardware SPI and if the SLVSEL pin is used as chipselect.

Related Topics

Init SPI (master interface)

Read Block SPI (master interface)

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.10	V1.00	V1.00	V0.90	V1.00

Reads n bytes from the SPI Input pin

Parameters

AH

Must be 0x96

ES:DI

Pointer to buffer for storing read data

CX

Number of bytes to read

Return Value

Result code in AX:

• Always 0 for software SPI
• 1, if illegal arguments were passed
• Else status bitmap:
  • BIT5 = 1: A collision has occurred between multiple masters
  • BIT6 = 1: An overrun was detected

SC1x Return Value

AX = 0

SC1x3/SC2x Comments

Overrun detection only works with hardware SPI and if the SLVSEL pin is used as chipselect.

Related Topics

Init SPI (master interface)

Write SPI Block (master interface)

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.10	V1.00	V1.00	V0.90	V1.00

Reads n bytes from the SPI Input pin and write n bytes out to the SPI Output pin simultaneously.

Parameters

AH

Must be 0x97

DS:DI

Pointer to buffer for storing read data

ES:SI

Pointer to buffer which stores write data

CX

Number of bytes to read and write

Return Value

Result code in AX:

• Always 0 for software SPI
• 1, if illegal arguments were passed
• Else status bitmap:
  • BIT5 = 1: A collision has occurred between multiple masters
  • BIT6 = 1: An overrun was detected

SC1x3/SC2x Comments

Overrun detection only works with hardware SPI and if the SLVSEL pin is used as chipselect.

Related Topics

Init SPI (master interface)

Write SPI Block (master interface)

Read SPI Block (master interface)

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.10	V1.00	V1.00	V0.90	V1.00

Initialize the SPI slave interface.

To use the SPI slave interface the user has to install an interrupt service routine for the SPI interrupt. An interrupt occurs when the SLVSEL pin transitions from active to inactive.

Parameters

AH

Must be 0xA0

BX

Mode
        BIT0-1 = SPI mode (0-3)
        BIT2 = 1 use Open-Drain-Mode, 0 use Output-Mode
        BIT3 = must be 0
        BIT4 = 1 invert SLVSEL chipselect pin (active high), 0 do not invert SLVSEL pin (active low)
        BIT5-7 = must be 0
        BIT8 = 0 Normal I/O pinout, 1 Alternate I/O pinout (swap SDI and SDO pin)
        BIT9-15 = must be 0

Return Value

none

Comments

When operating as a slave, the SPI clock signal (SCLK) must be slower than 1/8th of the CPU clock (1/16th is recommended).

A Wired-OR mode is provided which allows multiple masters to collide on the bus without risk of damage. In this mode, an external pull-up resistor is required on the Master Out Slave In (MOSI) and Master In Slave Out (MISO) pins. Generally, pull-ups are recommended on all of the external SPI signals to ensure they are held in a valid state, even when the SPI interface is disabled.

Alternate I/O pinout means that TX and RX lines are swapped.

Related Topics

Read SPI (slave interface)

Write SPI (slave interface)

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V0.90	V1.00

Write a byte to the SPI slave interface.

Parameters

AH

Must be 0xA5

BL

Data to write

Return Value

none

Related Topics

Init SPI (slave interface)

Read SPI (slave interface)

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V0.90	V1.00

Read a byte from the SPI slave interface.

Parameters

AH

Must be 0xA6

Return Value

AL contains read data

Related Topics

Init SPI (slave interface)

Write SPI (slave interface)

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V0.90	V1.00

Read and write a byte from/to the SPI slave interface.

Parameters

AH

Must be 0xA7

BL

Data to write

Return Value

AL contains read data

Related Topics

Init SPI (slave interface)

Read SPI (slave interface)

Write SPI (slave interface)

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V0.90	V1.00

Wait on semaphore / Release semaphore
If multiple tasks use the SPI hardware master interface to access different slaves through different slave chip select PIO pins, this call should be used to synchronise the SPI activity on the bus. The external MMC/SD driver examples uses this call since his version V1.02.

Parameters

AH

Must be 0xA8

BX

0: Release the semaphore
1: Wait on semaphore
2: Wait on semaphore and set SPI mode and divider

CX

SPI mode (see SPI init function)

SI

SPI divider (see SPI init function)

Return Value

AX contains error code

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V1.05	V1.00