Scan OS Function summary

The OS functions each have a unique vector which is used to JSR to the appropriate function. These vectors will remain fixed, even if the functions themselves are moved around in the internal ROM. These vectors are defined in an include file which you can use in your programs.

Each OS function will use (and usually alter) the contents of ACC, R0, DPTR and any other registers used for parameters, unless otherwise noted. Byte parameters are usually passed and returned in ACC, and if a second byte parameter is used, in R0. Pointers are always passed and returned in DPTR. 16 Bit values are passed and returned in A (low byte) and R0 (high byte). The following notation is used to describe the parameters:

ACCBYTE(first) 8-bit Parameter in ACC
R0BYTE2(second) 8-bit Parameter in R0
R1BYTE3(third) 8-bit Parameter in R1
DPTRPOINTERPointer parameter in DPTR
R0:ACCWORD16-bit Parameter in R0 (high) & ACC (low)
DPH:DPLBYTE3, BYTE42 8-Bit Parameters in DPH (BYTE3) and DPL (BYTE4)

If an ampersand character is appended to the type, the value is returned in that register.

Screen Functions

POINTER StrOut (POINTER text)

Address $0106

This function prints out the null terminated string pointed to by text on the LCD display. It observes and interprets the following control characters:

ASCII Code (decimal)Description
0End of string
1-7User defined characters. Character 0 accessible by ScrChr() only
8Backspace
9Tab
10Linefeed (scroll up display if in second line)
13Carriage Return (goto first column in current line)
128Clear Screen
129Home

All other characters are output "as is" on the LCD display (see display data sheet for complete character set). The functions returns a pointer to the null character terminating the string. When outputting strings from a table this can be useful for advancing the pointer to the next string.


VOID ChrOut (BYTE data)

Address $0103

Prints out the character specified on the LCD display. No interpretation is performed on the character. (see display data sheet for complete character set). This function is useful for printing a single character only, or for accessing control characters otherwise processed by StrOut(). This is especially true for the user defined characters with character codes 0 to 7.


VOID HexOut (BYTE data)

Address $0118

Prints the byte in ACC at the current cursor position in hexadecimal. This function is useful for debugging, but the end user does not normally want to see hex numbers.


VOID Cls (VOID)

Address $0112

Clears the LCD display and returns the cursor to the 0,0 position.


VOID Home (VOID)

Address $010F

Returns the cursor to the 0,0 position, but leaves the LCD display contents intact.


VOID Display_Ctrl (BYTE control)

Address $0115

This function is used to control the appearance of the cursor and the mode of the display.

Bit setBit clear
Bit 0Cursor onCursor off
Bit 1Cursor blinkingCursor not blinking
Bit 2Display onDisplay off


VOID Pos_Cursor (BYTE col, BYTE2row)

Address $0109

Sets the cursor to the specified position on the display. Col may be in the range of 0-63 and Row may be in the range of 0-1.


VOID Get_Cursor (BYTE& col, BYTE2&row)

Address $010C

Returns the current cursor coordinates. The values returned can be used directly to call Pos_Cursor(). Again, col may be in the range of 0-63 and Row may be in the range of 0-1.


VOID Load_Font (POINTER font, BYTE count)

Address $011B

Loads up to eight characters into the LCD display's character generator. The function always loads the characters starting at character 0. Count can be any value from 1-8. The font data pointed to by font must be consecutive. Each character consists of TBD font data bytes. Only the 5 least significant bits of each byte are used. The characters can be accessed as character codes 0 through 7.


Keyboard Functions

BYTE GetCh(VOID)

Address $011E

Read a character from the keyboard. Function returns immediately if no character is available. Up to one keypress is buffered by the OS. In no character is available, the functions returns $FF. Otherwise the ASCII code of the key is returned. The #-key acts as the "Enter/Yes" key and is assigned the ASCII code 13, the *-key (sometimes also the "Esc/Abort/No" key) has the ASCII code 42.


BYTE Input(VOID)

Address $0121

Read a character from the keyboard. This function waits until a key has been pressed. Otherwise it behaves exactly as GetCh().


Timer and OS Functions

WORD GetVer(VOID)

Address $0100

This function returns the current version of the operating system. Currently it returns $01:$00 (Version 1.00)


VOID Delay(BYTE tickcount)

Address $0124

This function waits a number of 10 ms ticks. This is a simple way to implement delays.


BYTE GetRamTop(VOID)

