EBIOS Reference Guide

Saturday, 06 June 2009 12:02 Shael
Print
This article provide information relating to the EBIOS support functions and data structures. Currently the network API is accessed via a jump table located in ADL memory in the EBIOS (extended BIOS). Each of the jump table entries in the EBIOS is five bytes in size. The jump table is located in the EZ80 source assembler file "eZ80-CPM-BIOS.inc". The base address for EBIOSjumptable is010800h.

Structures:

A number of EBIOS support functions use structures to pass information. These stuructures are currently used in the EBIOS;

String:

A mutilbyte ANSI string of one byte characters with a prefix byte indicating the number of ANSI characters in the string. The maximum size of a string is 255 characters. IP dotted decimal notation strings are 16 bytes in size allowing for 15 characters. Host name strings are 64 bytes in size and allow for up to 63 characters in a host name. A domain name used for a DNS request can be a maximum of 256 bytes with the name string having up to 255 characters.

IpConfigParams:

A structure made up of five 4 byte IP addresses followed by a 6 byte MAC addresss. This structure is used with the "IpConfig" and "IpGetConfig" support functions.

UdpAddress:

A UDP address structure is composed of a two byte port number followed by a four byte IP address for a total size of 6 bytes.

Error Codes:

Phy/EMAC initialization result codes;

0 = PhyInitOk

1 = PhyNotFound

2 = PhyNoLnk

3 = PhyNoSig

4 = PhyNoInit, the emac/phy was never initialize.

5 = PhyIsInit, the emac/phy is already initialized.

EMAC transmit packet result codes;

0 = E_EEmacTxOk, packet sent.

1 = E_EEmacTxNoData, zero length packet.

2 = E_EEmacTxToBig, packet to large to send.

ARP result codes;

0 = A_EIpToAdOk, address resolved.

1 = A_EIpToAdFail, address can not be resolved.

2 = A_EIpToAdResolved, address is being resolved.

IP/UDP result codes;

0 = E_IpTxOk, packet sent

1 = E_IpTxNoData, zero length packet.

2 = E_IpTxToBig, packet to large to send.

3 = E_EIpResolve,unable to resolve address, bad IP address.

4 = E_EIpResolving, unable to resolve address, attempting to resolve.

5 = E_EIpTxFifoFull, the tx fifo is full, try later.

6 = E_EEmacClosed, the emac device is not active.

7 = E_ESocketClosed, the specidied socket is not open.

8 = E_ESocketOpen, the port is already in use.

9 = E_ESocketNone, the max number of sockets is open.

 

Support Functions:

The EBIOS contains a number of support functions to allow user programs access to the IP stack. The EBIOS is not re-enterent and care should be taken that any functions called from a hardware interrupt use an IRQ priority lowwer then the EMAC and Timer0 IRQs priority.

IpConfig (010800h)

This function is used to set the IP address, subnet mask, gateway, and dns address. This function updates the current ip configuration from a config structure. The function automatically calculates the network, broadcast addresses. If the gateway address is '0.0.0.0' or not on the local subnet the gateway will not be used. In this case IP Addresses not on the local subnet will not resolve.

On Entry:

HL = (24 bit) address of a config structure.

The structure contains:

0...3 -- IP address.

4...7 -- subnet mask.

8..11 -- gateway ip address.

12..15 -- primary dns ip address.

16..19 -- secondary dns ip address.

20..25 -- emac station address.

On Exit:

all registers are preserved

IpGetConfig (010805h)

This function reads the current ip configuration to a config structure.

On Entry:

HL = (24 bit) address of a config structure

On Exit:

all registers are preserved

IpIsInit (01080A)

This function is used to read the current emac state.

On Exit:

A = current emac state. A = 0 the ip layer is running, A != 0 IP layer stoppped.

IpInit (01080Fh)

This function Initializes the IP layer. The duplex/speed settings are saved to there corresponding variables.

On Entry:

H = 0 use half-duplex. H != 0 use full duplex.

L = 0 use 10mbs, L != 0 use 100mbs.

On Exit::

A = 0 ok. A != 0 emac/phy error.

IpDone (010814h)

This function stops the emac/phy hardware. All open UDP sockets are closed. There are no parameters for this support function. The emac state variable is updated to PhyNoInit = 4.

E_SndPing (010819h)

Send an ICMP Echo request.

On Entry:

HL = points to the IP4 address to send echo request to.

DE = number of data bytes to send with the echo request.

On Exit:

A = 0 request send, A != 0 ping failed to send,

error codes same as IpSndPkt.

HL = Echo Ident sent in the ICMP echo request header.

E_GetEchoId (01081Eh)

Read the last echo responce ident (16 bits) into HL upper 8 bits of 24 bit HL are not valid.

On Exit:

HL (16 bit) contains last echo identifier number.

E_UdpOpenSkt (010823h)

This function opens a udp socket. If DE = 0 then a port number will be auto allocated. If global enable broadcast flag is off (E_AllowBroadCast = 0) and A != 0 global flag to allow broadcast packets is enabled.

On Entry:

A = enable broadcast packets. A = 0 - no broadcast packets, A != 0 receive broadcast.

DE = (16 bit) UDP port number for socket.

On Exit:

if A less then 255 then A = socket index.

if A = 255 specified socket is in use or no sockets available.

E_UdpCloseSkt (010828h)

This function closes a udp socket.

On Entry:

A = (8 bit) index of UDP socket to close.

On Exit:

all registers are preserved.

E_UdpCloseSkts (01082Dh)

This function closes all openudp sockets. The function requires no parameters.

On Exit:

all registers are preserved.

E_UdpRead (010832h)

This function read a UDP packet from the RX fifo.This function is only called from the user level.EMAC IRQs are disabled during the read.

On Entry:

A = index of socket to read

HL = address of buffer to copy packet into.

BC = max bytes to copy.

On Exit:

A = 0 -- data read, A = 1 -- buffer to small, A = 2 -- Fifo is empty.

BC = number of bytes returned in supplied buffer.

E_UdpPeer (010837h)

This function returns the remote port/ip address of the last packet that was received. The 6 byte address is returned as; a two byte integer port number, and a four byte ip address. The port number is returned in network order, the ip address in network order, high byte first.

On Entry:

A = socket index to check.

HL = (24 bit) address of a 6 byte buffer to hold Port/IP address.

On Exit:

all registers are preserved.

E_UdpReadFrm (01083Ch)

This function read a UDP packet from the RX fifo. This function is only called from the user level. EMAC IRQs are disabled during the read.

On Entry:

A = index of socket to read

HL = address of buffer to copy packet into.

BC = max bytes to copy.

DE = address of six byte from address structure. 0..1 port, 2..7 IP4 address.

On Exit:

A = 0 -- data read, A = 1 -- buffer to small, A = 2 -- Fifo is empty.

BC = number of bytes returned in supplied buffer.

E_UdpSend (010841h)

This function sends a block of bytes as a UDP packet.

On Entry:

A = UDP socket index.

HL = (24 bit) Source buffer adddress.

BC = (16 bit) Source buffer byte count.

On Exit:

A = 0, packet was sent.

A != 0, packet could not be sent.

E_UdpSendTo (010846h)

This function sends a block of bytes as a UDP packet to a specified address.

On Entry:

A = UDP socket index.

HL = (24 bit) Source buffer adddress.

BC = (16 bit) Source buffer byte count.

DE = (24 bit) to address structure (6 bytes). The 6 byte to address is; two byte integer port number, and a four byte ip address.

On Exit:

A = 0, packet was sent.

A != 0, packet could not be sent.

IpSetDhcpAdr (01084Bh)

This function updates the current DHCP server address from a 4 byte buffer.

On Entry:

HL = (24 bit) address of a 4 byte IP address buffer to copy.

