BIOS Interface Documentation - SC12 @CHIP-RTOS V1.10

BIOS Interrupts

Unsupported BIOS functions are handled by a default handler which issues a message to the console.

Some additional functions not found in a normal PC BIOS are provided for your convenience.

For some useful comments see Programming notes

New in version 1.10B: Extended: Get serial number
New in version 1.10B: Extended: Get @CHIP-RTOS features
New in version 1.10B: Extended: Install User Fatal Error Handler with Low Mem Error
New in version 1.10B: Extended: Get the IPC@CHIP device names
New in version 1.10B: Read/Write persistent user data
New in version 1.10B: Get IP address of the PPP Server
New in version 1.10B: Get IP address of the PPP Client
New in version 1.11B: Get sprintf address

Interrupt 0x1A service 0x00: Get clock count since midnight

Returns the number of clock ticks since midnight.
The frequency of the clock is 18.2 Hz (e.g. 54.945 ms per tick).

Parameters

AH

Must be 0.

Return Value

Returns the 32 bit tick count in CX (high word) and DX (low word)
If an overflow occurred since the last call, AX is set to 1.

Comments

Please note that the overflow indication returned in register AX can not be relied upon if several tasks are using this service.

Interrupt 0x11 service 0xXX: Get equipment list

Get the BIOS equipment list

Return Value

Returns the equipment list in AX, currently 0x013C.   This bit field indicates:

bit 8:       1 : No DMA
bit 6-7:   00: One floppy
bit 4-5:   11: 80x25 mono
bit 2-3:   11: system ram
bit 1:       0 : no 8087
bit 0:       0 : no disk drives

Comments

This function is needed to make sure an application finds no 8087 coprocessor so it can load a floating-point emulator.

Interrupt 0x10 service 0x00: Get char from standard input

Get a character from std in, wait if none available

Parameters

AH

Must be 0.

Return Value

Returns input character in AL
Return at DX the source stdin channel: 1: EXT, 2: COM, 4: Telnet, 8: User channel

Comments

Please note that AH does not contain the scan code, but is always 0.

Interrupt 0x10 service 0x01: Check if a character is available from std in

Check if a character is available from standard input

Parameters

AH

Must be 1.

Return Value

AX=1 if a character is available, AX=0 and zero-flag is cleared if no character is available.

Comments

Please note that AH does not contain the scan code, but is instead always 0.

Interrupt 0x10 service 0x08: Read character at cursor

Read character at cursor position, always returns 0

Parameters

AH

Must be 0x08

Return Value

AX = 0. (This function exists only for PC compatibility.)

Interrupt 0x10 service 0x0E: Teletype output

Write a character to the standard output.

Parameters

AH

Must be 0x0E

AL

Character to write

Return Value

Returns nothing.

Comments

This call returns immediately after space becomes available in the transmit ring buffer.
(The data transfer from the transmit ring buffer to the hardware transmitter is interrupt driven.)

Interrupt 0x10 service 0x0F: Get video state

Get video state

Parameters

AH

must be 0x0F

Return Value

number of screen columns, 80 in AH
mode currently set, 3 in AL
mode currently display page ,0 in BH

Interrupt 0x10 service 0x12: Video subsystem configuration

Video subsystem configuration

Parameters

AH

must be 0x12

Return Value

AX=0x0012
BX=0
CX=0

Interrupt 0x16 service 0x00: Get char from standard input

Get a character from std in, wait if none available

Parameters

AH

Must be 0.

Return Value

Returns character in AL
Returns at DX the source stdin channel of the character: 1: EXT , 2: COM , 4: Telnet

Comments

Please note that AH does not contain the scan code, but is always 0.

Interrupt 0x16 service 0x01: Check if a character is available from std in

Check if a character is available from standard input

Parameters

AH

Must be 1.

Return Value

AX=1 if a character is available, AX=0 and zero-flag is cleared if no character is available.

Comments

Please note that AH does not contain the scan code, but is always 0.

Interrupt 0xA0 service 0x00: Get serial number

Get the serial number of the IPC@CHIP device

Parameters

AH

Must be 0.

Return Value

AX=low word, BX=high word of IPC@CHIP serial number

CX=low word, DX=high word of BECK product serial number (if not available CX=DX=0)
SI contains BECK product hardware revision number HighByte and LowByte (if not available SI=0)
DI contains SCxxx hardware revision number HighByte and LowByte (if not available DI=0)

Comments

The serial number is a 24 bit value.

Interrupt 0xA0 service 0x01: Get IP address of the Ethernet interface

Get the IP address as a string.

Parameters

AH

Must be 1.

ES:DX

Pointer to a 16 byte memory area where the IP address is to be stored as a null terminated string.

Related Topics

Ethernet IP address initial value

Convert ASCII IP address to binary