Address $0193

This function returns the first RAM address usable by the Application program.


Misc. Functions

VOID Mode_10K(VOID)

Address $0157

Sets the ALDL output to 10K (diagnostic mode). This is used to put some ECMs into diagnostic mode.


VOID Mode_Open(VOID)

Address $0154

Sets the ALDL output to open (road mode). Not all ECMs output any information while the A & B terminals are open, but some do.


BYTE GetPtr(POINTER ptr)

Address $0184 This function returns the byte at the address in the linear 64K address space as described above.

VOID PutPtr(POINTER ptr, BYTE data)

Address $0187 This function writes a byte at the address in the linear 64K address space as described above. The pointer must reference either a RAM address (in the range 0-$FF) or an EEPROM address ($2000-$27FF).

BYTE Sel_Menu(POINTER menu)

Address $0127

This function is useful for selecting one of a number of entries from a menu. The function is passed a pointer to a menu structure, and returns the zero based index of the menu entry the user selected. The selection is made using the "2" (up) and "8" (down) keys. The menu entry is selected with the "#" (Enter) key, or the selection is aborted with the "*" key. If the selection is aborted, the function returns $FF. The current item is marked with an arrow, and the display scrolls up and down automatically if necessary.

The menu structure pointed to by menu consists of one byte describing the number of entries in the menu, a zero byte and then a table of null separated strings as menu entries. The menu must consist of at least two entries and each entry should contain 15 null-terminated printable characters or less.

Example:

	MOV 	DPTR,#MyMenu
	LCALL	Sel_Menu 	;function returns 0,1 or 2
	RET			;if entry was selected or else $FF

MyMenu:
	DB 3			;3 entries
	DB 0			;separator
	DB 'Choice 1',0 	;first entry
	DB 'Choice 2',0 	;second entry
	DB 'Choice 3',0 	;last entry


BYTE Message(POINTER msgptr, BYTE lcdwidth)

Address $012A

The message function is very useful for communicating long messages to the user. It formats a multiline message to fit the LCD screen. Msgptr points to a null-terminated string containing the message, lcdlen is the width of the LCD screen, typically 16.

The message is automatically broken down into several lines, and a line break can also be forced through the use of the vertical bar character (ASCII code 124).

The user can scroll down to view the entire message with the "8" or "0" keys. If the Escape ("*") or Enter ("#") key are pressed, the function returns.

The return value is the ASCII code of the key that caused the function to return. This is similar to a message-box under Windows, that can be used to ask the user a question, and the user can respond simply with yes/ok or no/abort.


VOID Switch(POINTER jmptable, BYTE selector)

Address $0199

This is a shortcut function intended to be used with Sel_Menu. jmptable is a jumptable consisting of three byte entries in the form "LJMP address". A is used to branch to an entry of the jumptable, with 0 branching to the first entry in the table, and so on.

The jumptable may have up to 64 entries.


VOID LedCtrl(BYTE)

Address $019F

This function is used to control the LED. The following table shows all possible parameter values:

ValueDescription
0LED off
1LED on
2LED flashing slowly
3LED flashing quickly


VOID SndCtrl(BYTE)

Address $01A2

This function is used to control the buzzer. The following table shows all possible parameter values:

ValueDescription
0Buzzer off
1Buzzer on
2Buzzer beeping slowly
3Buzzer beeping quickly


WORD CRC(POINTER memptr, WORD init, BYTE3 num_words)

Address $019C

This function calculates the CRC over a given block of memory. The block of memory may be up to 512 bytes long. The function is passed a pointer to the memory, an init value for the checksum, and the length of the block of memory in words. The function returns the CRC over the block of memory, and DPTR points to the first location after the block of memory.

In order to call the function multiple times for memory blocks larger than 512 bytes, only the num_words parameter needs to be passed, the other parameters will be initialized correctly by the previous call.


POINTER HexDump(POINTER memptr)

Address $0190

This function dumps 4 bytes in hex to the display in the following form:

	ORG 	0AB42H
LABEL:	DB	019H,02CH,075H,08FH

	...
	MOV	DPTR,#LABEL
	LCALL	HexDump
	...

;displays this line on the display:
;	AB42:19 2C 75 8F 

Upon return DPTR is incremented by four, so the function can be called to dump whole memory blocks with successive calls. The function does not output a CR/LF to prevent scrolling.


VOID StartSingleStep(VOID)

