@CHIP-RTOS - BIOS Interface Documentation

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.

BIOS API Data Structures

BIOS Interrupt 0x10 Services

BIOS Interrupt 0x11 Services

BIOS Interrupt 0x16 Services

BIOS Interrupt 0x1A Services

BIOS Interrupt 0xA0 Services

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.

Supported since or modified in @CHIP-RTOS version

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

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.

Supported since or modified in @CHIP-RTOS version

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

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.

Supported since or modified in @CHIP-RTOS version

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

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.

Supported since or modified in @CHIP-RTOS version

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

Read character at cursor position, always returns 0

Parameters

AH

Must be 0x08

Return Value

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

Supported since or modified in @CHIP-RTOS version

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

Write character to the standard output.

Parameters

AH

Must be 0x09

AL

Character to write

Return Value

Returns nothing.

Comments

This function exists only for PC compatibility. At old DOS PCs this functions writes a character with specified attributes at the current cursor position. At the @CHIP-RTOS this function works in the same way than service 0x0E

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.20	V1.20	V1.20	V1.01	V1.00

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.)

Supported since or modified in @CHIP-RTOS version

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

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

Supported since or modified in @CHIP-RTOS version

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

Video subsystem configuration

Parameters

AH

must be 0x12

Return Value

AX=0x0012
BX=0
CX=0

Supported since or modified in @CHIP-RTOS version

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

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, 8: User channel

Comments

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

Supported since or modified in @CHIP-RTOS version

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

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.

Supported since or modified in @CHIP-RTOS version

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

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.

Supported since or modified in @CHIP-RTOS version

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

Get the IPv4 address as a string.

Parameters

AH

Must be 1.

ES:DX

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

Beck C-Library Usage

Get_IPConfig()

Related Topics

Ethernet IPv4 address initial value

Ethernet IPv6 address initial value

Convert ASCII IPv4 address to binary

Supported since or modified in @CHIP-RTOS version

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

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

Parameters

AH

Must be 2.

ES:DX

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

Comments

This API is thread safe and reentrant.

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).

Beck C-Library Usage

Set_IPConfig()

Related Topics

TCP/IP API RECONFIG_ETHERNET service

Ethernet IPv4 address initial value

Ethernet IPv6 address initial value

IPv4 address IP command line

Convert binary IPv4 address to ASCII dotted decimal

Supported since or modified in @CHIP-RTOS version

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

Get the IPv4 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.

Beck C-Library Usage

Get_IPConfig()

Related Topics

Ethernet IP subnet mask initial value

Supported since or modified in @CHIP-RTOS version

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

Set the IPv4 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

This API is thread safe and reentrant.

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).

Beck C-Library Usage

Set_IPConfig()

Related Topics

Ethernet IP subnet mask initial value

NETMASK command line

TCP/IP API documentation

Supported since or modified in @CHIP-RTOS version

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

Get the IPv4 gateway as a string.

Parameters

AH

Must be 5.

ES:DX

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

Beck C-Library Usage

Get_IPConfig()

Related Topics

Ethernet default gateway initialization

GATEWAY command line

ADD_DEFAULT_GATEWAY API function

PPP server default gateway initialization

Supported since or modified in @CHIP-RTOS version

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

Set the IPv4 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

This API is thread safe and reentrant.

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.

Beck C-Library Usage

Set_IPConfig()

Related Topics

Ethernet default gateway initialization

GATEWAY command line

ADD_DEFAULT_GATEWAY API function

PPP server default gateway initialization

Supported since or modified in @CHIP-RTOS version

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

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.

Supported since or modified in @CHIP-RTOS version

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

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

Supported since or modified in @CHIP-RTOS version

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

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

Supported since or modified in @CHIP-RTOS version

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

Reports disk size and space.

Parameters

AH

Must be 0x0A.

AL

Drive (0 current drive, 1=A:,..,26=Z:)

ES:BX

Pointer to BiosDiskInfo data structure containing disk drive statistics which will be filled in by this API call.

Comments