Interrupt 0xA0 service 0x02: Set IP address of the Ethernet interface

Set the Ethernet interface's IP address based on the supplied string.

Parameters

AH

Must be 2.

ES:DX

Pointer to a 16 byte memory area where the IP address is stored as a null terminated string.

Comments

A new IP configuration must be activated by calling the ipeth command
or by calling the TCP/IP API interrupt 0xAC service 0x71 (RECONFIG_ETHERNET).

Important:
This API function writes to chip.ini and is not reentrant.
Don't use in different tasks or in combination with @CHIP-RTOS commands,
which are writing to chip.ini, e.g. DHCP.   Avoid race conditions with
any other API call which also writes or reads the chip.ini file.
e.g. service 0x23

Related Topics

TCP/IP API RECONFIG_ETHERNET service

Ethernet IP address initial value

IP command line

Convert binary IP address to ASCII dotted decimal

Interrupt 0xA0 service 0x03: Get IP subnet mask of the Ethernet interface

Get the IP subnet mask as a string.

Parameters

AH

Must be 3.

ES:DX

Pointer to a 16 byte memory area where the IP subnet mask is to be stored as a null terminated string.

Related Topics

Ethernet IP subnet mask initial value

Interrupt 0xA0 service 0x04: Set IP subnet mask

Set the IP subnet mask to the string supplied

Parameters

AH

Must be 4.

ES:DX

Pointer to a 16 byte memory area where the IP subnet mask is stored as a null terminated string.

Comments

A new IP configuration must be activated by calling the ipeth command
or by calling the TCP/IP API interrupt 0xAC service 0x71 (RECONFIG_ETHERNET).

Important:
This API function writes to chip.ini and is not reentrant.
Don't use in different tasks or in combination with @CHIP-RTOS commands,
which are writing to chip.ini, e.g. DHCP.   Avoid race conditions with
any other API call which also writes or reads the chip.ini file.
e.g. service 0x23

Related Topics

Ethernet IP subnet mask initial value

NETMASK command line

TCP/IP API documentation

Interrupt 0xA0 service 0x05: Get IP gateway

Get the IP gateway as a string.

Parameters

AH

Must be 5.

ES:DX

Pointer to a 16 byte memory area where the IP gateway is to be stored as a null terminated string.

Interrupt 0xA0 service 0x06: Set IP default gateway

Set the IP gateway to the string supplied

Parameters

AH

Must be 6.

ES:DX

Pointer to a 16 byte memory area where the IP gateway is stored as a null terminated string.

Comments

A new IP configuration must be activated by calling the ipeth command
or by calling the TCP/IP API interrupt 0xAC service 0x71 (RECONFIG_ETHERNET).

The TCP/IP stack of the IPC@CHIP supports only one valid default gateway for all device interfaces:

Ethernet, pppserver and pppclient.

The ipcfg command shows the current default gateway.

Important:
This API function writes to chip.ini and is not reentrant.
Don't use in different tasks or in combination with @CHIP-RTOS commands,
which are writing to chip.ini, e.g. DHCP.   Avoid race conditions with
any other API call which also writes or reads the chip.ini file.
e.g. service 0x23

Related Topics

Ethernet default gateway initialization

GATEWAY command line

ADD_DEFAULT_GATEWAY API function

PPP server default gateway initialization

Interrupt 0xA0 service 0x07: Execute a command shell command

Passes a command string to the command interpreter.

Parameters

AH

Must be 7.

ES:DX

Pointer to a null terminated command line.

Return Value

AX==0 success
AX==-1 error (loading EXE file failed!)

Comments

Internal commands are processed in the current task, external commands (.exe files) are loaded and executed in a new task.

Interrupt 0xA0 service 0x08: Set timer 0x1C's interval

Defines the interval in milliseconds for timer interrupt 0x1C.

Parameters

AH

Must be 0x08.

BX

Interval in milliseconds

Comments

Use setvect(0x1c, my_function) to change the interrupt vector.

Define your routine as:
         void interrupt my_function(void)

You must restore the old timer interrupt vector before ending the program.
Your interrupt routine must be as short as possible without any waiting or endless loops.
Avoid the usage of large C-library functions such as printf.

Related Topics

chip.ini TIMER 0x1C configuration

Interrupt 0xA0 service 0x09: Set timer interrupt 0xAF's interval

Defines the interval in milliseconds for timer interrupt 0xAF.

Parameters

AH

Must be 0x09.

BX

Interval in milliseconds

Comments

Use setvect(0xAF, my_function) to change the interrupt vector.

Define your routine as:
         void interrupt my_function(void)

You must restore the old timer interrupt vector before ending the program.
Your interrupt routine must be as short as possible without any waiting or endless loops.
Avoid the usage of large C-library functions such as printf.

Related Topics