Address $018A

This function starts a simple single step function through a normally closed switch from the ALDL input to ground. This is extremely useful for debugging functions in conjunction with a listing of the program code being executed. After this function is called, execution will stop before the first instruction after the function call.

The contents of the following registers are shown on the LCD display (register values are examples only):

a12 b34 dp=ABCD
pc8134 srC0 spC1

Register names are in lowercase characters: a=ACC, b=BCC, dp=DPTR, pc=PC, sr=PSW, sp=SP. If the switch is momentarily opened, a single instruction will be executed, the updated contents of the registers displayed, and execution again halted.

Note: This function will not step into operating system functions, but will halt again with the first instruction after the operating system call. Also, since the ALDL input is used, this feature can not be combined with any code relying on data being received through the ALDL input, but data reception must be carried out in realtime anyway, so this is not a real concern.


VOID StopSingleStep(VOID)

Address $018D This function stops single step mode and resumes normal operation.


C3 (160 baud) Functions

VOID C3_Init(POINTER buffer, BYTE bufsize)

Address $012D

This function initializes the C3 (CCC = Computer Command Control) handler. It is passed a pointer to a RAM buffer to monitor and the size of the buffer. This is the number of bytes the handler will expect in each frame. Usually the number of bytes in a frame is 20 or 25.

The data in the buffer will continuously be updated while data is being received. If the connection is interrupted, the previous contents will remain in the buffer.


VOID C3_Exit(VOID)

Address $0139

Exits the C3-handler and frees all buffers and internal variables again. Must be called before switching to UART- or Class 2 modes.


BYTE C3_FrameRcvd(VOID)

Address $0130

This function returns true ($FF) if a complete frame has been received. This function is useful to see if the communication could be established. If communication times out, the function returns false (0). Either way, this function returns immediately.


VOID C3_ClearFlag(VOID)

Address $0133

This function clears the handler's lock flag that is set at the end of each frame. If the application clears the lock flag, it can wait for the lock bit to be set again via a call to C3_CommunicationLocked(). This way the application can know when a new frame has arrived and still be able to use the time waiting for the current frame for something useful.


BYTE C3_Testlock(VOID)

Address $0136

This function can be used to check if there is still data coming in. If there has been no data for some time, the function returns 0, otherwise it returns $FF.


UART (8192 baud) Functions

VOID UART_Init(POINTER buffer, BYTE bufsize, BYTE2 module_id)

Address $0172