This API is provided as an alternative to the DOS interrupt 0x21 service 0x36 "Get Disk Free Space" service.   For large drives whose sector counts exceed 0xFFFF, this alternative API provided here should be used.

Beck C-Library Usage

BIOS_Disk_Info() - Get disk information

BIOS_Disk_Space() - Get disk space

Related Topics

DOS service 0x36 Get Disk Free Space

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.23	V1.23	V1.23	V1.16	V1.00

Passes a command string to the command interpreter.

Parameters

AH

Must be 0x0B.

ES:BX

Pointer to a null terminated command line.

DX:CX

Pointer to a command specific feedback data structure.

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.

The report structure referenced by DX:CX will be output to by only the following select commands:

• COPY - report data structure CmdFeedbackS
  
  
• FORMAT - report data structure CmdFeedbackS
  
  
• external commands (.exe files) - The invoked program can access the object at report using the progParentData() function.    The format of this object is user defined, however the first two integer values must correspond to the ProgFeedbackS data structure.   For compatibility with future @Chip-RTOS versions, the first integer (unsigned) of this user defined structure should be set to the size of this user structure. The second integer (signed) will be set to the program's DOS exit code value. The remainder of the structure following these two required integer values can be what ever the user desires.

The DX:CX argument is ignored by any other command.

Caution:

When another program is invoked using this API, the data area referenced by DX:CX must persist until that invoked program terminates. The @Chip-RTOS will write the program's exit code to the second 16 bit location within this referenced memory when the invoked program terminates.

Beck C-Library Usage

BIOS_ExecuteExt() - Execute extended

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V1.35	V1.35

The specified disk drive will be closed.

Parameters

AH

Must be 0x0C.

ES:BX

Pointer to a null terminated ASCII drive specifier, for example "B:".

CX

Bit field to request special actions:

• BDC_SAVE_1_FAT = 0x1 - Save only one copy of the File Allocation Table (FAT) in order to save time.
  
• BDC_ABORT_READ_WRITE = 0x2 - Cut short any read/write activity currently in progress, so that drive can be closed with a minimum of delay.
  

These bit flags may be OR'ed together.   Undefined bits should be set zero for compatibility with future versions.

Return Value

AX register contains status:

AX = 0 - Successful
AX = -1 - Invalid path or drive was already closed.

Comments

The ASCII drive specifier in [ES:BX] cannot be empty.   (No provision is offered by this API to specify a default drive.)

Beck C-Library Usage

BIOS_Disk_Close() - Close disk

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V1.40	V1.40

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

Supported since or modified in @CHIP-RTOS version

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

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.

Related Topics

Get @CHIP-RTOS version number

Supported since or modified in @CHIP-RTOS version

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

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.

Related Topics

Get bootstrap version number

Get version string

Get device name

Supported since or modified in @CHIP-RTOS version

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

Sets the batch file execution mode of 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 in a batch file, 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

Supported since or modified in @CHIP-RTOS version

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

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

Supported since or modified in @CHIP-RTOS version

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

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
Bit 8: IPv6 support
Bit 9: SSL Web server

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
Bit 7: CAN-Bus API
Bit 8: USB API

Supported since or modified in @CHIP-RTOS version

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

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.

Supported since or modified in @CHIP-RTOS version

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

SC12:

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.

SC11/SC13/SC1x3/SC2x:

Slows down the processor clock and puts the CPU in a power save mode until the restore function is called or in halt mode until the next interrupt occurs.   Please note that the internal time/date will be affected in some modes.

Parameters

AH

Must be 0x18.

SC11/SC13 Parameters

AL

Mode
If DX == 0xABCD and CX == 0x1234
    AL == 0x01: Restore full speed mode
    AL == 0x02: Set 1/2 speed mode
    AL == 0x04: Set 1/4 speed mode (serial baud rates > 57600 will no longer be accurate)
    AL == 0x80: Enter sleep mode (RTOS 1ms timer and time/date will be affected)
    AL == 0x81: Wakeup from sleep mode
    AL == 0x20: Power down Ethernet controller (no Ethernet communication is possible)
    AL == 0x21: Power up Ethernet controller