chip.ini TIMER 0xAF configuration

Interrupt 0xA0 service 0x11: Set STDIO focus

Set the focus of STDIO to either console, application or both

Parameters

AH

Must be 0x11

AL

1: command shell (console), 2: Application, 3: both

Comments

If your application requires input from the user, you should set the focus to the application.
You should assure that only one application requests input from STDIO.
The user can change the focus by using the focus hot key (default Ctrl-F).
Changing the focus clears the serial input and output queues immediately.

Important :

All buffered incoming and outgoing characters in the internal serial
send and receive queues are lost after this call.

Related Topics

Focus key definition

Interrupt 0xA0 service 0x12: Get bootstrap version number

Get the version number of the bootstrap loader.

Parameters

AH

Must be 0x12

Return Value

AX=version number, AH is major version, AL is minor version.

Comments

Example:

If the function returns 0x0100 in AX, this means that you have version 1.00.

Interrupt 0xA0 service 0x13: Get @CHIP-RTOS version number

Get the version number of the @CHIP-RTOS.

Parameters

AH

Must be 0x13

Return Value

AX=version number, AH is major version, AL is minor version.
If DX is set it is a Beta version.

Comments

Example:

If the function returns 0x0100 in AX, this means that you have version 1.00.

Interrupt 0xA0 service 0x14: Set batch file execution mode.

Sets the batch file execution mode of DOS programs for either concurrent or sequential execution.
See BATCHMODE initialization documentation for details.

Parameters

AH

Must be 0x14

AL

AL = 0:    (Selects default BATCHMODE=0, = concurrent)

AL = 1:    (Sets BATCHMODE=1, = sequential)

BX

BX = 0:    Disable the max. delayed execution timeout of DOS programs

BX = 1:    Enable the max. delayed execution timeout of DOS programs at a batchfile, if BATCHMODE=1

Return Value

returns nothing

Comments

Important:

If  BATCHMODE=1 take care that every program in your batch file which has a successor
program either exits (int21h 0x4C) or terminates resident with int21h 0x31.
A program which runs forever should call BIOS Interrupt 0xA0 Service 0x15, which immediately enables the further batch file sequencing.
By default the maximum delay time for execution of the next listed program in the batch file is 15 seconds.
If BX is set to 0, the successor program in a batch file waits forever for execution, if the predecessor program
does not finish or call 0xA0 Service 0x15

Related Topics

Initial batch mode configuration

BATCHMODE command

Interrupt 0xA0 service 0x15: Allow immediate further batch file execution in BATCHMODE 1.

This call allows the next program listed in a batch file to start execution.
This is implemented by waking up a batch file execution task which dispatches any
subsequent program listed in the batch file.

Parameters

AH

Must be 0x15

Return Value

returns nothing

Related Topics

Initial batch mode configuration

Run-time batch mode selection

Interrupt 0xA0 service 0x16: Get information about the @CHIP-RTOS features

Get information about running servers, interfaces and features of the @CHIP-RTOS

Parameters

AH

0x16

Return Value

Bits of AX, BX and DX indicate the services or devices available, coded as:

Bit=0: service or device is not available.
Bit=1: service or device is available.

AX:

Bit 0: Ethernet device for TCP/IP
Bit 1: PPP server
Bit 2: PPP client
Bit 3: Web server
Bit 4: Telnet server
Bit 5: FTP server
Bit 6: TFTP server
Bit 7: DHCP client

BX:

Bit 0: SNMP MIB variables support (see TCP/IP API service 0x71)
Bit 1: UDP config server
Bit 2: Ping client (see TCP/IP API service 0x75)
Bit 3: TCP/IP device driver API(see TCP/IP API service 0xA0 - 0xA7)
Bit 4: Webfile upload (Webserver PUT method)

DX:

Bit 0: I2C-Bus API
Bit 1: Hardware API
Bit 2: RTOS API
Bit 3: Packet driver interface for Ethernet
Bit 4: Serial XMODEM file transfer
Bit 5: External disk interface
Bit 6: Software SPI API

Interrupt 0xA0 service 0x17: Get MAC address of the Ethernet interface

Get the MAC address as a 6 Byte array.

Parameters

AH

Must be 0x17.

ES:DX

Pointer to a 6 byte memory area where the MAC address is to be stored.

Comments

At IPC@CHIP targets without internal Ethernet (e.g. SC11), this number represents a virtual ID.

Interrupt 0xA0 service 0x18: Power save

Slows down the internal timer for the RTOS and puts the CPU in a halt mode until the next interrupt occurs. Please note that the internal time/date will be affected.

Parameters

AH

Must be 0x18.

Comments

Call this function when your program is in idle state.
Power savings are marginal since we use a DRAM. Please note that power consumption may differ slightly when the date code of the IPC@CHIP is changed.

