Ethernet Packet Driver Interface - SC12 @CHIP-RTOS V1.10
IPC@CHIP Documentation Index
Ethernet: Packet Driver Interface
Packet driver interface definition for direct access to the IPC@CHIP Ethernet device.Packet drivers provide a simple, common programming interface that allows multiple applications to share a network interface at the data link level. The packet driver demultiplex incoming packets among the applications by using the network media's standard packet type. The packet driver provides calls to initiate access to a specific packet type, to end access to it, to send a packet,and to get information about the interface. The implemented services are only a small subset of the common packet driver interface.
The IPC@CHIP RTOS uses interrupt 0xAE with a service number in the high order byte of the AX register (AH) to access the IPC@CHIP Ethernet packet driver. All supported services are listed here.
On return the CPU carry flag is set if an error has occurred. The DH register holds an error code:
-
0x00 NO_ERROR
0x01 BAD_HANDLE // Invalid handle number
0x05 BAD_TYPE // Bad packet type specified
0x09 NO_SPACE // Insufficient space
0x0A TYPE_INUSE // Type already in use
0x0B BAD_COMMAND // Command not supported
0x0C CANT_SEND // Packet couldn't be sent
// (hardware error?).
Important:
-
One important difference to other standard packet drivers is, that the software interrupt 0xAE does not have the typical PKTDRVR
signature at offset 3 in the interrupt source code. So instead of looking for this signature,
use BIOS interrupt 0xA0 function 0x16 to
check if the packet driver interface is available in the IPC@CHIP @CHIP-RTOS.
The maximum number of installed packet handlers is five.
- PKTDRV.C: C-Source for the API calls
- PKTDRV.H: Defines, typedefs, prototypes, ... for the API calls
- REC.C : Example for a receiver handler function, installed with
function ACCESS_TYPE
- SEND.EXE and RCV.EXE (with source): Simple program pair for sending and receiving of Ethernet packets
Interrupt 0xAE service 0x01: DRIVER_INFO, Get Driver Information
- Added only for compatibility
Parameters
- AH
- 0x01
Return Value
- Carry flag: 0, Success:
-
AL: 1, Basic functions present
BX: 0x0B, Version
CH: 0x01, Class
CL: 0x00, Number
DL: 0x36, Type
DH: 0x00, Error code = NO_ERROR
DS:SI : Pointer to the null terminated driver name string, "SC1xPKT"
Related Topics
- ACCESS_TYPE Install Access Handler
Top of list
Index page
Interrupt 0xAE service 0x02: ACCESS_TYPE, Install Access Handler
Parameters
- AH
- 0x02
- AL
- class, from DRIVER_INFO call
- CX
- type length, must be 2!
- DL
- number, from DRIVER_INFO call
- DS:SI
- Pointer to the desired packet type, e.g. 0x800 for IP
(The object pointed to here must be persistent, not a momentary value.) - ES:DI
- Vector to user's receiver handler function for this packet type
Return Value
- Carry flag: 0 Success, AX contains the handle number (needed for
RELEASE_TYPE call)
Carry flag :1 Failure, DH contains error code
Comments
- We support the following Ethernet frame format (802.3):
48 Bits (6 Bytes) Destination address
48 Bits (6 Bytes) Source address
16 Bits (2 Bytes) Type field e.g 0x0608 for ARP, 0x0008 for IP or user defined types
46 to 1500 Bytes of user data.The maximum number of installed handlers is limited to five. In all BIOS versions except the TINY version, setting of ARP or IP handlers is not allowed here.
When an Ethernet packet of the type specified here at [DS:SI] is received by the IPC@CHIP's network device driver, this driver will perform callbacks to the receiver handler function specified here in [ES:DI]. This callback will be done twice per accepted packet:- First call:
-
Input parameters to your handler: AX = 0, CX = received packet length
Return Value from your handler: ES:DI - Pointer to buffer where driver can load the CX received bytes.
- Second call:
-
Input parameters to your handler: AX = 1, data is now ready in your buffer
Return Value from your handler: -- none --
On the first call, your handler produces a buffer into which the driver can transfer the received packet. This byte transfer occurs between the two calls to your handler function.
Important:
-
Because of our Little Endian processor you must exchange the bytes for the
packet types e.g. use 0x0008 for the IP type instead of 0x0800.
Simple example of an receiver callback function: - First call:
void interrupt receiver (unsigned bp, unsigned di, unsigned si,
unsigned ds, unsigned es, unsigned dx,
unsigned cx, unsigned bx, unsigned ax,
unsigned ip, unsigned cs, unsigned flags )
{
if (ax == 0) // ax==0 -> Packet driver asks for a buffer, give it at es:di
{
es = FP_SEG(&receivepacket);
di = FP_OFF(&receivepacket);
}
if (ax == 1) //Packet driver has filled our provided buffer
{
//Call our external c-function packet_receive to process the received data
packet_received(cx);
}
} |
Related Topics
- RELEASE_TYPE Unload an Access Handler
- INSTALL_WILDCARD Install wildcard access handler
Top of list
Index page
Interrupt 0xAE service 0x03: RELEASE_TYPE, Unload an Access Handler
- The user installed Ethernet packet type access handler is removed.
Parameters
- AH
- 0x03
- BX
- Handle from
ACCESS_TYPE call 0x02
Return Value
- Carry: 0, AX:0, DX:0: success
Carry: 1, DH contains error code
Related Topics
- ACCESS_TYPE Install Access Handler
Top of list
Index page
Interrupt 0xAE service 0x04: SEND_PKT, Send an Ethernet packet
- Send bytes in provided packet buffer over Ethernet.
Parameters
- AH
- 0x04
- CX
- Length of packet
- DS:SI
- Pointer to packet buffer
Return Value
- Carry flag:0, AX:0, DX:0: success
Carry flag:1, DH contains error code
Comments
- The data packet buffer should have the Ethernet packet form defined
by IEEE 802.3:
typedef struct MY_PACKET_
{
unsigned char dest[6]; // Destination MAC address
unsigned char src[6]; // Source MAC address
unsigned int type; // Packet type (big endian)
unsigned char data[DATA_SIZE];
} MY_PACKET ;
where DATA_SIZE can range up to 1500 bytes.
The src field can be set using the GET_ADDRESS API.
Related Topics
- GET_ADDRESS Get the Ethernet address
Top of list
Index page
Interrupt 0xAE service 0x06: GET_ADDRESS, Get the IPC@CHIP Ethernet address
- Get the IPC@CHIP Ethernet address.
Parameters
- AH
- 0x06
- ES:DI
- Pointer to user buffer (6 bytes), for storing the Ethernet address
Return Value
- Carry flag:0, AX:0, DX:0: success
Location at [ES:DI] contains the six bytes of the Ethernet address.
Top of list
Index page
Interrupt 0xAE service 0x14: SET_RCV_MODE, Set receive mode
- Set receive mode of IPC@CHIP Ethernet device.
Parameters
- AH
- 0x14
- CX
- Receive mode
-
3: Receiving packets with own Ethernet address or broadcast address
6: Promiscuous mode (receive all)
Return Value
- Carry flag:0, AX:0, DX:0: success
Carry flag:1, AX:-1;DX:-1 Bad parameter in CX
Comments
- Default receive mode is 3.
Receive mode 6 should only be used in the IPC@CHIP Tiny version (@Chip-RTOS without the TCP/IP stack).
Calling SET_MULTICAST overrides the current mode with mode 5.
API call Get receive mode returns the current mode.
Related Topics
- GET_RCV_MODE Get receive mode
Top of list
Index page
Interrupt 0xAE service 0x15: GET_RCV_MODE, Get current receive mode
- Get current receive mode of the Ethernet device.
Parameters
- AH
- 0x15
Return Value
- Carry flag:0, AX:3 accept any incoming packet with own address or broadcast address
AX:5 accept any incoming packet with own address, broadcast address or installed multicast addresses
AX:6 accept all incoming packets Carry flag:1, DH contains error code
Related Topics
- SET_RCV_MODE Set receive mode
- SET_MULTICAST Set Ethernet multicast address
Top of list
Index page
Interrupt 0xAE service 0x16: SET_MULTICAST, Set Ethernet multicast address
- Set Ethernet multicast address.
Parameters
- AH
- 0x16
- ES:DI
- Pointer to multicast MAC address buffer 6 bytes
- CX
- length of ES:DI buffer, must be 6
Return Value
- Carry flag:0, AX:0, DX:0: success
Carry flag:1, DH contains error code
Related Topics
- DEL_MULTICAST Remove Ethernet multicast address
Developer Notes
The address will be installed inside the Ethernet device of the IPC@CHIP.
A maximum of 64 addresses can be installed.Interrupt 0xAE service 0x27: DEL_MULTICAST, Remove Ethernet multicast address
- Remove the Ethernet multicast address.
Parameters
- AH
- 0x27
- ES:DI
- Pointer to multicast MAC address buffer 6 bytes
- CX
- length of ES:DI buffer, must be 6
Return Value
- Carry flag:0, AX:0, DX:0: success
Carry flag:1, DH contains error code
Related Topics
- SET_MULTICAST Set Ethernet multicast address
Top of list
Index page
Interrupt 0xAE service 0x28: INSTALL_WILDCARD, Install wildcard access handler
- Installs a wildcard packet type access handler.
Parameters
- AH
- 0x28
- AL
- class, from DRIVER_INFO call
- CX
- type length, must be 2!!
- DL
- number, from DRIVER_INFO call
- DS:SI
- Pointer to the desired packet type, e.g. 0xFFFF for
accepting any incoming Ethernet packet
(The object pointed to here must be persistent, not a momentary value.) - ES:DI
- Vector to user's receiver handler function for this packet type
Return Value
- Carry flag: 0 Success, AX contains the handle number
Carry flag :1 Failure, DH contains error code
Comments
- Any incoming Ethernet packet will be accepted for which one or more
bits of the packet type matches to the bits of the installed
wildcard packet type.
If a packet type of 0xFFFF is installed, any incoming packet will be accepted.
Only one wildcard can be installed at a time. Installing a new wildcard type overwrites the previous.
Delete a wild card handle by installing a wildcard with the packet type 0x0000. "Normal" handlers installed with ACCESS_TYPE API are not overwritten by installing a wildcard
Related Topics
- ACCESS_TYPE Install Access Handler
Top of list
Index page
End of document