Else
    Put the CPU in halt mode until next interrupt occurs.
    Please note that the internal time/date will be affected.
    Call this function when your program is in idle state.
    Power savings are marginal.
Endif

CX

Set to 0x1234 if using AL as mode specifier

DX

Set to 0xABCD if using AL as mode specifier

SC1x3/SC2x Parameters

AL

Mode
If DX == 0xABCD and CX == 0x1234
    AL == 0x01: Restore full speed mode
    AL == 0x02: Set 1/2 speed mode
    AL == 0x04: Set 1/4 speed mode
    AL == 0x20: Power down Ethernet controller (no Ethernet communication is possible)
    AL == 0x21: Power up Ethernet controller
    AL == 0x22: Disable the Ethernet Energy Detect Power-Down mode
    AL == 0x23: Enable the Ethernet Energy Detect Power-Down mode
Else
    Put the CPU in halt mode until next interrupt occurs.
    Please note that the internal time/date will be affected.
    Call this function when your program is in idle state.
    Power savings are marginal.
Endif

CX

Set to 0x1234 if using AL as mode specifier

DX

Set to 0xABCD if using AL as mode specifier

SC11/SC13/SC1x3/SC2x Return Value

AX==0, if successful (only when DX==0xABCD and CX==0x1234)

Comments

Please note that power consumption may differ slightly when the date code of the IPC@CHIP® is changed.

SC12 Comments

Call this function when your program is in idle state.   Power savings are marginal since we use a DRAM.

SC1x3/SC2x Comments

In mode 0x23 the Ethernet PHY is partially powered down.   The PHY powers-up when there is valid energy from the line: 100Base-TX, 10 Base-T or auto negotiation.
If the user calls this function with AL==4 (Set 1/4 speed mode), the internal ethernet controller doesn't work in the 100 MBit mode. Because of this behaviour, it is recommended to set the ethernet mode at chip.ini fix to 10MBit Halfduplex.

The modes 0x02 and 0x04 influence the USB API. In mode 0x02 the USB API cannot be used at all. The SC1X3 will crash if you do. In mode 0x04 the USB API can only be used in Device mode, because Host mode needs better performance.

Supported since or modified in @CHIP-RTOS version

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

Change the supported level for the configuration server.   For a description of the possible levels, please refer to UDPCFG documentation.

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.

Supported since or modified in @CHIP-RTOS version

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

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).

Return Value

ES:DI holds old handler (since SC1x RTOS V1.25 / SC1x3/SC2x RTOS V1.20)

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
7: Ethernet link error detected (SC13 only: 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.
10: RTOS memory list corrupted
Error codes in the range[1000..9999] are reserved for Beck drivers or libraries. Currently the following codes are used:
1000: GCLIB - The communication between the IPC@CHIP® and the graphics controller failed. Error codes starting from 10000 can be used by user applications.

In all cases (except error code 7 and 9, driver/library and application codes depend) 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 your exit handler will hang inside the print call when Telnet is part of your stdio.

// Example using Beck C-Library functions:
//   This error handler reboots the system
void huge _pascal user_error_handler(int errorcode)
{
   BIOS_Reboot () ;
}

// Installing the error handler function
//  from program's main function
BIOS_Install_Error_Handler (user_error_handler) ;

Related Topics

Set fatal error record

ERRORS command

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.25	V1.25	V1.25	V1.20	V1.20

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.

Supported since or modified in @CHIP-RTOS version

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

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

Get version number

Get device name

VER shell command

Supported since or modified in @CHIP-RTOS version

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

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)
Pass a NULL pointer here to erase the complete item line

Return Value

AX=0 success
AX=-1 Invalid string length, low heap memory or file error.

Comments

This API is thread safe and reentrant.   This function will fail (no operation) if insufficient system heap memory is available to momentarily hold the contents of the CHIP.INI file.

This API can be accessed through the Beck C-Library function BIOS_Set_Ini_String.   A call to this function with parameters:

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

produces the following chip.ini entry:

    [MY_SECTION]
    MY_ITEM=VALUE_TEXT