Interrupt 0xA0 service 0x19: Change level for configuration server.

Change the supported level for the configuration server.   For a description of the possible levels, please refer to config.htm document.

Parameters

AH

Must be 0x19.

BX

The supported level.

Comments

Please note that if the level defined in the chip.ini is 0 (zero), the configuration server task is not started and changing the supported level does not have any effect. To avoid this, use a unlisted support level such as 0x1000 in the chip.ini.
The entry in the chip.ini file is not changed by this call.

Interrupt 0xA0 service 0x20: Install a user fatal error handler

Install a user fatal error callback function.   This installed function will be called by the system on execution of fatal errors.  

Parameters

AH

Must be 0x20.

ES:DI

Address of the user error handler function (or zero to remove a previously installed handler).

Comments

The user is permitted to execute an error handler function if a fatal error occurs in either an application program or the @CHIP-RTOS.

Note that this mechanism will (of course) fail if the user error handler code is itself overwritten (corrupt).

Only one error handler callback per system is supported.   An application can remove its handler by calling this install function with a zero (NULL) value in ES:DI, which is an advisable clean-up procedure at program exit.

The callback function must be of type huge _pascal with an errorcode input parameter (see the example function below).   The error codes conveyed by this input parameter are as follows:

1: Invalid processor opcode (usually caused by corrupted memory).   The current task will be suspended.
2: Fatal kernel error (usually caused by corrupted memory or a task stack overflow)
3: Fatal internal TCP/IP error, current task will be suspended
4: TCP/IP stack reaches memory limit
5: TCP/IP memory allocation error
6: Ethernet bus error (hardware decfect)
7: Ethernet link error detected (cable not connected?)
8: Flash write error -> Flash defect ( Note:    IPC@CHIP is no longer usable)
9: Low Memory error -> called if a memory allocation (system or user) failed.

In all cases (except errorcode 6,7 and 9) we recommend a reboot with BIOS interrupt 0xA0 0x21.

Important:    Do not use any message printing inside your error handler if error code is 3 or 4,
because when Telnet is part of your stdio, your exit handler will hang inside the print call.

// Example for Borland C:  This error handler reboots the system

void huge _pascal user_error_handler(int errorcode)

{

   union  REGS  inregs;

   union  REGS  outregs;



   // e.g. resetting outputs

   outportb(0x600,0x00);



   // rebooting the IPC@CHIP

   inregs.h.ah = 0x21;

   int86(0xA0,&inregs,&outregs);

}



// Installing the error handler function from program's main function

inregs.h.ah=0x20;

sregs.es   =FP_SEG(user_error_handler);

inregs.x.di=FP_OFF(user_error_handler);

int86x(0xA0,&inregs,&outregs,&sregs);

Interrupt 0xA0 service 0x21: Rebooting the IPC@CHIP

This function works in the same way as the reboot shell command

Parameters

AH

0x21

Return Value

No return from this function occurs due to system reboot.

Interrupt 0xA0 service 0x22: Get version string

Copies the @CHIP-RTOS version information in to a text buffer.   The string is null terminated.

Parameters

AH

Must be 0x22

CX

Buffer length, including space for null terminator

ES

Segment of memory buffer for the string

DI

Offset of memory buffer for the string

Related Topics

VER shell command

Interrupt 0xA0 service 0x23: Insert an entry in chip.ini

The functions 0x23 and 0x24 allows the user to modify/place and find/read
your own chip.ini entries.

Parameters

AH

Must be 0x23.

BX:SI

Pointer to section string (max. 40 chars)

ES:DI

Pointer to item name (max. 40 chars)

DS:DX

Pointer to item text (max. 128 chars)

Return Value

AX=0 success , AX=-1 invalid string length

Comments

Important:    The API functions 0x23 and 0x24 are not reentrant.
Don't use in different tasks or in combination with @CHIP-RTOS commands,
which are writing to chip.ini e.g. DHCP. Avoid race conditions with
any other API call, which writes or read also to/from chip.ini
e.g. service 0x02

Example (tested with Borland C/C++ 5.02):

int iniPutString(char *sectionName, char *itemName, char *text)

{

  union  REGS  inregs;

  union  REGS  outregs;

  struct SREGS sregs;



  inregs.h.ah = 0x23;

  inregs.x.bx = FP_SEG(sectionName);

  inregs.x.si = FP_OFF(sectionName);

  sregs.es    = FP_SEG(itemName);

  inregs.x.di = FP_OFF(itemName);

  sregs.ds    = FP_SEG(text);

  inregs.x.dx = FP_OFF(text);

  int86x(0xA0,&inregs,&outregs,&sregs);

  return outregs.x.ax;

}

//Call of this function:

iniPutString("MY_SECTION", "MY_ITEM", "VALUE_TEXT");

