www.beck-ipc.com

@CHIP-RTOS - Ethernet Packet Driver Interface


    IPC@CHIP® Documentation Index

Ethernet: Packet Driver Interface

API definition for access the ethernet device 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.

  • 0x01:_DRIVER_INFO, Get Driver Information
  • 0x02:_ACCESS_TYPE, Install Access Handler
  • 0x03:_RELEASE_TYPE, Unload an Access Handler
  • 0x04:_SEND_PKT, Send an Ethernet packet
  • 0x06:_GET_ADDRESS, Get the IPC@CHIP® Ethernet address
  • 0x14:_SET_RCV_MODE, Set receive mode
  • 0x15:_GET_RCV_MODE, Get current receive mode
  • 0x16:_SET_MULTICAST, Set Ethernet multicast address
  • 0x27:_DEL_MULTICAST, Remove Ethernet multicast address
  • 0x28:_INSTALL_WILDCARD, Install wildcard access handler


  • 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.
      Source code examples for the usage of the packet interface can be found at www.beck-ipc.com.



    Interrupt 0xAE service 0x01:     DRIVER_INFO, Get Driver Information

    Provided 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

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00n/aV0.90V1.00

    Top of list
    Index page
    Interrupt 0xAE service 0x02:     ACCESS_TYPE, Install Access Handler

    Parameters

    AH
    0x02

    CX
    type length, must be 2!

    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
      5    BAD_TYPE      - Type not allowed or CX was not set to 2.
      9    NO_SPACE      - Limit of 5 accesses reached
      10   TYPE_INUSE    - The type is already accessed

    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.   If this pointer is NULL then no second call will be made by the driver and the packet will be discarded.

    • Second call:
        Input parameters to your handler: AX = 1, CX = received packet length and 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.

    SC1x3/SC2x Comment
      For SC1x3/SC2x systems, the Ethernet packet is immediately available on the first callback, where AX is zero.   A pointer to this packet is passed to the callback in registers [DX:SI].   This referenced packet buffer is volatile and is only valid up to the return from your callback, so you must make a copy of the packet data inside your callback if you want the data.   Return with register ES set to zero if you do not want a second call performed following a copy operation to a buffer at [ES:DI].    When you set ES to zero, no copy operation is performed by the @Chip-RTOS.

      Note that the two callback operation may still be used in same manner as for the SC1x systems, if desired.   It is not necessary that you use this additional "packet at [DX:SI]" feature which is available only on the SC1x3/SC2x targets.

    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:

                
    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
      {            // We provide the buffer at ES:DI
                   // If the application has no buffer avail, es, di must be set to zero
        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

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00n/aV1.05V1.00

    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

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00n/aV0.90V1.00

    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 (min. length 60)

    DS:SI
    Pointer to packet buffer

    Return Value

    Carry flag:0, AX:0, DX:0: success
    Carry flag:1, DH contains error code
      12    CANT_SEND    - Send failed

    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

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00n/aV0.90V1.00

    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.

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00n/aV0.90V1.00

    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: 0x0B00 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

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00n/aV0.90V1.00

    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

    Related Topics

    SET_RCV_MODE Set receive mode
    SET_MULTICAST Set Ethernet multicast address

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00n/aV0.90V1.00

    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
      9    NO_SPACE    - CX was not set to 6.

    Comments

    The address will be installed inside the Ethernet device of the IPC@CHIP®.   A maximum of 64 addresses can be installed.

    Related Topics

    DEL_MULTICAST Remove Ethernet multicast address

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00n/aV0.90V1.00

    Top of list
    Index page
    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

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00n/aV0.90V1.00

    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

    CX
    type length, must be 2!!

    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 5 due to CX was not zero
      5    BAD_TYPE      - Input parameter CX was not set to 2.

    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

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00n/aV0.90V1.00

    Top of list
    Index page


    End of document