Keep in mind that this function writes to the chip.ini file.   This generates flash write cycles and these cycles are limited.

Related Topics

Get CHIP.INI entry

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.20	V1.20	V1.20	V1.05	V1.00

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 or low memory
else Success: pointer at DS:DX contains the found string AX contains length of the found string

Comments

Leading and trailing white space characters will be cut. The function stops reading the entry when it finds an invalid character (<0x20).
This API is thread safe and reentrant.   This function will fail if insufficient system heap memory is available to momentarily hold the contents of the CHIP.INI file.

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.

The Beck C-Library function BIOS_Get_Ini_String can be used to access this API.   Example usage would be as follows:

// Declare a target buffer to be filled by BIOS_Get_Ini_String().
unsigned char target[101];

BIOS_Get_Ini_String("MY_SECTION", "MY_ITEM", target, 100);
// Now target contains the chip.ini text for this item

Related Topics

Set CHIP.INI entry

Supported since or modified in @CHIP-RTOS version

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

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

Supported since or modified in @CHIP-RTOS version

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

Get the IPC@CHIP® device name

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

Get version number

Get version string

Supported since or modified in @CHIP-RTOS version

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

Suspend/Resume FTP, Telnet or Web Server

Parameters

AH

Must be 0x27.

AL

0: Resume, 1: Suspend

SC1x Parameters

BX

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

SC1x3/SC2x Parameters

BX

0: FTP Server, 1: Telnet Server, 2: Web Server, 3: SSL Web Server, 4: SSH 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.

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.02	V1.00	V1.00	V1.07	V1.00

Provide a an access to the file system directories which locks the directory against write activity during the series of search calls.

Parameters

AH

Must be 0x28.

CX

File attribute (provisional, not used)

BX:SI

Null terminated file specification

ES:DI

Pointer to a filefind structure which will be initialized inside this API.

Return Value

AX=   1 DX=0: Success
AX=   0 DX=0: No file found

Comments

The three filefind functions (0x28, 0x29, 0x30) provide a slightly faster Findfirst/next access than the DOS compatible functions at INT 21h.   More importantly, these functions provide a multi-tasking version of the findfirst/findnext functions which protects against changes being made to the file directory within the midst of the search sequence.   The directory being searched will remain locked against write activity until the search is completed (Findfirst/Findnext return with AX equal zero) or until the Finddone API terminates the search.

This function starts an iteration of files found at the path specified in [BX:SI].   This path may contain the * and ? wild card characters.   If this function returns with AX set to 1, it has successfully found a matching file at the specified path.   The Findnext function can then be used to retrieve further matching file names.

This function is reentrant.   However, eventually the system will run out of file system resources (e.g. directory nodes) if too many sessions are simultaneously active.

CAUTION:

The Fast Finddone function must be called if the Findfirst/Findnext sequence is stopped prior to these iteration functions returning with AX equal zero ("File not found").    This is important so that the directory can be unlocked and file system resources released!

SC1x3/SC2x Comments

The alternative directory scan functions for long file names (LFN) starting with LFN Findfirst can be used to read out the long file names.

Related Topics

Fast Findnext

Fast Finddone must be called at end of the search

LFN Findfirst

Supported since or modified in @CHIP-RTOS version

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

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

Parameters

AH

Must be 0x29.

ES:DI

Pointer to filefind structure initialized by the Fast Findfirst function (0x28).

Return Value

AL=  1 DX=0: Success
AX=  0 DX=0: no file found

Comments

This function is reentrant.

See Fast Findfirst function (0x28) for further description.

CAUTION:

The Fast Finddone function must be called if the Findfirst/Findnext sequence is stopped prior to these iteration functions returning with AX equal zero ("File not found").    This is important so that the directory can be unlocked and file system resources released!

Related Topics

Fast Findfirst must be called to start the search

Fast Finddone called at end of the search

Supported since or modified in @CHIP-RTOS version

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

Begin iteration of files listed in specified directory.

Parameters

AH

Must be 0x2A.

AL

non-zero to leave the directory node locked against write activity