//and produces the following chip.ini entry

[MY_SECTION]

MY_ITEM=VALUE_TEXT

<nl>

---

Developer Notes

Top of list
Index page

Interrupt 0xA0 service 0x24: Find an entry in chip.ini

Finds an entry in chip.ini configuration file.

Parameters

AH

Must be 0x24.

CX

Maximum length of target string (without '\0').

BX:SI

Pointer to section string

ES:DI

Pointer to item name

DS:DX

Pointer to target

Return Value

AX= 0 : Entry not found
AX= -1: Could not open chip.ini
else Success: pointer at DS:DX contains the found string AX contains length of the found string

Comments

Important:    API functions 0x23 and 0x24 are not reentrant.
Don't use in different tasks or in combination with @CHIP-RTOS commands,
which are writing to chip.ini, e.g. DHCP.   Avoid race conditions with
any other API call, which writes or read also to/from chip.ini
e.g. 0xA0 0x02 Set IP address
The maximum length value in CX specifies the number of characters which could be copied into the target string.   You have to allocate one more character for the null termination.

Example (tested with Borland C/C++ 5.02):

int iniGetString(char *sectionName, char *itemName, char *target, int maxlen)

{

   union  REGS  inregs;

   union  REGS  outregs;

   struct SREGS sregs;



   inregs.h.ah = 0x24;

   inregs.x.bx = FP_SEG(sectionName);

   inregs.x.si = FP_OFF(sectionName);

   sregs.es    = FP_SEG(itemName);

   inregs.x.di = FP_OFF(itemName);

   inregs.x.cx  = maxlen;

   sregs.ds    = FP_SEG(target);

   inregs.x.dx = FP_OFF(target);

   int86x(0xA0,&inregs,&outregs,&sregs);

   return outregs.x.ax;

}

// Declare a target buffer to be filled by iniGetString().

unsigned char target[101];



iniGetString("MY_SECTION", "MY_ITEM", target, 100);

// Now target contains the chip.ini text for this item

Interrupt 0xA0 service 0x25: Set the Stdio focus key

Set the Stdio focus key

Parameters

AH

Must be 0x25.

AL

Focus key character (default CTRL-F, ASCII 6)

Return Value

Returns nothing

Comments

By default, the focus key is set to CTRL-F (ASCII 6)
At runtime, the pressed key Ctrl-F toggles between these three modes
and shows the current mode.

Key Range:     0..254

If the key is set to zero, the switching of stdio is disabled.
The focus key is not usable by the command shell or dos executable.

Related Topics

Focus key definition

Interrupt 0xA0 service 0x26: Get the IPC@CHIP device names

Get the IPC@CHIP device names

Parameters

AH

Must be 0x26.

Return Value

AX=0
ES:DI contains pointer to the fixed IPC@CHIP device name stored at the IPC@CHIP flash
BX:SI contains pointer to the device name configured at chip.ini.

DX:CX contains pointer to the fixed BECK product name stored in the IPC@CHIP flash

Comments

All returned strings are terminated by 0.   These strings should be treated as read only.

Related Topics

Device name definition

Interrupt 0xA0 service 0x27: Suspend/Resume System Servers

Suspend/Resume FTP, Telnet or Web Server

Parameters

AH

Must be 0x27.

AL

0: Resume, 1: Suspend

BX

0: FTP Server, 1: Telnet Server, 2: Web Server

Return Value

AX=  0:   Success
AX=  1:   Server was already in the postulated state
AX= -1:   Invalid Parameter

Comments

If FTP, Telnet or WEB was disabled at startup with a CHIP.INI entry, you can enable it using this call.

Interrupt 0xA0 service 0x28: Fast Findfirst

Provide a faster access to the file system directories

Parameters

AH

Must be 0x28.

CX

File attribute

BX:SI

Null terminated file specification

ES:DI

Pointer to filefind structure

Return Value

AL=   1 DX=0: Success
AL=   0 DX=0: No file found
DX= -1: Findfirst already active

Comments

The three filefind functions (0x28 - 0x30) provide a faster Findfirst/next access than the DOS compatible functions at INT 21h.   They work in a manner similar to the INT 21h Findfirst/next functions.   You must first call Findfirst (0x28).   After that call, you can call Findnext (0x29) as much as you need.   To get the entire directory call repeatedly until Findnext returns an error.   The directory being searched will be locked for exclusive access by the calling task.   To unlock the directory you have to call Finddone (0x30).

Note:   Only a successful call of this function (file found) must be later terminated by a call of the Fast Finddone function!
These functions (0x28 - 0x30) are not reentrant, do not call findfirst/findnext sequences from different tasks without semaphore protection.

The filefind structure is defined as follows:

typedef struct filefind