On Exit:

all registers are preserved.

IpGetDhcpAdr (010850h)

This function reads the current DHCP server address to a 4 byte buffer.

On Entry:

HL = (24 bit) address of a 4 byte IP address buffer.

On Exit:

all registers are preserved.

IpSetHostName (010855h)

This function updates the current host name and length from a buffer. The first byte is the length of the name up to E_HostMaxLen bytes long followed by the name string.

On Entry:

HL = (24 bit) address of a (E_HostMaxLen + 1) byte string buffer that contains a length byte followed by the host name.

On Exit:

all registers are preserved.

IpGetHostName (01085Ah)

This function reads the current host name and length into a buffer. The first byte is the length of the name up to E_HostMaxLen bytes long followed by the name string.

On Entry:

HL = (24 bit) address of a (E_HostMaxLen + 1) byte string buffer.

On Exit:

all registers are preserved.

RES_StrToIp4 (01087Dh)

This function convers an IP4 dotted notation formatted string into a four byte IP4 address with the bytes inn network order. IP4 formatted strings can have a max length of 15 character. The first byte of a string is the length of the string.

On Entry:

HL = 24 bit memory address of string (first byte is length).

DE = 24 bit memory address of 4 byte IP4 address buffer to receive value.

On Exit:

A = 0 if no error, A != 0 error invalid address.

RES_ExStrToIp4 (010882h)

This function converts a partial IP4 dotted notation string to an IP4 address. The missing higher octets are filled in using the current system IP address. At a minumum one octet must be provided. The first character of the partial IP4 dotten notation string may be a '.' if so it is gnored.

On Entry:

HL = 24 bit memory address of string (first byte is length).

DE = 24 bit memory address of 4 byte IP4 address buffer to receive value.

On Exit:

A = 0 if no error, A != 0 error invalid address.

RES_ResFirst (010887h)

This function converts a string to an IP4 address. If the suplied string is in dotted decimal format it is converted to an IP4 address. if the string is not a dotted decimal string it is assumed to contains a domain name. A DNS request is made for the "A" records for the supplied domain name. If more then one DNS "A" record is returned this function returns the first IP4 address in the DNS responce. Call the RES_ResNext to read any additional addresses returned. A domain name string can have a max length of 255 chars and the first byte is the string length. The function reads the DNS server address from the "Emac.inc" unit variable E_Dns1Ip4Addr. The port is set to 53.

On Entry:

HL = 24 bit pointer to the domain name string.

DE = 24 bit pointer to a IP4 address (4 bytes).

On Exit:

A = 0 if valid responce, A != 0 failed with an E_Net error.

RES_ResNext (01088Ch)

This function is called after calling the RES_ResFirst function to read any additional IP4 addresses found. The function is called until it indicated all addresses have been read. One address is returned at a time.

On Entry:

HL = 24 bit pointer to a IP4 address (4 bytes).

On Exit:

A = 0 if address copied, A != 0 no more addresses in buffer.

RES_MacToStr (010891h)

This function convert an ENET MAC address (6 bytes) to a 17 character string. The MAC address is written in dashed hex format. (ex: AF-00-23-45-9C-A0). The first byte of the string is the length of the string.

On Entry:

HL = 24 bit address of first byte (length byte) of string to write.

DE = 24 bit address of 6 byte MAC address (in Network order).

On Exit:

all registers are preserved.

RES_StrToMac (010896h)

This function converts an ENET MAC hex digit dashed notation string into a six byte MAC address with the bytes in network order. MAC formatted strings have a length of 17 character. The first byte of a string is the length of the string. (ex: A0-22-DF-22-9E-C0).

On Entry:

HL = 24 bit address of first byte (length byte) of string to write.

DE = 24 bit address of 6 byte MAC address (in Network order).

On Exit:

A = 0 if no error, A != 0 error invalid mac address string.

 

Last Updated on Tuesday, 12 January 2010 04:25