BX:SI

Null terminated file path

ES:DI

Pointer to a LFN_filefind structure which will be initialized inside this API.

Return Value

CX=   1: Success
CX=   0: No file found
Carry flag zero (in either case)

Comments

The set of long file name file find functions (0x2A, 0x2B and 0x2C) provide access to the long file names as well as the short [8.3] DOS alias names.   These functions operate roughly similar to the DOS compatible functions at INT 21h when AL parameter is zero.   No directory node lock is performed.

When AL parameter is non-zero, then these functions behave analogous to the so called Fast findfirst BIOS service 0x28 but providing the long file names.   In this case these functions lock the file node (write protect) of the directory being scanned and therefore are protected against directory changes being made during the iteration sequence.   This lock remains in affect until either a "No file found" indication is returned from either this function or Findnext (0x2B), or until the user calls the LFN FindDone API, 0x2C, to terminate the search.

This function starts an iteration of files found at the path specified in [BX:SI].   This path may contain the * and ? wild card characters.   If this function returns with AX set to 1, it has successfully found a matching file at the specified path.   The LFN Findnext function can then be used to retrieve further matching file names.

This function is reentrant.   However, eventually the system will run out of file system resources (e.g. directory nodes) if too many sessions are simultaneously active.   This resource exhaustion with excessive recursion is more likely when the AL non-zero node locking is used.

Note:    The alternative Fast Findfirst / Fast Findnext functions which retrieve only the short alias DOS file names are no faster than this series of long name findfirst/findnext functions.   (Those functions are named "fast" only for historical reasons.)

CAUTION:

System heap memory, and file system resources remain allocated until the user calls LFN FindDone (0x2C) or until either of the LFN FindFirst/FindNext functions return with CX equal zero.   Therefore it is important that the user call the LFN FindDone API if the search is terminated before the FindFirst/FindNext functions reach the "No file found" condition.   Calling the LFN FindDone function for "good measure" after the FindFirst/FindNext functions have returned the zero in CX does no harm (has no affect).

Related Topics

Long File Name Findnext

Long File Name Finddone

Short name "Fast" Findfirst

Supported since or modified in @CHIP-RTOS version

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

Continues a file search which was started by LFN Findfirst (0x2A)

Parameters

AH

Must be 0x2B.

ES:DI

Pointer to LFN_filefind structure initialized by LFN Findfirst call.

Return Value

CX=  1: Success
CX=  0: no file found

Comments

This function is reentrant.

See LFN Findfirst function (0x2A) for further description.

CAUTION:

System heap memory, and file system resources remain allocated until the user calls LFN FindDone (0x2C) or until either of the LFN FindFirst/FindNext functions return with CX equal zero.   Therefore it is important that the user call the LFN FindDone API if the search is terminated before the FindFirst/FindNext functions reach the "No file found" condition.

Related Topics

LFN Findfirst must be called to start the search

LFN Finddone must be called at end of the search

Supported since or modified in @CHIP-RTOS version

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

Terminates a search which was started by LFN Findfirst (0x2A), releasing resources.

Parameters

AH

Must be 0x2C.

ES:DI

Pointer to LFN_filefind structure initialized by LFN Findfirst call.

Return Value

Carry flag zero

Comments

This function releases the system resources required during a directory scan operation.

This function is reentrant.

See LFN Findfirst function (0x2A) for further description.

CAUTION:

System heap memory, and file system resources remain allocated until either the user calls LFN FindDone or either the LFN FindFirst/FindNext functions return with CX equal zero.   Therefore it is important that the user call this LFN FindDone API if the search is terminated before the FindFirst/FindNext functions reach the "No file found" condition.

Related Topics

LFN Findfirst must be called to start the search

LFN Findnext continues search

Supported since or modified in @CHIP-RTOS version

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

Get state of system servers (FTP, Telnet, Web Server etc.)

Parameters

AH

Must be 0x2D.

SC1x Parameters

BX

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

SC1x3/SC2x Parameters

BX

0: FTP Server, 1: Telnet Server, 2: Web Server, 3: SSL Web Server, 4: SSH Server