{

     char               filename[12];       // Null terminated filename

     char               fileext[4];         // and extension

     unsigned short int fileattr;           // MS-DOS file attributes

     short int          reserved;           // Reserved

     struct tag_filetimestamp

     {

        unsigned short int filedate;        // Date = ((year - 80) shl 9) or (month shl 5)) or day

        unsigned short int filetime;        // Time = (hour shl 11) or (min shl 5)) or (sec / 2)

     } filetimestamp;                       // Time & date last modified

     unsigned long      filesize;           // File size

     char               private_field[180]; // Reserved, used internal

}

Related Topics

Fast Findnext

Fast Finddone must be called at end of the search

Interrupt 0xA0 service 0x29: Fast Findnext

Continues a search which was started by Fast Findfirst (0x28)

Parameters

AH

Must be 0x29.

ES:DI

Pointer to filefind structure

Return Value

AL=  1 DX=0: Success
AX=  0 DX=0: no file found
DX= -1: Findfirst not called before

Comments

See Fast Findfirst function (0x28) for description.

Note:   Successful calls of this function (filefind) must be eventually terminated by a call to the Fast Finddone function!

Related Topics

Fast Findfirst must be called to start the search

Fast Finddone must be called at end of the search

Interrupt 0xA0 service 0x30: Fast Finddone

Closes a find access started with Fast Findfirst, thereby allowing a subsequent Fast Findfirst operation.

Parameters

AH

Must be 0x30.

ES:DI

Pointer to filefind structure

Return Value

AX=0 DX=0:   Success
DX= -1:   Findfirst not active

Comments

See Fast Findfirst function (0x28) for description.

Note:  This function must be called to close a find operation following a successful call to Fast FindFirst!   Otherwise further attempts to use the Fast FindFirst function will fail.

Related Topics

Fast Findfirst

Fast Findnext

Interrupt 0xA0 service 0x31: Detect Ethernet link state

Detect Ethernet link state

Parameters

AH

Must be 0x31.

Return Value

AX=0: Link ok
AX!=0: No Link (no cable connected?)
DX!=0: Initialization or reset procedure of Ethernet device failed

SC13 only: CX holds the current Phy status

CX register Phy status word bit definitions (SC13 only):

Bit 14    1 = Link Not detected

Bit 07    1 = 100Base-TX mode, 0=10Base-T mode

Bit 06    1 = Device in Full Duplex mode

Top of list
Index page

Interrupt 0xA0 service 0x32: Set a memory gap between the loaded DOS programs

Sets a memory gap between loaded DOS programs as a memory reserve.

Parameters

AH

Must be 0x32.

BX

Number of paragraphs (range between 0 to 2048 paragraphs).

Return Value

AX=0 DX=0: Success
AX=-1: Invalid value found in BX

Comments

Some programs compiled with Borland C 5.02 (other compilers??) try to increase their program memory block at runtime.   This can occur, for example, when opening a file with Borland C-library function fopen, where some additional memory is required.   The Borland C-library fopen function calls int 21h 0x4A, which is not directly visible to the application programmer.   This memory resize call fails if another program is loaded after the previous one, because now there is no memory space left for increasing the memory size of the previously executed program.   The program then returns from fopen with an error.   In this case, the global program variable errno is set to value 8 (not enough memory).

To prevent this error, the @CHIP-RTOS allows a memory gap of a defined size between loaded programs.   This memory gap size is specified as a number of paragraphs (where 1 paragraph == 16 Bytes).

This value can also be defined in chip.ini.

Note:   This strategy can fail when programs are terminated and restarted again.  

---

Developer Notes

Top of list
Index page

Interrupt 0xA0 service 0x33: Set stdin/stdout channel

Set the stdin/stdout channel

Parameters

AH

Must be 0x33.

AL

Bit 0 = 1 set stdout, Bit 1 = 1 set stdin

BX

Channel bits, see comment

Return Value

AX=0 DX=0: Success
AX=DX=-1: Invalid parameter

Comments

Channel bits for BX register:
Bit 0: Serial port 0 (PORT EXT)
Bit 1: Serial port 1 (PORT COM)
Bit 2: Telnet server
Bit 3: User channel

Setting a bit to zero deactivates this channel, setting a bit to one activates the specified channel

Interrupt 0xA0 service 0x34: Get stdin/stdout settings

Get the stdin/stdout settings

Parameters

AH

Must be 0x34.

Return Value

AX=0, BX contains stdout settings, CX: stdin settings

Comments

Return values
Bit 0 == 1: Serial port 0 (EXT)
Bit 1 == 1: Serial port 1 (COM)
Bit 2 == 1: Telnet server
Bit 3 == 1: User channel

Interrupt 0xA0 service 0x35: Install user specific stdio handlers

Installs user specific stdio channel handlers.