This function initializes the UART (UART = Universal Async Receive Transmit) handler. It is passed a pointer to a RAM buffer to capture a frame to and the size of the buffer. This is the maximum number of bytes the handler will accept in a frame. Usually the number of bytes in a frame is 68 or less (it's 67 on the Fiero). Only frames starting with the module ID byte are accepted.

The data in the buffer will continuously be updated while data is being received. If the connection is interrupted, the previous contents will remain in the buffer.


VOID UART_Exit(VOID)

Address $0181

Exits the UART-handler and frees all buffers and internal variables again. Must be called before switching to C3- or Class 2 modes. Note: this resets the baudrate back to default 9600 Baud!


BYTE UART_FrameRcvd(VOID)

Address $0175

This function returns true ($FF) if a complete frame has been received. This function is useful to see if the communication could be established. If communication times out, the function returns false (0). Either way, this function returns immediately.


VOID UART_ClearFlag(VOID)

Address $0178

This function clears the handler's lock flag that is set at the end of each frame. If the application clears the lock flag, it can wait for the lock bit to be set again via a call to C3_CommunicationLocked(). This way the application can know when a new frame has arrived and still be able to use the time waiting for the current frame for something useful.


BYTE UART_Testlock(VOID)

Address $017B

This function can be used to check if there is still data coming in. If there has been no data for some time, the function returns 0, otherwise it returns $FF.


VOID UART_Tx_Msg(POINTER msg)

Address $017E

This function is used to transmit a message on the UART bus. Some ECMs only transmit diagnostic information if commanded to do so by a message frame.

The function is passed a pointer to a message, with the first byte containing the length of the message (in bytes) followed by the message itself. The function does not perform any checks to see if the bus is busy.

Note: This function works regardless of whether or not the UART mode is active. In other words, if you're not using the UART mode, you can use this function to transmit data on the serial output at the default 9600 Baud, with 8N1, or you can also set a different baudrate. This can be useful for debugging purposes for instance. However, you do need to build some interfacing circuitry to electrically connect the UART-Bus to a PC or terminal.


VOID UART_SetBaudrate(BYTE index)

Address $01A5 Note: this function is only available with ROM Version 1.1 and higher

This function is used to set the baudrate for the UART. The following baudrates are currently supported:

ValueBaudrate
08192
1300
2600
31200
42400
54800
67200
78192
89600
919200

Class 2 (J1850) Functions

VOID DLC_Init(POINTER buffer, BYTE bufsize)

Address $013C

This function initializes the J1850 (Class 2) handler / Data Link Controller (DLC). It is passed a pointer to a RAM buffer for received messages and the size of the buffer. The buffer size should be at least 22 bytes, which are used internally by the handler to store a message until it is unloaded by the DLC_UnloadMessage function.

An internal flag is set if a message has arrived in the buffer. This flag can be queried with the DLC_Rx_Ready() function.


BYTE J1850_Idle(VOID)

Address $0151

Returns 0 if the J1850 bus is idle, $FF otherwise.


BYTE DLC_Tx_Ready(VOID)

Address $0148

Returns 0 if the DLC is ready to accept another message, nonzero otherwise. The return value contains the fill status of the DLC transmit FIFO:

ValueBuffer status
0Buffer empty
1Buffer not empty
2Buffer almost full
3Buffer full


VOID DLC_Load_Msg(POINTER msgptr, BYTE mode)

Address $0145

Transmits a J1850 message on the bus. msgptr points to a buffer containing the message to be transmitted, with the first byte in the buffer being the length of the message.

The mode determines how the message should be transmitted. If bit 0 is cleared, the message is sent to the DLC and remains there until the DLC can transmit it on the bus. The function returns immediately after the message has been sent to the DLC.

If bit 0 is set, the function returns only after the message has been transmitted on the J1850 bus.

Bit 1 controls the behavior of the function concerning the message previously queued in the DLC. If Bit 1 is set, the previous message in the DLC is cleared/aborted if it has not been sent yet. If Bit 1 is clear, the function waits for the DLC to be ready before the message is transferred to the DLC.


BYTE DLC_Rx_Ready(VOID)

Address $014B

This function reads the status of the internal message buffer. Bit 0 is set if there is a message in the buffer.

Bit 1 is set if a message was lost because a second message was received before the buffer was emptied. This overflow bit is automatically reset when DLC_Unload_Msg() is called.

The remaining bits are reserved for future use and should be masked.


VOID DLC_Unload_Msg(VOID)

Address $014E

This function is called to remove a message from the internal buffer. Also the internal message-in-buffer and overflow flags are reset and the buffer is marked as ready for another message.


VOID DLC_Filter(BYTE flags, BYTE3 tester_id, BYTE4 peer_id)

Address $0196

Used to filter received messages from the bus. If message filtering is off, all messages seen on the bus, including those sent by the DLC itself, will be read by the DLC and appear in the receive buffer. With filtering on, only those messages appear in the buffer that are of interest to the application. The filtering options are tailored to GM messages with three byte headers and no In-Frame response. If other filtering is required, it must be done in the application code.

The first parameter is a bit coded parameter that controls the filtering. The default is zero, which allows all messages to get through. If one or several bits are set, the conditions are ORed, which means that a message is discarded if it meets any of the criteria required.

The second parameter is the module ID of the scantool (Usually in the range of $F0-$FD), the third parameter is the module ID of the peer for some filtering options. Generally, bits 1, 5 and 7 should be set to ensure a valid GM header and suppress echoes of messages we sent ourself (echoes).

For physical messages, it usually makes sense to turn on bits 1 through 3 to only see messages addressed to our module from the peer we're communicating with. For functional messages, bit 6 is usually set in conjunction with the module source ID we're interested in.

Bit set
Bit 0Discard all physical messages
Bit 1Discard physical messages with source ID = our ID (discard our physical echoes)
Bit 2Discard physical messages with target ID not equal our ID (Broadcast messages are allowed through)
Bit 3Discard physical messages with source ID not equal peer ID
Bit 4Discard all functional messages
Bit 5Discard all functional messages with source ID = our ID (discard our functional echoes)
Bit 6Discard all functional messages with source ID not equal peer ID
Bit 7Check for GM-Header byte (H=0, K=1)


VOID DLC_Exit(VOID)

Address $013F

Exits the J1850-handler and frees all buffers and internal variables again. Must be called before switching to UART- or C3-modes.


BYTE DLC_Data(BYTE data, BYTE2& cmd_status)

Address $0142

Low level function for direct communication with the DLC. The data in ACC is transferred into the DLC's tx data register, the data in R0 is put into the command register. Upon return, ACC contains the rx data register, and R0 contains the status register.

It is usually not necessary to access this function directly, because the basic J1850 functionality is provided be the other DLC functions.


Scaling Limit Offset Transfer (SLOT) Functions

VOID Slot_Output(BYTE type, BYTE2 address)

Address $015A

This function prints a value on the display at the current cursor position. Address must be the address in internal RAM containing the data to be displayed. Type describes how the data should be interpreted and displayed. The following table lists all currently supported data types.

TypeNameRangeDescription
0Dec0/255One byte is output in decimal
1Hex0/FFOne byte is output in hex
2Mul0020/5.1One byte, multiplied by 0.02, it output in decimal
3Mul010/25.5One byte, multiplied 0.1, is output in decimal
4Percent0/100.0One byte is scaled to a range of 0-100%
5Mul250/6375One byte is multiplied by 25 and output in decimal
6Cool-40/150One byte is converted to a temperature (degrees Celsius)
7Mat-63/159One byte is converted to a temperature (degrees Celsius)
8Angle450/45.0One byte is scaled to an angle of 0-45 degrees
9Angle900/90.0One byte is scaled to an angle of 0-90 degrees
10Oxygen0-1.128One byte is converted to an O2 sensor voltage
11Second0-1000.0Two bytes are scaled to a range of 0-1000.0ms
12Dec160-65535Two bytes are output in decimal (High byte first)
13Hex160/FFFFTwo bytes are output in hex (High byte first)
14Baro10.0/104.0One byte is scaled to a range of 10.0-104.0 kPa
15Mul1250/3188One byte is multiplied by 12.5 and output in decimal


VOID Slot_SOutput(BYTE type, BYTE2 address, POINTER string)

Address $015D

This function works exactly like SlotOutput(), but it appends the given string to the output. This is useful for displaying the unit after a value.


VOID Slot_OnOff(BYTE data)

Address $0160

This function prints the string "Off" if data is zero, or prints "On" if data is nonzero.


VOID Slot_OpenClosed(BYTE data)

Address $0163

This function prints the string "Open" if data is zero, or prints "Closed" if data is nonzero.


VOID Slot_RichLean(BYTE data)

Address $0166

This function prints the string "Lean" if data is zero, or prints "Rich" if data is nonzero.


VOID Slot_DispItem(POINTER structptr)

Address $0169

This function is used to display an item from the current frame. The location is monitored continuously and the display is updated if necessary until the user presses a key.

The function is passed a structure describing the data to be displayed:

struct {
  BYTE address;		// address of item in internal RAM
  BYTE slot;		// slot function used to display item
  char* prefix;		// string displayed before item
  char* suffix;		// string displayed after item
}

If the 'slot' byte is > 127 (bit 7 set), the lower 7 bits define a binary variable. In this case the bits are defined as follows:

Bits 0-2Bit number in the byte (0-7)
Bit 3Bit is toggled (inverted) if this bit is set
Bits 4-6:String output
0001=on, 0=off
0011=closed, 0=open
0101=rich, 0=lean
0111=yes, 0=no
1xxreserved


BYTE Wait_Or_Abort(VOID)

Address $016C

This function is a "macro" that does several things. It waits for a new frame, and prints "no data" if nothing has been received for a while. If the user aborts by pressing any key, the function returns zero. If the new data that has arrived can be printed, the function returns $FF.


VOID Code_Text(POINTER codetable, BYTE trouble_code)

Address $016F

This function displays a description of a trouble code. It is passed a trouble code number and a pointer to a table describing the trouble codes.

The table describing trouble codes consists of Null separated strings prefixed with the trouble code number. An entry with the trouble code number zero marks the end of the table.

This function is useful whenever a number needs to be converted into one of several corresponding strings.

	MOV     A,trouble_code
	MOV	DPTR,#TXT_CODE
	LCALL   CODE_TEXT
;
TXT_CODE:
	DB	12,'Code 12: No',13,10,'Distrib. Pulses',0
	DB	14,'Code 14: Coolant',13,10,temperature high',0
	DB	0	;End of table

There have been visitors to this site since May 31, 2000.