Return Value

AX=  0:   Server is enabled
AX=  1:   Server is suspended
AX= -1:   Invalid Parameter

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.27	V1.27	V1.27	V1.30	V1.30

Closes a find access started with Fast Findfirst, thereby releasing the lock on the directory that was being searched.

Parameters

AH

Must be 0x30.

ES:DI

Pointer to filefind structure initialized by the Fast Findfirst function (0x28).

Return Value

AX=0 DX=0:   Success

Comments

This function releases the file system resources used during a directory scan operation.

This function is reentrant.

See Fast Findfirst function (0x28) for further description.

Related Topics

Fast Findfirst

Fast Findnext

Supported since or modified in @CHIP-RTOS version

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

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

SC12 Return Value

CX=0

SC13/SC1x3 Return Value

CX holds the current Phy status.

Bit 14   1 = Link Not detected
Bit 07   1 = 100Base-TX mode, 0=10Base-T mode
Bit 06   1 = Device in Full Duplex mode

Supported since or modified in @CHIP-RTOS version

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

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, Paradigm Beck Edition (other compilers??) try to increase their program memory block at runtime.   This can occur, for example, when opening a file with the Borland or Paradigm C-library function fopen, where some additional memory is required.   The 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 equals 16 bytes for SC1x, and 256 bytes for SC1x3 systems).

This value can also be defined in chip.ini.

Note:   This strategy can fail when programs are terminated and restarted again.  
It is not necessary to set this entry if the application doesn't show the described error.   Only if a C-library function call sets errno to 8, should this value be defined.   We recommend in that case a value of 128 paragraphs for SC1x or 8 paragraphs for SC1x3 (2048 bytes in either case).   The described problem was noticed when the Borland or Paradigm C-library function fopen were used.   The same can happen with usage of C-library function malloc using memory model Large.   The malloc returns a NULL pointer in this case.

Supported since or modified in @CHIP-RTOS version

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

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
Bit 4: SSH channel (SC1x3 only)

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

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.02	V1.00	V1.00	V1.07	V1.00

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
Bit 4 == 1: SSH channel (SC1x3 only)

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.02	V1.00	V1.00	V1.07	V1.00

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.
   

This API can be reached using the BIOS_Install_User_Stdio Beck C-Library function.   Example usage of this function is shown below.

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)
{
  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;

  BIOS_Install_User_Stdio ( &user_stdio ) ;
  BIOS_Select_Stdio ( STDIO_COM | STDIO_TELNET | STDIO_USER,
           SET_STDOUT | SET_STDIN) ;
}

void remove_mystdio_channel(void)
{
  BIOS_Select_Stdio ( STDIO_COM | STDIO_TELNET,
           SET_STDOUT | SET_STDIN) ;

  BIOS_Install_User_Stdio ( 0 ) ;
}

int main(void)
{
  //......
  install_mystdio_channel();
  //....

  // at the end of the program
  remove_my_stdio_channel():
}

Supported since or modified in @CHIP-RTOS version

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

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.

ES:DI

Pointer to handler function

SC1x Parameters

BX

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

SC1x3/SC2x Parameters

BX

0: FTP Server, 1: Telnet Server, 2: Web Server, 3: SSL Web Server, 4: SSH Server

Return Value

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

Comments

The connection handler will be called when a client establishes a connection to the server (FTP, WEB, Telnet).
Exemplary 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.

A connection handler function must be declared in the following manner:
int huge UserConnectionHandler( struct sockaddr_in *sockptr );


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).

SC1x Comments

Example handler:
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.)  

int huge UserConnectionHandler( struct sockaddr * SockAddr )
{
    char ip_str[INET_ADDRSTRLEN];
    InetToAscii(&((struct sockaddr_in *)SockAddr)->sin_addr.s_addr
                ,ip_str);
    helper_printf("\r\nHost %s, Port %u",ip_str,
                ((struct sockaddr_in *)SockAddr)->sin_port);
    return 0;
}

SC1x3/SC2x Comments

Example handler:
The handler can read the IP Address and the Port in the sockaddr_storage struct .