This API call allows the user to install their own stdio handler functions, e.g. for a user developed input/output device connected to the IPC@CHIP (e.g. a display and/or keyboard device) or a user TCP application similar to Telnet.

The user must implement inside of their application four functions for reading and writing characters from/to their stdin/stdout device.

After installing these functions with this API call and setting stdin and/or stdout to include the user channel with Set stdio channels, the @CHIP-RTOS will call these user functions at each stdin and stdout operation.   For further details on programming and installing these handler functions, see the comments below.

Parameters

AH

Must be 0x35.

ES:DI

Pointer to User_Stdio_Funcs structure variable, see comments

Return Value

AX=0 DX=0: Success

Comments

Necessary type definitions:

typedef int (huge *User_Kbhit)(void);
typedef void (huge *User_PutCh)(char chr);
typedef void (huge *User_PutStr)(char * pch, int n);
typedef int (huge *User_Getch)(void);


typedef struct tag_user_stdio
{
         User_Kbhit user_kbhit;
         User_Getch user_getch;
         User_PutCh user_putch;
         User_PutStr user_putstr;
}User_Stdio_Funcs;

Functions to be implemented by the user:

int huge user_kbhit(void);     // returns 1 ,if a character is available, 0 if not
int huge user_getch(void);     // read a char from stdin (wait, if none available)
void huge user_putch(char chr);     // write a single char to stdout
void huge user_putstr(char * pch, int n);    // write a string with n chars to stdout

The user must set the four callback function vectors in their User_Stdio_Funcs type variable and then call this API function with the address of the User_Stdio_Funcs structure in ES:DI.

With ES = DI = 0, the user can later uninstall their stdio handlers.

Important:
1. If your applications exits, don't forget to uninstall your stdio handlers, by calling this API call with ES=DI=0.
2. Do not call your implemented stdio functions from inside your application.   These installed functions must be called only from inside the @CHIP-RTOS.

Example (Borland C):

User_Stdio_Funcs user_stdio_funcs;    // global variable



// Implementation of users stdio functions

int  huge my_kbhit(void)

{

  //........

}



int huge my_getch(void)

{

  //........

}



void huge my_putch(char chr)

{

  //........

}



void huge my_putstr(char * pch, int n)

{

  //.......

}



void install_mystdio_channel(void)

{

   union  REGS  inregs;

   union  REGS  outregs;

   struct SREGS sregs;



   user_stdio_funcs.user_kbhit  = my_kbhit;

   user_stdio_funcs.user_getch  = my_getch;

   user_stdio_funcs.user_putch  = my_putch;

   user_stdio_funcs.user_putstr = my_putstr;



   inregs.h.ah=0x35;

   sregs.es   =FP_SEG(&user_stdio_funcs);

   inregs.x.di=FP_OFF(&user_stdio_funcs);

   int86x(0xA0,&inregs,&outregs,&sregs);

}



void remove_mystdio_channel(void)

{

   union  REGS  inregs;

   union  REGS  outregs;

   struct SREGS sregs;



   inregs.h.ah=0x35;

   sregs.es   = 0;

   inregs.x.di= 0;

   int86x(0xA0,&inregs,&outregs,&sregs);

}



unsigned int set_stdio_channel(unsigned int channels)

{

	union  REGS  inregs;

	union  REGS  outregs;



	inregs.h.ah=0x33;

	inregs.h.al=3;   //set both: stdin and stdout

	inregs.x.bx = channels;

	int86(0xA0,&inregs,&outregs);

	return outregs.x.ax;

}



int main(void)

{

  //......

  install_mystdio_channel();

  set_stdio_channel(0x0E);  // COM,TELNET,USER

  //....



  // at the end of the program



  set_stdio_channel(0x06);  // COM,TELNET

  remove_mystdio_channel():

}

Interrupt 0xA0 service 0x36: Install a System Server Connection Handler function

Installs a user specific System Server Connection Handler function.
The handler function will be called if a client establishes a connection.   This functions allows application programmers to implement their own callback functions for controlling access to the default @CHIP-RTOS servers.

Parameters

AH

Must be 0x36.

BX

0: FTP Server, 1: Telnet Server, 2: Web Server

ES:DI

Pointer to handler function

Return Value

AX=0: Success
AX=-1: Invalid Parameter

Comments

A connection handler function must be declared in the following manner:

int huge UserConnectionHandler( struct sockaddr_in *sockptr );

The connection handler will be called when a client establishes a connection to the server (FTP, WEB, Telnet).   The handler can read the IP Address and the Port in the sockaddr_in struct . (If desired, the IP address in the sin_addr structure member can be converted to ASCII using the TCP/IP API_INETTOASCII function.)   If the handler returns 0 the connection will be established.   If it returns a nonzero value, the connection will be aborted.

To uninstall a connection handler call this function with a null pointer (ES=DI=0).