int huge UserConnectionHandler( struct sockaddr * SockAddr )
{
  char ip_str[INET6_ADDRSTRLEN];
  struct sockaddr_in ipv4SockAddr;

  if(IN6_IS_ADDR_V4MAPPED(
       &((struct sockaddr_storage *)SockAddr)->addr.ipv6.sin6_addr))
  {
   //IPv4, copy data into  sockaddr_in variable
   ipv4SockAddr.sin_addr.s_addr=((struct sockaddr_storage *)SockAddr)
                               ->addr.ipv6.sin6_addr.ip6Addr.ip6U32[3];
   ipv4SockAddr.sin_port=
         ((struct sockaddr_storage *)SockAddr)->addr.ipv6.sin6_port;
   //Convert to string
   inet_ntop( AF_INET,&ipv4SockAddr.sin_addr,ip_str,INET_ADDRSTRLEN);

   //helper_printf(.........);
  }
  else
  {
    //IPv6: //Convert to string
    inet_ntop( AF_INET6,
              &((struct sockaddr_storage *)SockAddr)
              ->addr.ipv6.sin6_addr,ip_str,INET6_ADDRSTRLEN);
    //helper_printf(...........);
  }
  return 0;
}

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.02	V1.00	V1.00	V1.07	V1.00

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!

Supported since or modified in @CHIP-RTOS version

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

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

Parameters

AH

Must be 0x38.

CX

File handle

ES:BX

Output Parameter:   Pointer to string, must be 13 chars long (12 + Null termination)

Return Value

AX=0: Success
AX=-1: Invalid file handle

Comments

This function is reentrant.

SC1x3/SC2x Comments

The alternative Get LFN function can be used to retrieve the long file names.

Related Topics

Get LFN

Supported since or modified in @CHIP-RTOS version

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

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

Parameters

AH

Must be 0x3A.

CX

File handle

ES:BX

Output parameter:   Pointer to buffer in user memory where up to 259 ASCII characters plus a null terminator will be written.

Return Value

AX=0: Success
AX=-1: Invalid file handle

Comments

On success, the long file name is written to the caller's buffer at [ES:BX].

This function is reentrant.

Related Topics

Get DOS file name

Supported since or modified in @CHIP-RTOS version

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

Set operation mode of the internal ethernet controller. This setting overlays temporarily the CHIP.INI setting ETH_MODE.

Parameters

AH

Must be 0x3B.

CL

Operating mode The internal Ethernet controller is able to operate in different operating modes. Select the following operating modes of the internal Ethernet device:

0: Auto negotiation, Default mode
1: Fixed 010 MBit/s, Half duplex
2: Fixed 010 MBit/s, Full duplex
3: Fixed 100 MBit/s, Half duplex
4: Fixed 100 MBit/s, Full duplex

Return Value

AX contains the current value of the ethernet operating mode

Comments

The setting becomes valid when executing the shell command IPETH , after calling TCPIP interrupt 0xAC service 0x71 (controller hardware restart and IP reconfiguration) or BIOS interrupt 0xA0 service 0x39 (controller hardware restart only)

The current mode could be retrieved by calling this functions with parameter CL>4.

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V1.23	V1.23

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.

Supported since or modified in @CHIP-RTOS version

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

Writes persistent data into the Flash memory of the IPC@CHIP®
To storage non-volatile customer product data a block at the IPC@CHIP flash, independent of the IPC@CHIP® file system is provided. The size of this area for the IPC@ targets SC1x and SC1x3/SC2x is 192 Bytes. Developers of IPC@CHIP-based products can use this block in every way they want, e.g. for programming serial number of their product or other important data.

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

Supported since or modified in @CHIP-RTOS version

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

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

Supported since or modified in @CHIP-RTOS version

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

The indicated memory block is re-assigned to the specified RTOS task.

Parameters

AH

Must be 0x48.

ES:BX

Pointer to the memory block allocated by the RTOS.

CX

RTOS task ID of task to assign this memory block.   You may set this to zero to assign the memory block to the current task that is making this call.

Return Value

Success: AX = 0
Invalid task ID:   AX = -1
Invalid RTOS memory pointer:   AX = -38

Comments

This function can be useful to control the lifespan of a given block of memory.   After the specified task has been assigned ownership of this memory block, this memory block will be automatically released when that task is deleted from the system if the block had not already been released.

A task's stack space allocated from system memory can safely be released in this manner.

Related Topics

Allocate normal RTOS memory

Allocate fast RTOS memory

Delete task

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.23	V1.23	V1.23	V1.12	V1.00

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.

SC1x3/SC2x Comments

This function is deprecated, because it doesn't work, if the PPP server uses the IPv6 protocol.   The IP configuration of all TCPIP/IP devices can be read by using Get_Iface_Entries or Get_IPv6_Iface_Entries.

Supported since or modified in @CHIP-RTOS version

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

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.

SC1x3/SC2x Comments

This function is deprecated, because it doesn't work, if the PPP server uses the IPv6 protocol.   The IP configuration of all TCPIP/IP devices can be read by using Get_Iface_Entries or Get_IPv6_Iface_Entries.

Supported since or modified in @CHIP-RTOS version

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

Get the address of the internal RTOS vsprintf function.

Parameters

AH

Must be 0x56.

Return Value

AX=0
ES:DI points to the internal vsprintf function of the @CHIP-RTOS BX = 0x1 to signal caller that this @Chip-RTOS version supports the direct console output when first argument to the vsprintf function is MK_FP(0, 0x22).   (If BX remains unchanged, then @Chip-RTOS version is older and does not support this feature.)

Comments

This function is used by our C-library to provide a printf function for user applications.   Floating point types are not supported by this vsprintf implementation.

Supported since or modified in @CHIP-RTOS version

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

Allocates memory for the calling process from the fast memory pool.

Parameters

AH

0x57

BX

Size counted in paragraphs

Return Value

Success:

AX holds the segment of the memory area

Failure:

AX = 0, due to not enough memory available.

Comments

A paragraph is 256 bytes in length.

Note:

The software Cryptographic Engine used by SSH, SSL or IPsec will operate noticeably quicker during key negotiation (e.g. Diffie-Hellmann, RSA, DSS) if a block of memory in the fast memory pool is available.   A memory block of roughly 42 Kbyte size is required by the Cryptographic Engine.   If the block is not available in this fast RAM area, then an attempt is made to allocate it from the normal system memory as a last resort.

Beck C-Library Usage

helper_alloc_rtos_fast_mem()

Related Topics

Allocate normal RTOS memory

Free allocated memory

Reassign memory ownership

Supported since or modified in @CHIP-RTOS version

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

Get the MAC address as a 6 Byte array.

Parameters

AH

Must be 0x58.

ES:DX

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

Comments

The second Ethernet controller has no PHY controller.   Only an MII interface is provided.   It is only accessible with an external connected PHY and an external driver program, which must base on the TCPIP device driver API.

Supported since or modified in @CHIP-RTOS version

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

Sets the RTOS' fatal error record

Parameters

AH

0x59

BX

Error code
Codes 0..999 are reserved for the RTOS.
Codes 1000..9999 are reserved for Beck drivers and libraries. (see Install a user fatal error handler)
Codes 10000... can be used for user applications.

CX:DX

Details:
This arbitrary integer value can be used to describe the error more detailed. (CX holds high word)

Return Value

AX = 0: Success
AX = -1: Illegal (reserved) error code

Beck C-Library Usage

BIOS_Set_Error()

Related Topics

Install a user fatal error handler

ERRORS command

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V1.30	V1.30

Check for installed license

Parameters

AH

0x5A

AL

ID of license key

ES:BX

Pointer to secret key

CX

Length of secret key in bytes

Return Value

AX = 0: Success, found a valid license
AX = -1: Error, no valid license for specified ID found
AX = -2: Error, reading product data failed
AX = -3: Error, MD5 functions failed

Beck C-Library Usage

helper_check_license()

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.27	V1.27	V1.27	V1.35	V1.35