Example usage:

The implemented handler function can check the source IP address (Clients IP), compare this IP with an application internal list of allowed IP addresses.   The connection can then be rejected by returning a non-zero value if the source IP is not a member of the list.

Interrupt 0xA0 service 0x37: Enable/Disable File sharing

Enable disable File sharing of Int21h open/create

Parameters

AH

Must be 0x37.

AL

0: set mode, 1: get mode

BX

0: disable, 1: enable (Sharing mode)

Return Value

AX=0: Success, contains Sharing mode if al=1
AX=-1: Invalid Parameter

Comments

By default file sharing is disabled.   This has the effect that a file which is opened for write access can't be opened a second time for read or write access.   Also a file which is opened for read access can only be opened for read access a further time.

To avoid this security feature you can enable file sharing.   This can also be done with the CHIP.INI entry FILESHARING.

NOTE:   Be careful when opening a file multiple times with one or more of the openings done with write access!

Interrupt 0xA0 service 0x38: Get file name by handle

Returns the file name string corresponding to a specified file handle.

Parameters

AH

Must be 0x38.

CX

File handle

ES:BX

pointer to string, must be 13 chars long (12 + Null termination)

Return Value

AX=0: Success, contains Sharing mode if al=1
AX=-1: Invalid file handle

Interrupt 0xA0 service 0x40: Install a UDP Cfg Callback

Install a UDP Config Server User Callback function.

Parameters

AH

Must be 0x40.

ES:DI

Pointer to the User Callback function

Comments

This API Function installs a User Callback function for the UDP Config Server.   If a UDP Cfg Request with the command number 06 arrives, this User Callback function will be called.   This allows you to realize your own UDP Config sub protocol and commands.   The UDP Cfg Callback function receives an argument with information about the UDP Cfg Request and its requester.   This information structure and the function must be declared as specified in the description below:

typedef struct UdpCfgSrv_UserCBInfo
{
    int length;                     // Length of this struct
    struct sockaddr_in *fromAddrPtr;    // Sender address pointer
    int udpCfgSD;                // UDP Config Server's Socket Descriptor
    char *dataPtr;               // Data of Request package
    unsigned dataLength;         // Length of request package
};

void huge MyUdpCfgSrvCB( struct UdpCfgSrv_UserCBInfo *infoPtr );

If the callback function returns with the dataPtr and dataLength fields in the UdpCfgSrv_UserCBInfo structure both non-zero, the UDP Config Server will send the dataLength bytes from location referenced by dataPtr back to the requester.   If the pointer is set to null or the dataLength field is set to 0, no data will be sent back to the requester.

To remove an installed callback function, call this function with a null pointer.

For more Information on the UDP Config Server and its protocol, refer to the UDP Config Server description available on our website.

Note:   The data sent and received is limited to 300 bytes maximum.

Interrupt 0xA0 service 0x45: Write persistent User Data

Writes persistent data into the Flash memory of the @CHIP

Parameters

AH

Must be 0x45.

ES:SI

Pointer to the User data

CL

number of bytes to write (max 192)

Comments

The user can use this function to save product specific persistent data (e.g. own serial number of the product).
The function requires a pointer in [es:si] to memory block, which should be written into the flash memory.
The 192 bytes array in the flash memory will be untouched on a format of the file system and also on an @CHIP-RTOS BIOS Update.

Related Topics

Read persistent User Data

Interrupt 0xA0 service 0x46: Read persistent User Data

Reads persistent data from the Flash memory of the @CHIP

Parameters

AH

Must be 0x46.

ES:DI

Pointer to the User buffer

CL

number of bytes to read (max 192)

Comments

The user can use this function to read product specific persistent data written with function 0x45 (Write Persistent User Data).
The function requires a pointer [es:di] to the memory block into which the read data will be stored.

Related Topics

Write persistent User Data

Interrupt 0xA0 service 0x50: Get IP address of the PPP Server

Get the IP address as a string.

Parameters

AH

Must be 0x50.

ES:DX

Pointer to a 16 byte memory area where the IP address is to be stored as a null terminated string.   If no PPP IP address is set (e.g. no link is established) this function returns an empty string.

Interrupt 0xA0 service 0x55: Get IP address of the PPP Client

Get the IP address as a string.

Parameters

AH

Must be 0x55.

ES:DX

Pointer to a 16 byte memory area where the IP address is to be stored as a null terminated string.   If no PPP IP address is set (e.g. no link is established) this function returns an empty string.

Interrupt 0xA0 service 0x56: Get sprintf address

Get the address of the internal RTOS sprintf function.

Parameters

AH

Must be 0x56.

Return Value

AX=0
ES:DI points to the internal sprintf function of the @CHIP-RTOS

Comments

This function is used by our Clib library to provide a printf function for user applications.